Setup

The Versuno MCP server is distributed on npm as 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.

The universal config

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

{
  "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:

{
  "mcpServers": {
    "versuno": {
      "url": "https://mcp.versuno.ai/mcp",
      "headers": {
        "Authorization": "Bearer uk_live_xxx"
      }
    }
  }
}

For Claude Code:

claude mcp add --transport http versuno https://mcp.versuno.ai/mcp --header "Authorization: Bearer uk_live_xxx"

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.

Some GUI clients (e.g. Claude Desktop) can’t attach a custom header. For those, bridge to the hosted server with mcp-remote:

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

Client-specific instructions:

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

The agent doesn’t see any Versuno tools. The server isn’t being launched. Check:

The MCP client’s config file is saved and the client has been fully restarted.
npx is on your PATH. Run npx --version from your terminal.
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. 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:

{
  "command": "npx",
  "args": ["-y", "versuno-mcp@0.1.0"],
  "env": {
    "VERSUNO_API_KEY": "uk_live_xxx"
  }
}

See the changelog for release notes.

Getting Started

Clients

Tools

Reference

Requirements

The universal config

Remote (hosted HTTP) server

Environment variables

Verifying it works

Troubleshooting

Installing a specific version

​Requirements

​The universal config

​Remote (hosted HTTP) server

​Environment variables

​Verifying it works

​Troubleshooting

​Installing a specific version

Requirements

The universal config

Remote (hosted HTTP) server

Environment variables

Verifying it works

Troubleshooting

Installing a specific version