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, Canva, Zapier, Trello, Miro, Resend, Cal.com, Context7, Alpha Vantage, Twelve Data, draw.io, CoinGecko, Neon, Airtable, Cloudflare, or Excalidraw). 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, CoinGecko and Excalidraw 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, CoinGecko and Excalidraw connect with one click and need no credentials. draw.io’s 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 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. Neon’s consent screen lets each member choose a project, turn off write access and pick tool categories; its URL parameters — readonly=true, projectId=<project-id> and category=<name> — fix those choices instead, so add it as a custom MCP server only when a grant has to be fixed; see Neon. For Excalidraw, read_me describes the diagram format and create_view draws the diagram as an interactive canvas in the answer (see MCP Apps); the canvas exports it to an editable https://excalidraw.com/#json=… link. Admins can turn presets off one by one, and turn off custom MCP servers, in Admin > Connectors. See Connectors.

A server’s tool descriptions reach the model verbatim, so a hostile server can plant instructions in them. While an admin has turned on Warn about tool descriptions that look like prompt injection in Admin > Guardrails, and the operator has turned the decision model on, each action is scored when the server is saved or refreshed, and an action that reads like a prompt injection is marked in the tool’s permissions. Nothing is turned off; check the action under Customize before you allow it. See MCP tool descriptions.

Example: Parallel Search

Parallel Search MCP provides public web search and page extraction without a Parallel account or API key. Free access is rate-limited.

Follow Step 2 above to add a custom MCP server, and name it Parallel Search.
Enter https://search.parallel.ai/mcp as the server URL and select No authentication. DocsGPT automatically uses Streamable HTTP for this URL.
Click Test Connection. The discovered tools should include web_search and web_fetch. Click Save.
Enable the saved MCP tool in your agent configuration. Start a conversation and ask, for example: “Search the web for the official Python documentation on virtual environments and fetch the relevant page.”

web_search returns web results with source URLs and excerpts. web_fetch extracts text from public URLs. To stop an agent from using these tools, remove the MCP tool from that agent’s configuration.

Once enabled, the agent can call these tools during conversations. Queries, requested URLs, and any supplied objectives or context are sent to Parallel. Only enable the connection for agents whose data may be shared with this service.

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.

MCP Apps

Some MCP servers ship an interactive view with a tool, an MCP App : Excalidraw’s create_view draws a live canvas. DocsGPT renders the view inline in the answer, in a sandboxed frame that reaches only the domains the server declares, and renders it again when you reopen the conversation. A tool the server marks as the view’s own (visibility: ["app"]) is not offered to the agent; the view calls it through DocsGPT under the tool’s permission, so a tool set to Needs approval asks on the card first.

The view runs on a sandbox origin, which must differ from the app’s. On a local install with API_URL on localhost or 127.0.0.1, DocsGPT uses the other loopback name and needs no setup. On your own domain, point a second hostname (for example sandbox.docs.example.com) at the API and set MCP_APPS_SANDBOX_URL=https://sandbox.docs.example.com/api/mcp_apps/sandbox. Without a sandbox origin, or with MCP_APPS_ENABLED=false, tools show as ordinary steps and the agent keeps every tool. A connection made before this release shows its view once you open it in Settings > Connectors and click Refresh tools.

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, unless the operator lists it in SAFE_URL_ALLOWED_HOSTS (Allowing private hosts). 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.