@vursulabs/mcp-server

Connect Claude Desktop, Cursor, and other MCP clients to your Vursu knowledge base.

Heads up — Claude Desktop and Claude.ai users: The fastest way to connect is the new remote URL flow. In Claude, add a custom connector with https://app.vursu.com/api/mcp — no API key needed, you pick which Vursu account to connect on the consent screen, and OAuth handles auth and refresh automatically. This npm package is still the right choice for Cursor, stdio-based agents, and scripts.

What it provides

Tools

| Tool | Description | |------|-------------| | get_instructions | Called automatically before every response. Returns account-specific skills and instructions that guide the AI's behaviour. | | search_knowledge | Semantic search across brain entries, documents, URLs, assets, skills, and research | | create_brain_entry | Add a new knowledge entry to the brain | | create_skill | Create an account-scoped AI skill (specialist instructions) | | update_skill | Update an existing skill by ID | | delete_skill | Delete a skill by ID | | get_skill | Load full skill content by ID | | upload_document | Upload a PDF, DOCX, or image file (base64, max 10MB) | | add_url_source | Add a URL to scrape, or crawl an entire website | | query_activity | Query audit logs and recent activity |

How skills work

Skills are reusable instructions that tell the AI how to perform specific tasks for your account — like "create a social post", "write a proposal", or "review a contract". When a user asks the AI to do something, get_instructions automatically searches for matching skills and injects the instructions into the AI's context before it responds.

Create skills in the Vursu UI (Brain page → Skills tab) or directly via the create_skill tool.

Resources

Browse and read knowledge directly:

• knowledge://brain/{id} — Brain entries
• knowledge://documents/{id} — Uploaded documents (extracted text)
• knowledge://urls/{id} — Scraped URL content
• knowledge://skills/{id} — AI skills (specialist instructions)

Prerequisites

• Node.js 18 or later
• A Vursu API key (generate one at Settings > API Keys in your Vursu app)
• The origin (scheme + host + port) of your Vursu web app, as you see it in the browser — you must set VURSU_API_URL in env to that value (no trailing slash)

Setup

Set VURSU_API_KEY and VURSU_API_URL in the env object. Replace the placeholders below with your real API key and your real app URL — the JSON values are examples only, not something you can paste unchanged.

Claude Desktop

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "vursu": {
      "command": "npx",
      "args": ["-y", "@vursulabs/mcp-server"],
      "env": {
        "VURSU_API_KEY": "vsk_REPLACE_WITH_YOUR_KEY",
        "VURSU_API_URL": "https://REPLACE_WITH_YOUR_VURSU_APP_ORIGIN"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "vursu": {
      "command": "npx",
      "args": ["-y", "@vursulabs/mcp-server"],
      "env": {
        "VURSU_API_KEY": "vsk_REPLACE_WITH_YOUR_KEY",
        "VURSU_API_URL": "https://REPLACE_WITH_YOUR_VURSU_APP_ORIGIN"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | VURSU_API_KEY | Yes | Your Vursu API key (starts with vsk_) | | VURSU_API_URL | Yes | Origin where your Vursu app is hosted (e.g. https://your-host or http://localhost:5173 for local dev). No path and no trailing slash. |

Development

Local development example — still replace with whatever origin your dev server actually uses:

{
  "env": {
    "VURSU_API_KEY": "vsk_REPLACE_WITH_YOUR_KEY",
    "VURSU_API_URL": "http://localhost:5173"
  }
}

License

MIT