OpenRPC MCP Server: Interact with JSON-RPC APIs

Overview

The OpenRPC MCP Server is a small server for exposing and interacting with JSON-RPC APIs using OpenRPC documents. It hosts an OpenRPC description (local file or remote URL) and provides documentation-driven tooling so developers can discover available methods, read parameter definitions, and exercise calls through an interactive UI or HTTP endpoints. This makes it easier to understand and test JSON-RPC services without hand-writing request payloads or reversing the protocol.

The server is useful for API authors, integrators, and testers who want a lightweight, repeatable way to present a JSON-RPC surface to users or tools. By serving the OpenRPC document alongside a playground and proxy endpoints, the MCP server bridges documentation and runtime interactions, enabling workflows like live debugging, automated integration tests, and client generation driven directly from a canonical API description.

Features

• Serve an OpenRPC document (local file or remote URL) over HTTP
• Interactive documentation UI (method list, parameter schemas, examples)
• JSON-RPC proxy endpoint for issuing calls to the target backend
• Simple CLI and configuration file support for quick setup
• Docker image for containerized deployment
• CORS and basic proxy configuration for testing cross-origin clients
• Compatible with standard OpenRPC tools for client generation and validation

Installation / Configuration

Prerequisites:

• Node.js (LTS recommended)
• npm or yarn (for local development)
• Docker (optional, for containerized runs)

Clone and install

git clone https://github.com/shanejonas/openrpc-mpc-server.git
cd openrpc-mpc-server
npm install

Run locally with a local OpenRPC document:

# Serve a local OpenRPC document on port 4000
node server.js --openrpc ./openrpc.json --port 4000

Serve a remote OpenRPC URL and proxy backend:

node server.js --openrpc https://example.com/openrpc.json --port 8080 --proxy-target https://rpc-backend.example.com

Configuration file (config.json)

{
  "openrpc": "./openrpc.json",
  "port": 4000,
  "bind": "0.0.0.0",
  "cors": true,
  "proxyTarget": "https://rpc-backend.example.com"
}

Start with the config:

node server.js --config ./config.json

Docker

# Build
docker build -t openrpc-mcp-server .

# Run with environment variables
docker run -p 4000:4000 \
  -e OPENRPC_URL=https://example.com/openrpc.json \
  -e PORT=4000 \
  openrpc-mcp-server

Command-line options (typical)

• –openrpc: path or URL to OpenRPC document
• –config: path to JSON config file
• –port: HTTP port (default 4000)
• –bind: bind address (default 127.0.0.1)
• –proxy-target: backend JSON-RPC endpoint to forward calls to
• –cors: enable CORS support

Available Resources

• GitHub repository: https://github.com/shanejonas/openrpc-mpc-server
• OpenRPC specification: https://www.open-rpc.org
• JSON-RPC 2.0 specification: https://www.jsonrpc.org/specification
• Example OpenRPC documents (usually found in the repo’s examples/ directory)
• Compatible tools: openrpc-generator, openrpc-playground, client SDK generators that accept OpenRPC documents

Common server endpoints (examples)

Use Cases

1. Explore a public JSON-RPC API

• Point the server at a published OpenRPC document and open the UI to browse methods, parameter schemas, and examples.
• Example: serve an Ethereum-compatible node OpenRPC document and call eth_blockNumber from the UI.

2. Test and debug JSON-RPC implementations

• Use the interactive UI or curl to exercise methods with different parameters and inspect results and errors.
• Example curl (proxying to backend):

curl -s -X POST http://localhost:4000/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

3. CI integration and contract testing

• Start the MCP server in your CI pipeline pointing at the service under test. Run a suite of JSON-RPC calls driven by the OpenRPC document to validate method contracts and parameter validations.
• Example: start server headless and run a node script to assert expected responses.

4. Client generation and onboarding

• Use the served OpenRPC document URL (/openrpc) as the canonical source for client code generators. Onboarding new developers becomes a matter of directing them to the server URL for documentation and sample calls.

5. Local development proxy

• Developers can run the MCP server locally and configure frontend apps to call the server, which proxies requests to a remote JSON-RPC backend while injecting CORS headers and serving documentation.

Tips & Best Practices

• Keep your OpenRPC document authoritative: generate it from your code or CI so the server always reflects the current API.
• Use the proxyTarget option for non-CORS backends to avoid modifying client code during testing.
• Combine with OpenRPC tooling (e.g., openrpc-generator) to generate SDKs and tests directly from the served /openrpc URL.

The OpenRPC MCP Server is designed to be a small, documentation-first bridge between OpenRPC descriptions and practical developer workflows for JSON-RPC APIs. For full details and examples, consult the repository and the OpenRPC spec.