The Wensity MCP server.

@wensity/mcp connects your AI coding agent to Wensity. Ask Claude Code, Cursor, VS Code, or Codex for "animated testimonials" or "a pricing section" and the agent can search the live Wensity library, explain what an item does, check what your machine can install, show you an installation plan, and then install exactly that plan into your project.

It runs on your machine over stdio, started by your MCP client with npx. It complements the Wensity CLI: both use the same install engine and write the same files, so an install from your agent matches npx wensity add.

What it does

Requirements

• Node.js 20 or newer, with npx on your PATH.
• An MCP client that starts local stdio servers: Claude Code, Cursor, VS Code with GitHub Copilot agent mode, Codex, or any other.
• For installs: a React 18+ project. Wensity is built for Next.js and Tailwind CSS v4; run npx wensity init once if the project has no wensity.json.
• No account and no token for free items.

Set up your client

Each snippet pins an exact version, @wensity/mcp@0.1.0. That is deliberate: this server can write files into your project and run your package manager, so you choose when a new version gets those capabilities. See Updating.

The formats below were checked against each client's official documentation on 2026-10-11.

Claude Code

Add the server to the current project from a terminal:

claude mcp add --transport stdio --scope project wensity -- npx -y @wensity/mcp@0.1.0

That writes .mcp.json in the project root. You can also create the file yourself:

1{
2"mcpServers": {
3  "wensity": {
4    "command": "npx",
5    "args": ["-y", "@wensity/mcp@0.1.0"]
6  }
7}
8}

Claude Code asks you to approve a project server from .mcp.json the first time. Drop --scope project to add it for yourself only.

Cursor

Create .cursor/mcp.json in the project, or ~/.cursor/mcp.json to use it in every project:

1{
2"mcpServers": {
3  "wensity": {
4    "command": "npx",
5    "args": ["-y", "@wensity/mcp@0.1.0"]
6  }
7}
8}

Then open Cursor Settings, find the server under MCP, and make sure it is enabled.

VS Code

VS Code uses servers, not mcpServers. Create .vscode/mcp.json in the workspace:

1{
2"servers": {
3  "wensity": {
4    "type": "stdio",
5    "command": "npx",
6    "args": ["-y", "@wensity/mcp@0.1.0"]
7  }
8}
9}

Start the server from the code lens VS Code shows in that file, then use it from Copilot Chat in agent mode.

Codex

Codex reads TOML, not JSON. Add the server from a terminal:

codex mcp add wensity -- npx -y @wensity/mcp@0.1.0

Or add the table to ~/.codex/config.toml yourself. A trusted project can also use .codex/config.toml.

1[mcp_servers.wensity]
2command = "npx"
3args = ["-y", "@wensity/mcp@0.1.0"]

Other clients

Any client that starts a local stdio server works. Give it the command npx with the arguments -y and @wensity/mcp@0.1.0, in whatever format that client documents. No environment variables are needed for free items.

Check the connection

Restart the client (or reload its MCP servers), then ask:

1Use the Wensity MCP server. Is it connected, and which Wensity tools do you have?

The agent should list six tools whose names start with wensity_. The first start can take a few seconds while npx downloads the package.

Authentication

Free components, primitives, and blocks need nothing. Pro items need a token from an account with an active Pro license, saved on your machine by the Wensity CLI:

1. Create a token at ui.wensity.com/dashboard/tokens.
2. In a terminal, run npx wensity login and paste the token at the prompt.
3. Ask your agent again. The MCP server reads the credential the CLI saved; there is nothing to restart.

npx wensity login

The CLI saves the token to ~/.config/wensity/credentials.json (or under $XDG_CONFIG_HOME/wensity/) with 0600 permissions, readable only by your user. A token is only ever sent to the Wensity origin it was issued for. To revoke one, delete it on the tokens page; it stops working on the next request. Run npx wensity logout to remove the saved file. More on tokens in the API tokens guide.

Free, Pro, and Needs Pro

Every item your agent shows you carries one of three labels:

Pro items are never hidden, so you can see everything Pro includes. When you pick a Needs Pro item, the agent says so before planning and suggests a free alternative when there is one.

