Skip to content
AskVault Docs
Try Free →

Per-workspace MCP server

Written by , Principal Architect, Networks and Tech, AskVault · Reviewed by Allison Chan
Last updated: · 4 min read

What MCP is and why it matters

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

For your AskVault customers, the practical result is simple. Their AI tool of choice, whether that is a laptop app, an IDE, or a browser extension, 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 sees search_knowledge and ask_agent next to its other tools and the user picks them. This complements the REST API rather than replacing it: MCP is the zero-code path for AI-native clients, the REST API is the code path for everything else.

The two tools

An agent that connects to a workspace's MCP server discovers exactly two tools, listed below.

search_knowledge

Search the workspace's indexed knowledge: website pages, uploaded documents, FAQs, and 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. See what RAG is for background on how retrieval feeds an answer.

ask_agent

Send a question to the workspace's full AI agent, the same one that answers the chat widget. It runs the full retrieval plus generation loop and 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 plus 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. Each ask_agent call consumes one message credit from the workspace's monthly allowance, same as a widget or API query. Plans range from 50 messages a month on Free up to a 40,000-message floor on Enterprise; see the pricing breakdown for the full table.

Enable MCP for a workspace

  1. Go to Dashboard, then Workspace settings.
  2. Toggle MCP endpoint to on.
  3. Note your workspace ID and create an API key (Dashboard, then API keys, then 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, then MCP. Same shape as Claude Desktop:

{
  "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 custom MCP clients

The endpoint speaks 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

Auth uses a bearer token: Authorization: Bearer <workspace_api_key>. The key must belong to the workspace being addressed; cross-workspace access is rejected with HTTP 401. It is the same key your customers already use for the /v1/query REST endpoint, so there is nothing new to provision. Revoking that key cuts off MCP access within 30 seconds, same as it does for the REST endpoint. See API keys for how to generate one and why rotating it every 90 days is worth the habit.

Two safety gates apply:

  1. Workspace opt-in: MCP must be enabled for the workspace, off by default.
  2. Plan-tier quota: MCP calls count against the workspace owner's monthly message quota, just like widget or API calls, across all 5 plan tiers.

What is not in v1

Three things are deliberately out of scope for the first release, listed below.

  • SSE transport: Claude Desktop, Cursor, and ChatGPT desktop's current MCP clients all support plain HTTP, so HTTP-only shipped first. Server-sent events arrive if one of those clients makes it the only supported transport.
  • Resources and prompts: only tools are exposed in v1. MCP's resources (file-style content access) and prompts (server-suggested templates) are a later addition.
  • Per-tool scoping: an API key with MCP access can call both tools today. Tool-level scoping is planned but not built.

Why this matters

MCP adoption moved fast in 2026: Claude Desktop, Cursor, several IDE extensions, and ChatGPT desktop in preview all added support within the same year. Every one of those surfaces is a place your customers might already be working, and every one is a place your knowledge base was previously invisible.

Per-workspace MCP closes that gap. Your customers' knowledge bases become first-class data sources inside whatever AI tool they use day to day, alongside the 10 channels (Slack, WhatsApp, Telegram, email, and more) most teams already deploy through Slack or WhatsApp.

See also

Was this page helpful?