pyRPC - Type-Safe APIs for Python

pyRPC has two MCP surfaces: a remote server that provides documentation to agents, and a local server that provides your project's API to agents. This guide walks through setting up both, then combining them.

Prerequisites

Python 3.11 or later
Node.js 18 or later
uv installed

Part 1: Remote Documentation MCP (5 minutes)

The remote MCP server provides pyRPC documentation to your agent. No project setup required.

npx @pyrpc/mcp mcp

The CLI detects which AI coding agents are installed on your system and lets you select which ones to configure. It writes the MCP server URL (https://mcp.pyrpc.com/mcp) into each agent's config file.

Verify the connection by asking your agent to search for something:

"Search the pyRPC docs for FastAPI integration"

The agent should return results from the documentation, including relevant guide pages and code examples. That is it. Your agent now has access to the full pyRPC documentation.

Part 2: Local Project MCP (5 minutes)

The local MCP server provides your project's actual API to your agent. This is where the real power is.

# Add MCP support to your project
uv add "pyrpc-core[mcp]"

Then register the local server with your agent. For Claude Code:

claude mcp add pyrpc -- pyrpc mcp

For other agents, add the MCP entry manually to their config:

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

Now try the three core tools:

introspect_project: Ask “What procedures does my project expose?” The agent sees every registered procedure with full parameter schemas.
check_call: Ask “Would calling create_user with email=test@example.com work?” The agent gets back per-parameter errors if something is wrong.
run_codegen: Ask “Generate a React hook for create_user” The agent runs codegen with dry_run=true first, then writes it only after approval.

Part 3: Both together

Configure both servers in the same agent. This gives your agent two capabilities: understanding your project and understanding pyRPC.

Now the agent can answer “how do I add authentication?” using the remote docs server, and “what procedures does my app expose?” using the local server. It switches between them based on context.

Troubleshooting

npx @pyrpc/mcp mcp hangs or times out

The MCP server communicates over stdio. Make sure your agent is configured to use stdio transport, not HTTP. Check that Node.js 18+ is installed by running node --version.

introspect_project returns “no config found”

The local MCP server looks for pyrpc.json in your project root. Make sure you are running from the directory that contains it. If you have not created one yet, run pyrpc init.

Client shows no tools

Confirm uv add "pyrpc-core[mcp]" succeeded. Restart your agent after adding the MCP server. Most agents only read MCP configuration at startup.

ModuleNotFoundError on import

A dependency of your entrypoint module is missing from the environment running the MCP server. Verify pyrpc dev works in the same checkout.

Next steps