> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versuno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Configure the Versuno MCP server in any MCP-compatible client.

The Versuno MCP server is distributed on npm as [versuno-mcp](https://www.npmjs.com/package/versuno-mcp). You don't install it manually. Your MCP client launches it on demand via `npx`.

## Requirements

* Node.js 18 or newer on your machine.
* A Versuno API key. Create one at [versuno.ai/settings/api-keys](https://versuno.ai/settings/api-keys).

## The universal config

Every MCP client uses some variation of the same config block:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "versuno-mcp"],
  "env": {
    "VERSUNO_API_KEY": "uk_live_xxx"
  }
}
```

The `-y` flag tells `npx` to auto-install without prompting. Subsequent runs use the cached binary.

## Remote (hosted HTTP) server

Don't want to run anything locally? Versuno also hosts the MCP server over Streamable HTTP at `https://mcp.versuno.ai/mcp`. Instead of `npx`, point your client at the URL and send your API key as a bearer token:

```json theme={null}
{
  "mcpServers": {
    "versuno": {
      "url": "https://mcp.versuno.ai/mcp",
      "headers": {
        "Authorization": "Bearer uk_live_xxx"
      }
    }
  }
}
```

For Claude Code:

```bash theme={null}
claude mcp add --transport http versuno https://mcp.versuno.ai/mcp --header "Authorization: Bearer uk_live_xxx"
```

<Note>
  The hosted server exposes the **read/query tools only** — `list_public_brains`, `query_brain`, `get_brain_tree`, `get_brain_node`, `list_assets`, `search_assets`, and `get_asset`. The `pull_asset` and `push_asset` tools need access to your local disk, so they're available only via the local (npx) setup.
</Note>

Some GUI clients (e.g. Claude Desktop) can't attach a custom header. For those, bridge to the hosted server with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json theme={null}
{
  "mcpServers": {
    "versuno": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.versuno.ai/mcp",
        "--header",
        "Authorization: Bearer uk_live_xxx"
      ]
    }
  }
}
```

Client-specific instructions:

* [Cursor](/mcp/clients/cursor)
* [Claude Code](/mcp/clients/claude-code)
* [Cline](/mcp/clients/cline)
* [Claude Desktop](/mcp/clients/claude-desktop)
* [VS Code](/mcp/clients/vscode)
* [Windsurf](/mcp/clients/windsurf)
* [Codex CLI](/mcp/clients/codex)
* [OpenCode](/mcp/clients/opencode)
* [Zed](/mcp/clients/zed)
* [Antigravity](/mcp/clients/antigravity)

## Environment variables

| Variable          | Required | Description                                                                                                                     |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `VERSUNO_API_KEY` | Yes      | Your Versuno API key. Must start with `uk_live_`.                                                                               |
| `VERSUNO_API_URL` | No       | Override the API base URL. Defaults to `https://versuno.ai/api/public`. Useful for self-hosted Versuno or staging environments. |
| `VERSUNO_DEBUG`   | No       | Set to `1` to log HTTP requests to stderr. Useful for troubleshooting connection issues.                                        |

## Verifying it works

After configuring your client, restart it and open a chat. The agent should have access to nine new tools.

**Brains:**

* `list_public_brains`
* `query_brain`
* `get_brain_tree`
* `get_brain_node`

**Prompt Manager:**

* `list_assets`
* `search_assets`
* `get_asset`
* `pull_asset`
* `push_asset`

Ask the agent: *"List my Versuno assets."* It should call `list_assets` and return metadata for up to 20 assets. If it doesn't, the server isn't connected. See [Troubleshooting](#troubleshooting).

## Troubleshooting

**The agent doesn't see any Versuno tools.**

The server isn't being launched. Check:

1. The MCP client's config file is saved and the client has been fully restarted.
2. `npx` is on your PATH. Run `npx --version` from your terminal.
3. Node.js 18 or newer is installed. Run `node --version`.

**`VERSUNO_API_KEY is not set`.**

The env block isn't reaching the spawned process. Double-check the JSON structure. Some clients need `env` inside the server block, not at the top level.

**`VERSUNO_API_KEY is invalid`.**

Your key doesn't start with `uk_live_` or is too short. Regenerate it at [versuno.ai/settings/api-keys](https://versuno.ai/settings/api-keys).

**`AUTH_FAILED` on every tool call.**

The key was revoked or copied incorrectly. Regenerate and update the config.

**Intermittent timeouts.**

Set `VERSUNO_DEBUG=1` in the env block, restart the client, and check its MCP log panel for the actual HTTP errors.

## Installing a specific version

`npx -y versuno-mcp` always pulls the latest release. To pin a version, add it to the package spec:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "versuno-mcp@0.1.0"],
  "env": {
    "VERSUNO_API_KEY": "uk_live_xxx"
  }
}
```

See the [changelog](https://github.com/Versuno-AI/mcp/blob/main/CHANGELOG.md) for release notes.