Versuno MCP Server

The official MCP server for Versuno — the universal memory and context layer for AI agents. It connects coding agents (Claude Code, Cursor, Claude Desktop, VS Code) to your Versuno memory: query public brains (graph-based knowledge bases such as indexed library and framework documentation) and search, load, and sync your AI assets (contexts, skills, personas, prompts, and system prompts) for accurate, up-to-date context.

Setup

Create a free Versuno account and create a new API key.

Configuration

The server currently supports stdio transport only. To connect, configure your MCP client (Claude Desktop, Cursor, Claude Code, VS Code) to run npx -y versuno-mcp with the VERSUNO_API_KEY environment variable set to your API key.

Claude Code

claude mcp add versuno -e VERSUNO_API_KEY=uk_live_xxx -- npx -y versuno-mcp

To control where pull_asset writes files, add VERSUNO_WORKSPACE_DIR:

claude mcp add versuno -e VERSUNO_API_KEY=uk_live_xxx -e VERSUNO_WORKSPACE_DIR=/path/to/project -- npx -y versuno-mcp

Cursor

Open the command palette, choose Cursor Settings > MCP > Add new global MCP server.

{
  "mcpServers": {
    "versuno": {
      "command": "npx",
      "args": ["-y", "versuno-mcp"],
      "env": {
        "VERSUNO_API_KEY": "uk_live_xxx",
        "VERSUNO_WORKSPACE_DIR": "/path/to/project"
      }
    }
  }
}

VERSUNO_WORKSPACE_DIR tells the server where to write pulled assets. Without it, files are written relative to the server's working directory.

Claude Desktop

Open Settings > Developer > Edit Config and add:

{
  "mcpServers": {
    "versuno": {
      "command": "npx",
      "args": ["-y", "versuno-mcp"],
      "env": {
        "VERSUNO_API_KEY": "uk_live_xxx",
        "VERSUNO_WORKSPACE_DIR": "/path/to/project"
      }
    }
  }
}

VS Code

Versuno writes pulled assets to a .versuno/ folder in your project. The server resolves the target directory in this order:

1. VERSUNO_WORKSPACE_DIR env var (explicit override)
2. The active workspace folder reported by VS Code via the MCP roots protocol
3. process.cwd() as a last resort

There are two supported configuration approaches:

Option A: Workspace-scoped config (recommended)

Add to .vscode/mcp.json in each project where you want to use Versuno:

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

The server auto-detects the workspace folder via the MCP client, so no path needs to be hardcoded. This is the recommended approach. Each project gets its own server instance, and you can use different API keys per project.

Option B: User-level config with VERSUNO_WORKSPACE_DIR

If you prefer a single global config in your user-level mcp.json, you must set VERSUNO_WORKSPACE_DIR to an absolute project path, otherwise pulls will land in your home directory:

{
  "servers": {
    "versuno": {
      "command": "npx",
      "args": ["-y", "versuno-mcp"],
      "env": {
        "VERSUNO_API_KEY": "uk_live_xxx",
        "VERSUNO_WORKSPACE_DIR": "C:\\path\\to\\your\\project"
      }
    }
  }
}

Note: this hardcodes a single project. For multi-project use, prefer Option A.

After changing server config or env vars, restart the MCP server (VS Code command: MCP: Restart Server). Env changes only apply when the server process (re)spawns.

Tools

Asset tools

| Tool | What it does | |------|--------------| | list_assets | Lists assets by type. Metadata only, nothing loaded into context. | | search_assets | Full-text search across your assets with relevance scoring. | | get_asset | Fetches a single asset's full content into the agent's context. | | pull_asset | Downloads an asset to .versuno/ on disk as a markdown file with frontmatter. | | push_asset | Pushes a local .versuno/ markdown file back to Versuno. Creates a new version if the file has an id in its frontmatter, otherwise creates a new asset (type is inferred from the folder: contexts/, skills/, personas/, prompts/, system-prompts/). |

Brain tools

Brains are graph-based knowledge bases (e.g. indexed library/framework docs). Agents use them to pull accurate, up-to-date context about a specific library or topic.

| Tool | What it does | |------|--------------| | list_public_brains | Lists available public brains (metadata only). The entry point for finding the right brain. | | query_brain | Semantic (RAG) search over a brain. Returns the most relevant passages for a query, ranked by relevance, each with a source and a node id. | | get_brain_tree | Returns a brain's container hierarchy (its table of contents) as an indented outline. | | get_brain_node | Fetches the full content of a single node, e.g. the complete source behind a query_brain result. |

Typical agent flow: list_public_brains to find the right brain → query_brain with that brain's id to retrieve relevant passages → optionally get_brain_node (using a node id from the results) to read the full source. Use get_brain_tree first when you want to understand how a brain is organized.

Brain queries are metered against your API key. Some brains may not yet have an AI-generated overview or exampleQueries populated. Discovery falls back to the brain's name and description in that case.

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. | | VERSUNO_WORKSPACE_DIR | No | Absolute path to treat as the workspace root for reading/writing .versuno/ files. Overrides MCP client roots and process.cwd(). Use this when the server can't auto-detect the correct project directory (e.g. user-level VS Code MCP config). | | VERSUNO_DEBUG | No | Set to 1 to log HTTP requests to stderr. Useful for troubleshooting. |

Security

Prompt injection

The biggest risk with any MCP server is prompt injection: content inside an asset you pull (or that an agent fetches via get_asset) can contain instructions aimed at the LLM rather than at you. A malicious or compromised asset could try to get your agent to run other tools, exfiltrate data, or overwrite files.

Mitigations built in:

• push_asset refuses to read files outside <cwd>/.versuno/. Even if an agent is instructed to push ../../.ssh/id_rsa, the call fails.
• File reads are capped at 1 MB to stop pathological inputs.
• pull_asset only writes into .versuno/ and only as markdown.
• Frontmatter parsing rejects non-object YAML payloads, so a crafted asset can't smuggle in arrays that break the client.

What you should do:

• Keep your MCP client's "ask before running tools" setting on. Don't blanket-approve tool calls, especially push_asset.
• Treat .versuno/ like source code. Review the markdown before pushing.

API key handling

• VERSUNO_API_KEY is passed via the MCP client config. Don't commit it. Don't paste it into chat windows.
• The server validates the key format before making any calls. A placeholder like uk_live_your_key_here will be rejected.
• If a key leaks, rotate it immediately at versuno.ai/settings/api-keys.