pyRPC - Type-Safe APIs for Python

Before MCP, every AI tool that wanted to integrate with your codebase needed a custom integration. VS Code extensions for Copilot, CLI wrappers for local agents, API clients for cloud-hosted models. Each integration meant understanding your tool's specific API, auth model, and data format. The result was N tools times M agents equals N times M integrations.

The protocol stack

    +---------------------------+
    |     Your MCP Tools       |  (introspect, validate, codegen)
    +---------------------------+
    |      MCP Protocol        |  (tools/list, tools/call, resources)
    +---------------------------+
    |       JSON-RPC 2.0       |  (request, response, notification)
    +---------------------------+
    |      Transport Layer     |  (stdio or streamable HTTP)
    +---------------------------+

JSON-RPC as the foundation

MCP builds on JSON-RPC 2.0, a specification from 2010 that is well-understood, battle-tested, and language-agnostic. Every major language has a JSON-RPC library. The wire format is trivial to parse. Debugging tools read it natively. By choosing JSON-RPC as the foundation, MCP inherits a decade of tooling and avoids inventing a serialization format that would need its own ecosystem.

Streamable HTTP vs stdio

MCP defines two transport layers: stdio for local servers and streamable HTTP for remote ones. stdio is the right choice when the server runs on the same machine as the agent, which is the case for pyRPC's local MCP. The server is spawned as a subprocess, communicates over stdin and stdout, and shuts down when the session ends. No ports, no firewalls, no auth tokens. Streamable HTTP is for remote servers where the agent connects over the network, authenticates once, and maintains a persistent session. The transport choice is not cosmetic; it determines the trust model.

How pyRPC uses both

pyRPC's local MCP server uses stdio for zero-config local operation. The agent spawns pyrpc mcp, gets a JSON-RPC session over pipes, and calls tools. No configuration, no port discovery, no auth. For remote scenarios, the same tools can be exposed over HTTP, where the server runs as a hosted endpoint and the agent connects with an API key. The tools are identical; only the transport changes.

The thin server principle

pyRPC's MCP server does one thing: introspect your project. It exposes three tools, introspect_project for schemas, check_call for validation, and run_codegen for type generation. It does not manage your database, deploy your code, or execute arbitrary commands. The server is thin because a thin server is a trustworthy server. Every tool is read-only or narrowly scoped, which means the agent can use it without the kind of trust elevation that a full-featured server would require.

Why this matters for the ecosystem

The protocol-as-interface model means any MCP-compatible agent works with any MCP server. Cursor, Claude Desktop, Windsurf, opencode, and every future agent all speak the same protocol. pyRPC does not need to write a Cursor plugin, a Claude extension, or a Windsurf integration. It writes one MCP server and gets all of them for free. The same is true in reverse: any future pyRPC tool, whether it validates code, generates types, or inspects schemas, works in every agent without changes.