To unlock Needs Pro items: if you already have Pro, run npx wensity login in a terminal. If you do not, see pricing. One Pro license unlocks every Pro component and block. The label is a hint; the Wensity API decides access again when you plan and when you install.

If the agent reports that your token was rejected (invalid, revoked, or its user deleted), that is not a Pro problem: create a new token and run npx wensity login again.

Example prompts

• Find a Wensity component for animated testimonials.
• List all Wensity primitives.
• What does the Wensity <slug> component do, and what are its dependencies?
• Show me Wensity hero sections that are free.
• Which Wensity components use framer-motion?
• Plan installing <slug> into this project, show me the plan, and wait for my OK.
• Install it.

Replace <slug> with an item from a search result. After an install, ask "show me the code" and the agent reads the installed file from your project.

The six tools

Your agent picks these on its own. Five only read; wensity_install is the only one that changes your project, and your client marks it as a write so it can ask you first. There are no MCP resources or prompts.

How an install works

1. The agent calls wensity_plan_install. Source is downloaded into the server process only, run through the same engine as npx wensity add, and dropped. Nothing in your project changes.
2. The agent shows you the plan: the files, the dependency command, and the caveat that package-manager changes are not rolled back. You decide.
3. The agent calls wensity_install with the plan token. Plans expire after 10 minutes and run at most once.
4. Under a lock in .wensity-tmp/, the server downloads the source again (so access is checked again), confirms nothing changed since the plan, writes the files, and runs the planned command without a shell.

If anything changed since the plan (a file you edited, a new dependency, a different package manager), the install stops with nothing written and the agent plans again. If a write fails, every file is restored. Running the same install again reports that the item is already installed and changes nothing.

.wensity-tmp/ is removed after every install. Do not commit it.

New components appear automatically

The server contains no list of Wensity items. Every search asks the live site, so a component or block published to Wensity shows up for you within about a minute or two, with nothing to update, reinstall, or restart. The same goes for new categories, changed descriptions, changed dependencies, and items that move between Free and Pro.

A new version of @wensity/mcp is only needed when the server itself gains a new capability, such as a new tool.

Updating

Your configuration pins an exact version. To update, change the version in your client configuration and restart the client:

1"args": ["-y", "@wensity/mcp@0.1.0"]

There is nothing to uninstall first: npx fetches the version you name.

The update notice. When a newer version is out, the agent passes on a one-time message such as:

1A newer Wensity MCP (0.2.0) is available; you're on 0.1.0. Change `@wensity/mcp@0.1.0` to `@wensity/mcp@0.2.0` in your MCP config and restart your editor. No reinstall needed.

That is the whole change: one version number in your config. The server never updates itself, never edits your config, and keeps working while you decide. If a version is ever marked unsupported, the notice says so, and some installs may fail until you change it.

Uninstalling

1. Remove the wensity entry from your client configuration (or run claude mcp remove wensity, or codex mcp remove wensity), then restart the client.
2. Optionally run npx wensity logout to delete the saved credential.
3. Files the server installed are ordinary source files in your project. Keep or delete them like any other code.

Configuration

Nothing is required. These environment variables go in the env block of your client configuration when you need them:

Privacy

• The server sends no analytics or telemetry and contacts no host other than the Wensity API.
• Requests carry a User-Agent of wensity-mcp/<version> and an X-Wensity-Client: mcp header, covered by Wensity's normal server logs.
• Your search queries, file contents, and project paths are never logged, and nothing about your project is sent to Wensity. Project inspection is local.
• Component source is never returned to the AI agent and never cached. It goes from the Wensity API into your project files during an install.

Security

• Authenticate only in a terminal with npx wensity login. No tool accepts a token.
• The credential file lives at ~/.config/wensity/credentials.json with 0600 permissions. Revoke a token on the tokens page.
• Package-manager operations are not transactional and may run dependency lifecycle scripts. The exact command is shown in the plan before it runs.
• Pin an exact version (see Updating).

To report a vulnerability, email hey@wensity.com with "Security" in the subject. Please report it privately by email and don't post the details publicly. We acknowledge reports within 3 business days and ask for up to 90 days to fix an issue before it is disclosed publicly.

