DocSpace Docs

MCP quickstart

Connect an AI agent (Claude Code, Claude Desktop, Cursor or Codex) to your DocSpace space over the Model Context Protocol. The agent can then search and read your pages, boards, catalog and planner, and (if you allow it) write to them.

Availability. The hosted endpoint https://app.docspace.dev/mcp opens after the security review of remote MCP access. Until then /mcp only answers on a local development server (http://localhost:4000/mcp, see Self-hosting). The steps below are the same for both; only the URL changes.

1. Create an agent key

An agent key gives one agent access to one space, with a role and a set of scopes you choose. You need to be an administrator of the space.

  1. Open the space, then Settings → Knowledge → Agents and keys.
  2. Select Create key.
  3. Fill in:
    • Key name: something you will recognise later, such as claude-code-laptop.
    • Role: Viewer, Commenter or Editor. The agent can never do more than this role allows.
    • Scopes: Read only (every *:read scope) or Full write (every scope; needs the Editor role). See Scopes and roles.
  4. Copy the key. It looks like dsk_<id>_<secret> and is shown only once: DocSpace stores a hash, not the key. If you lose it, revoke it and create a new one.

The dialog also offers a ready-made configuration for Claude Code, Cursor and Codex with your key filled in. The snippets below are the same, with a placeholder.

Every snippet on this page uses the placeholder dsk_live_REPLACE_ME. Replace it with your own key, and never commit a real key to a repository or paste it in a shared chat.

2. Connect your client

Claude Code

Run in your terminal:

claude mcp add --transport http docspace 'https://app.docspace.dev/mcp' \
  --header 'Authorization: Bearer dsk_live_REPLACE_ME'

Add --scope user to make the server available in every project. Check it with claude mcp list, or type /mcp inside Claude Code.

Claude Desktop

Claude Desktop launches local (stdio) servers from its configuration file, so use the mcp-remote bridge to reach the HTTP endpoint (it needs Node.js 18 or later). Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "docspace": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://app.docspace.dev/mcp",
        "--header", "Authorization: Bearer ${DOCSPACE_AGENT_KEY}"
      ],
      "env": { "DOCSPACE_AGENT_KEY": "dsk_live_REPLACE_ME" }
    }
  }
}

Restart Claude Desktop. The DocSpace tools appear under the tools menu of a new conversation.

Cursor

Add the server to your personal ~/.cursor/mcp.json (or a project's .cursor/mcp.json that is not committed):

{
  "mcpServers": {
    "docspace": {
      "url": "https://app.docspace.dev/mcp",
      "headers": { "Authorization": "Bearer dsk_live_REPLACE_ME" }
    }
  }
}

Codex

Add the server to your personal ~/.codex/config.toml:

[mcp_servers.docspace]
url = "https://app.docspace.dev/mcp"
http_headers = { Authorization = "Bearer dsk_live_REPLACE_ME" }

Any other MCP client

DocSpace speaks MCP Streamable HTTP, stateless, JSON responses:

3. Try it

Ask your agent something your space can answer, for example:

Using DocSpace, what does our payments runbook say about retries? Cite the pages.

A good agent calls get_context (or search, then get_page) and cites results as [page:12] or [block:345]. The server tells clients to do this in its instructions.

To check the connection without a model, list the tools with curl (the server is stateless, so tools/list works without a prior initialize):

export DOCSPACE_AGENT_KEY='dsk_live_REPLACE_ME'   # your agent key
curl -s https://app.docspace.dev/mcp \
  -H "Authorization: Bearer $DOCSPACE_AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Every call your key makes appears in Settings → Knowledge → Agents and keys → Activity (tool, scope, result and latency; never the content).

Troubleshooting

Symptom Cause Fix
401 with mcp.unauthorized Missing header, wrong format, unknown or revoked key Send Authorization: Bearer dsk_…; create a new key if it was revoked
A tool returns mcp.scope_denied The key lacks the tool's scope, or its role is too low Create a key with the needed scope and role (Scopes and roles)
429 with mcp.rate_limited More than 120 tool calls in 60 s for this key Wait for Retry-After (60 s)
A page the agent should see is "not found" The page is restricted to a team the key's creator is not in, or lives in another space Keys only see one space, as their creator would with the key's role
404 on /mcp Remote MCP is not enabled on that server yet See the availability note at the top

All codes are listed in Errors. The full tool list is in the tool reference.

Next steps