MCP Server

DocsGPT runs a Model Context Protocol  server, so an MCP client such as Claude Code, Claude Desktop or Cursor can search the sources of one of your agents. The client’s own model then answers with what it finds.

This is the opposite direction from MCP tools, where a DocsGPT agent calls external MCP servers.

What the server offers

search_docs searches the sources attached to the agent the key belongs to and returns at most chunks passages. It calls no model, so it uses no LLM tokens. Each result is an object with:

• text: the passage.
• title: the file or page title.
• source: where the passage came from, such as a file name or URL.

An agent with no sources returns an empty list. Each search is recorded as a trace for the agent’s owner, like a call to the Search API.

Before you start

• An agent API key. Publish an agent with the sources you want to search and copy its key from Access Details. See Agent API keys. Anyone holding the key can search those sources.
• The ASGI server. /mcp is served by the ASGI app (uvicorn or gunicorn with docsgpt.asgi:asgi_app, which every install uses by default). Under flask run it returns 404. See ASGI-only features.
• A running worker. The API embeds each query through the Celery worker. Without one, every search waits EMBEDDINGS_DELEGATE_TIMEOUT and then returns an empty list, with no error; the failure is only in the API log. To search without a worker, set EMBEDDINGS_DELEGATE_TO_WORKER=false or point EMBEDDINGS_BASE_URL at an embeddings service.

The server doesn’t check the key when a client connects: the connection and the tool list work without one. A missing or wrong key shows up when the tool runs, as a tool error that reads Missing Bearer token or Invalid API key.

Connect a client

In the examples, replace http://localhost:7091 with your API address and YOUR_AGENT_API_KEY with the key.

Claude Code

claude mcp add --transport http docsgpt http://localhost:7091/mcp \
  --header "Authorization: Bearer YOUR_AGENT_API_KEY"

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "docsgpt": {
      "url": "http://localhost:7091/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

Claude Desktop

Claude Desktop’s configuration file starts local (stdio) servers, so bridge to the HTTP server with mcp-remote, which needs Node.js. Add this to claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "docsgpt": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:7091/mcp",
        "--header",
        "Authorization:${DOCSGPT_AUTH}"
      ],
      "env": {
        "DOCSGPT_AUTH": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

The header value sits in env because some platforms split arguments that contain spaces.

Other clients

Any client that speaks streamable HTTP and can send a header works. With the FastMCP  Python client, where a string auth is sent as a bearer token:

import asyncio
 
from fastmcp import Client
 
 
async def main():
    async with Client("http://localhost:7091/mcp", auth="YOUR_AGENT_API_KEY") as client:
        result = await client.call_tool("search_docs", {"query": "How do I install DocsGPT?", "chunks": 3})
        for hit in result.data:
            print(hit["title"], hit["source"])
 
 
asyncio.run(main())

To check the endpoint with curl, send an initialize request. A working server answers with an event stream and an mcp-session-id header:

curl -i http://localhost:7091/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

Related

• Search API: the same search as a plain HTTP endpoint.
• API overview: the other credentials and endpoints.