Rate limits

You will rarely get near them: the server keeps the catalog in memory for 60 seconds, so a burst of searches makes one request. When a limit is hit, the agent is told how long to wait.

Known limitations

1. The Wensity credentials file is plaintext at mode 0600 — the same as the CLI and most developer tools.
2. Never paste a Wensity API token into an AI conversation or a tool argument. Authenticate with npx wensity login in a terminal; the Wensity MCP server reads the credential the CLI wrote and provides no way to submit a token through the model.
3. The Wensity MCP server does not return component source to the AI agent. Source is written to your project during installation, after which your agent can read it like any other file.
4. Package-manager operations are not rolled back. Wensity's own file writes are rolled back on a handled failure, but package.json, the lockfile, node_modules, and any dependency lifecycle scripts are not. The exact command is always shown before it runs.
5. Wensity's file writes are not crash-safe. If the process is killed (SIGKILL, power loss, a container stop), an installation can be left incomplete. Wensity detects this on the next run and blocks with a recovery message listing the journal path, the affected files, and which backups exist. Do not delete a .wensity-tmp journal that Wensity has reported — it may hold the only copy of your original file. Follow the recovery steps, verify with git diff, then delete it.
6. On Windows, replacing an existing file is not guaranteed to be atomic. Wensity always writes a backup before attempting a replacement, so recovery remains possible either way.
7. Pin an exact @wensity/mcp version in your client configuration. This server can write files into your project and run your package manager; @latest would grant those capabilities to an unreviewed release on every launch. To update, bump the pinned version and restart your client.
8. The MCP server sends no separate analytics or telemetry requests and contacts no host other than the configured Wensity API origin. Normal Wensity API requests include the documented User-Agent and X-Wensity-Client: mcp identifier and are covered by Wensity's existing server-side logging and retention policy.
9. JavaScript-only projects receive .tsx files, because Wensity source is TypeScript.
10. Templates cannot be installed through MCP.
11. Free component source updates become visible after a Wensity deploy (the public source route is statically generated).
12. Renamed or removed items do not redirect; a removed slug returns "not found" with suggestions.
13. Block metadata does not include an npm dependency list, so dependency search filters components only. Block dependencies are resolved and shown at plan time.
14. wensity_get_item returns the item's description, dependencies, usage snippet, and props — not its code examples. Those are rendered on the linked detail page.
15. Formatting and type-checking after installation are your agent's responsibility.

Troubleshooting

The server does not appear, or shows as failed

Run npx -y @wensity/mcp@0.1.0 in a terminal. It should wait silently for input (press Ctrl+C to stop). If it errors, check node --version is 20 or newer and that npx works. Then restart the client, and in Claude Code run /mcp, or claude mcp list from a terminal. The first start downloads the package and can be slow; in Codex, raise startup_timeout_sec in the [mcp_servers.wensity] table if it times out.

"Needs Pro" on an item you paid for

Run npx wensity whoami in a terminal. If it shows no Pro plan or no saved token, run npx wensity login with a token from the account that holds the license. The server rechecks your access at most once a minute, so ask again after a moment.

"Token rejected" or "create a new token"

The saved token is invalid, revoked, or belongs to a deleted user. Create a new token on the tokens page and run npx wensity login again in a terminal.

The agent picks the wrong project, or says the project is ambiguous

The server looks for your project in this order: a path the agent passes, WENSITY_MCP_PROJECT_PATH, a workspace root your client shares, then the directory the client started it in. It never guesses your home directory. Ask the agent to pass your project path, or set WENSITY_MCP_PROJECT_PATH in the client configuration.

"Plan stale" or "plan expired"

Something changed since the plan was made, or more than 10 minutes passed. Ask the agent to plan again. Nothing was written.

"Recovery required"

A previous install was interrupted. Follow the numbered steps in the message, check git diff, and only then delete the .wensity-tmp journal it names. See limitation 5 above.

"Installed with a dependency failure"

The files were written but the package-manager command failed. Run the command shown in the result yourself; the files stay in place.

"Rate limited" or "network error"

Wait the number of seconds the agent reports and retry. After several failures in a row the server pauses for 30 seconds instead of hanging your agent.