MCP Tool Integration

The Model Context Protocol (MCP) integration lets you connect external tool servers to DocsGPT. Your agents can then discover and call tools provided by those servers during conversations — for example, querying a CRM, running code, or accessing a database.

Setup

Step 1: Configure Environment Variables (Optional)

Only needed if your MCP servers use OAuth authentication:


MCP_OAUTH_REDIRECT_URI=https://yourdomain.com/api/mcp_server/callback

If not set, it is derived from the host of CONNECTOR_REDIRECT_BASE_URI, then from API_URL.

Step 2: Add an MCP Server

Go to Settings > Connectors and pick a preset (Notion, Linear, Atlassian, Sentry, Stripe, ClickUp, Zapier, Trello, Miro, Resend, Cal.com, Alpha Vantage, draw.io, or CoinGecko). OAuth presets open the service’s sign-in: Sign in to ClickUp, for example, opens ClickUp’s sign-in, and its tools are ready when you return. draw.io and CoinGecko need no sign-in: click Connect and their tools are ready. For any other server, choose Add custom connector > MCP server and enter its URL and authentication; scopes and the timeout are under Show advanced. Click Test Connection to verify, then Save.

Alpha Vantage’s sign-in works on DocsGPT cloud and on localhost only. On a self-hosted instance with its own domain, add it as a custom MCP server with your API key in the URL, https://mcp.alphavantage.co/mcp?apikey=<KEY>, and choose no authentication.

Step 3: Enable for Your Agent

In your agent configuration, enable the MCP tools you want the agent to use.

Presets need no URL entry. Most sign in with OAuth; draw.io connects with one click and needs no credentials. Its create_diagram tool returns a link to an editable diagram in draw.io. The hosted server receives the diagram content; draw.io’s MCP server also documents a self-hosted option. CoinGecko works the same way and gives agents live crypto market data through two tools: CoinGecko’s search_docs looks up its SDK documentation (methods, parameters and request structure), and execute runs the TypeScript the agent writes against the CoinGecko SDK in a sandbox. Its keyless server shares rate limits across all users. Admins can turn presets off one by one, and turn off custom MCP servers, in Admin > Connectors. See Connectors.

Authentication Types

Auth Type	Config Fields
None	—
Bearer	`bearer_token`
API Key	`api_key`, `api_key_header` (default: `X-API-Key`)
Basic	`username`, `password`
OAuth	`oauth_scopes` (optional)

For OAuth in production, MCP_OAUTH_REDIRECT_URI must be a publicly accessible URL pointing to your DocsGPT backend.

OAuth servers, including the OAuth presets, also need ENABLE_SSE_PUSH=true (the default) and the API served through the ASGI app. The sign-in link and its result reach the web app only as mcp.oauth.* events on the realtime events stream; with the publisher off, adding an OAuth server never gets past Test Connection.

API Endpoints

Endpoint	Method	Description
`/api/mcp_server/test`	POST	Test a connection without saving
`/api/mcp_server/save`	POST	Save or update a server configuration
`/api/mcp_server/callback`	GET	OAuth callback handler
`/api/mcp_server/auth_status`	GET	Batch check auth status for all MCP tools

For an OAuth server, /api/mcp_server/test answers with requires_oauth: true and a task_id, and the sign-in runs in the background. Its progress arrives on the user event stream, GET /api/events, as mcp.oauth.in_progress, mcp.oauth.awaiting_redirect (with the authorization_url to open), mcp.oauth.completed or mcp.oauth.failed events whose scope.id is that task_id. After completed, call /api/mcp_server/save with oauth_task_id set to the task_id in the config. See Realtime events; the event stream needs the API served through the ASGI app.

Troubleshooting

Connection refused — Verify the URL and that the server is reachable from your backend.
Invalid server URL: <reason> (when testing or saving) or Invalid MCP server URL: <reason> (when a saved tool connects) — DocsGPT only connects to MCP servers on the public internet. localhost, loopback, private (RFC 1918), link-local and other reserved addresses are refused, including a server on the same host or in the same Docker Compose project, and there is no allowlist. See Outbound network access.
403 Forbidden — Check credentials and permissions.
Timed out — Default is 30s; increase timeout in tool config (max 300s).
OAuth “needs_auth” persists — Verify MCP_OAUTH_REDIRECT_URI is correct and Redis is running.