Per-workspace MCP server

TL;DR: Every AskVault workspace can expose itself as a Model Context Protocol (MCP) server. Claude Desktop, Cursor, ChatGPT desktop, and any MCP-aware AI tool connects with one config block and gets two tools: search_knowledge and ask_agent. Auth is the workspace's existing API key. Opt-in per workspace.

What MCP is and why it matters

Model Context Protocol is the open standard for connecting AI tools to external data and capabilities. Claude introduced it; Cursor, ChatGPT desktop, and several other agent surfaces now support it as a first-class integration point.

For your AskVault customers, the implication is simple: their AI tool — wherever it lives, on their laptop, in their IDE, on the web — can query their knowledge base through MCP just like any other connected data source. No copy-paste, no separate browser tab, no API client to write. The tool just sees search_knowledge and ask_agent next to its other tools and the user picks them.

The two tools

When an agent connects, it discovers these two tools on the workspace's MCP server:

`search_knowledge`

Search the workspace's indexed knowledge — website pages, uploaded documents, FAQs, integrations like Notion or Confluence.

Inputs:

query (string, required) — natural-language search query
top_k (integer, default 5, max 20) — how many chunks to return

Returns: a list of text blocks, each prefixed with [source name] and a relevance score.

Use this when the agent wants raw chunks to reason over directly without going through your full RAG pipeline.

`ask_agent`

Send a question to the workspace's full AI agent. Uses the same RAG + agent loop + tool calling as the chat widget. Returns a finished natural-language answer with source citations.

Inputs:

question (string, required)
conversation_id (string, optional) — thread id to maintain context across calls

Returns: a text block containing the answer + the source-citation strip.

Use this when the agent wants a finished answer the way an end user would see it in the chat widget.

Enable MCP for a workspace

Dashboard → Workspace settings
Toggle MCP endpoint to on.
Note your workspace ID and create an API key (Dashboard → API keys → New).

Connect from Claude Desktop

Add the workspace to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "askvault-acme-docs": {
      "transport": "http",
      "url": "https://api.askvault.co/api/mcp/{your_workspace_id}/rpc",
      "headers": {
        "Authorization": "Bearer {your_workspace_api_key}"
      }
    }
  }
}

Restart Claude Desktop. The tools appear under the workspace name you chose.

Connect from Cursor

Cursor's MCP config lives at ~/.cursor/mcp.json (or via Settings → MCP). Same shape:

{
  "mcpServers": {
    "askvault-acme-docs": {
      "url": "https://api.askvault.co/api/mcp/{your_workspace_id}/rpc",
      "headers": {
        "Authorization": "Bearer {your_workspace_api_key}"
      }
    }
  }
}

Cursor picks up the tools the next time the editor opens.

Wire format (for clients implementing MCP themselves)

The endpoint is plain JSON-RPC 2.0 over HTTP. One envelope per request.

`initialize`

POST /api/mcp/{workspace_id}/rpc
Authorization: Bearer {api_key}
Content-Type: application/json

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {"name": "askvault.Acme Docs", "version": "1.0.0"},
    "capabilities": {"tools": {"listChanged": false}}
  }
}

`tools/list`

{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}

Returns the two tools above with their inputSchema.

`tools/call`

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_knowledge",
    "arguments": {"query": "WhatsApp pricing", "top_k": 5}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {"type": "text", "text": "[Pricing page] (relevance=0.91) The Starter plan includes WhatsApp Business API..."}
    ],
    "isError": false
  }
}

`ping`

Empty result. Used by some clients for health checks.

Auth model

Bearer token (Authorization: Bearer <workspace_api_key>). The API key must belong to the workspace being addressed — cross-workspace access is rejected with 401. Same key your customers already use for the /v1/query REST endpoint.

Two safety gates apply:

Workspace opt-in — Workspace.mcp_enabled must be true.
Plan-tier quota — MCP calls count against the workspace owner's monthly query quota, just like API calls.

What's NOT in v1

SSE transport — Claude Desktop, Cursor, and ChatGPT desktop's current MCP clients all support plain HTTP, so we shipped HTTP-only first. SSE arrives when one of those clients makes it the only supported transport.
Resources / prompts — only tools are exposed in v1. MCP's resources (file-style content access) and prompts (server-suggested prompt templates) ship in v2.
Per-tool scoping — an API key with MCP access can call both tools. Tool-level scoping is on the roadmap.

Why this matters in 2026

The MCP adoption curve has gone vertical: Anthropic's Claude Desktop, Cursor IDE, Sourcegraph's Cody, several VS Code extensions, ChatGPT desktop in preview. Every one of those surfaces is a place your customers might be working, and every one is a place your knowledge base is currently invisible.

Per-workspace MCP closes that gap. Your customers' knowledge bases become first-class data sources inside whatever AI tool they actually use day-to-day. That's a category your competitors (Chatbase, SiteGPT, Intercom Fin) don't yet have.

Implementation reference

Source: backend/app/routers/workspace_mcp.py. The Workspace model gained an mcp_enabled Boolean (default off) to gate access.