dc-mcp

Stdio MCP (Model Context Protocol) client for the DoControl multi-agent assistant. Connect Cursor (or any MCP-compatible client) to your DoControl tenant in under 60 seconds.

Quick start

1. Install uv (one-time, if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Authenticate with your DoControl refresh token

uvx dc-mcp login

3. Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "docontrol": {
      "command": "uvx",
      "args": ["dc-mcp"],
    },
  },
}

Then restart Cursor. The DoControl tools will appear in the chat sidebar.

Available tools

All tools are read-only and cannot mutate tenant data. Each advertises this via the standard MCP readOnlyHint annotation in tools/list.

Get your refresh token

Log in to https://app.docontrol.io, navigate to Settings → Integrations → MCP Token, and click Generate. The token is valid for 30 days; you can regenerate it at any time.

When your token expires, simply run uvx dc-mcp login again with the new refresh token.

CLI reference

CI / headless / corporate environments

For environments where the OS keychain is unavailable (CI runners, headless Linux containers, devcontainers without Secret Service), set the refresh token via environment variable:

export DOCONTROL_REFRESH_TOKEN="..."

Then configure your MCP server to pass it through:

{
  "mcpServers": {
    "docontrol": {
      "command": "uvx",
      "args": ["dc-mcp"],
      "env": {
        "DOCONTROL_REFRESH_TOKEN": "${env:DOCONTROL_REFRESH_TOKEN}",
      },
    },
  },
}

The environment variable takes priority over the keychain when both are set.

Troubleshooting

error: Refresh token expired or revoked
Your refresh token is older than 30 days or has been revoked. Generate a new one in the DoControl webapp and run dc-mcp login again.

Network error contacting Cognito ... Check your internet connection or corporate proxy
You're behind a corporate firewall. Set HTTPS_PROXY to your proxy URL (e.g., export HTTPS_PROXY=http://proxy.company.com:8080).

Keychain unavailable: ... On headless Linux, set DOCONTROL_REFRESH_TOKEN env var instead
Your environment doesn't have a usable OS keychain (common in headless Linux or devcontainers). Use the environment variable approach from the CI section above.

No refresh token found
Either run dc-mcp login to store a token in your keychain, or set the DOCONTROL_REFRESH_TOKEN environment variable.

No DoControl tools appear in Cursor
Verify the syntax of ~/.cursor/mcp.json, restart Cursor, then check Cursor Settings → MCP for connection errors. Run dc-mcp whoami to confirm your authentication is healthy.

MCP connection fails / proxy crashes after a successful login (AttributeError: ... list_tools, Connection closed)
Your local uvx cache may be on a broken package resolve. Force a refresh, then reconnect the MCP server in Cursor:

uvx --refresh dc-mcp@latest

You do not need to run dc-mcp login again if your refresh token is still valid.

uvx: command not found
Install uv with curl -LsSf https://astral.sh/uv/install.sh | sh and restart your shell.

Privacy and security

Refresh tokens are stored in your OS keychain (macOS Keychain, Windows Credential Vault, or Linux Secret Service). They never leave your machine other than to be exchanged with Cognito for short-lived access tokens.

Each request to DoControl uses a fresh access token with a one-hour time-to-live (TTL). All traffic is HTTPS to AWS-hosted endpoints. No telemetry is collected by the package.

To revoke access, run dc-mcp logout to clear the local token, and revoke server-side via the DoControl webapp's Integrations panel.

Development & contributing

This package is part of the docontrol-io/dot repository. To report issues, file a GitHub issue in the main repo. For implementation details and testing, see the package source in packages/docontrol-mcp/src/ and tests in packages/docontrol-mcp/tests/.

License

MIT — see LICENSE.