MCP

pyRPC ships two distinct MCP surfaces. They solve different problems and can be used together.

Which MCP should I use?

An agent can have both configured at once. The local one understands "my application"; the remote one understands "pyRPC".

Remote Documentation MCP

The hosted documentation server exposes read-only search and retrieval over the entire pyRPC documentation. No Python installation and no pyRPC project are required.

npx @pyrpc/mcp mcp

This command configures your AI coding client to use:

https://mcp.pyrpc.com/mcp

It is a thin convenience wrapper around the add-mcp configuration engine, which maintains native support for 19 coding agents including Claude Code, Cursor, VS Code, OpenCode, Windsurf, Codex, Zed, Antigravity, Cline, and Gemini CLI. add-mcp is the configuration utility; it is not the MCP server.

Useful flags:

npx @pyrpc/mcp mcp --global            # user-level instead of project-level
npx @pyrpc/mcp mcp --agent cursor      # configure a specific agent
npx @pyrpc/mcp mcp --list              # supported agents

Prefer the upstream tool directly? It is the same result:

npx add-mcp https://mcp.pyrpc.com/mcp

Claude Desktop

claude_desktop_config.json only accepts local stdio servers. For remote servers, Claude Desktop uses connectors configured in the app: Settings -> Connectors -> Add custom connector, then paste https://mcp.pyrpc.com/mcp. The connection is brokered through Anthropic's cloud per their custom-connector model.

Manual configuration

Enterprise teams that prefer not to run installer utilities can paste an entry directly.

Claude Code (.mcp.json)

{
  "mcpServers": {
    "pyrpc-docs": { "type": "http", "url": "https://mcp.pyrpc.com/mcp" }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "pyrpc-docs": { "url": "https://mcp.pyrpc.com/mcp" }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "pyrpc-docs": { "type": "http", "url": "https://mcp.pyrpc.com/mcp" }
  }
}

OpenCode (opencode.json)

{
  "mcp": {
    "pyrpc-docs": {
      "type": "remote",
      "url": "https://mcp.pyrpc.com/mcp"
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "pyrpc-docs": { "serverUrl": "https://mcp.pyrpc.com/mcp" }
  }
}

Reload your agent after any manual change.

Local Project MCP

The local server runs inside your project's Python environment, imports your configured backend module, and answers from the live registry, giving agents ground truth about your application.

uv add "pyrpc-core[mcp]"

Then register it with your agent:

Claude Code

claude mcp add pyrpc -- pyrpc mcp

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "pyrpc": {
      "command": "pyrpc",
      "args": ["mcp"]
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "pyrpc": {
      "command": "pyrpc",
      "args": ["mcp"]
    }
  }
}

Tools

Security model

• No procedure execution. There is no tool that invokes your backend code, so agents cannot cause database writes, network calls, or other side effects through pyRPC's MCP.
• Local-only. The process is spawned by your own client in your project environment. No telemetry, no network egress.
• Narrow writes. run_codegen writes generated files only; tsconfig/bundler setup stays with pyrpc init / pyrpc codegen.
• Structured errors. Missing or ambiguous configuration produces actionable errors (including what was detected) rather than guesses.

How it works

Claude / Cursor / VS Code / OpenCode
        | launches subprocess
        v
    pyrpc mcp
        | imports your backend module
        v
your routers, registry, schemas

The server must run in the same Python environment as your project because it imports your code. That is automatic when clients spawn pyrpc mcp from the project root.

Example interaction

With both servers connected, an agent grounds its work in reality:

Agent: calls introspect_project on the local server.

{
  "framework": "fastapi",
  "procedures": [
    { "name": "get_post", "kind": "query",
      "parameters": [{ "name": "id", "required": true }] }
  ]
}

Agent: unsure how mutation invalidation works, searches the remote docs server for mutation invalidation react, reads the adapter guide via get_doc, and follows the documented pattern.

Agent: verifies the payload with check_call("get_post", { "id": "abc" }) before writing client code:

{ "valid": false, "errors": [{ "param": "id",
    "message": "Input should be a valid integer" }] }

Agent: fixes the payload, confirms types are current with run_codegen(dry_run=true), regenerates with dry_run=false.

Troubleshooting