openpx-mcp

A Model Context Protocol server that teaches any coding agent how to use the openpx prediction-markets SDK — across the Rust, Python, and TypeScript SDKs.

It exposes the openpx OpenAPI spec, AsyncAPI spec (websockets), unified type schema, and SDK quickstarts as MCP resources, plus a focused set of tools that produce runnable, idiomatic snippets in the language you ask for. The server stays in sync with openpx releases automatically — every openpx version cuts a matching @openpx/mcp@<version> on npm with the latest specs vendored in.

Install

This server runs locally over stdio and is launched by your MCP client on demand. No service to host.

Claude Code

claude mcp add openpx -- npx -y @openpx/mcp

Or hand-edit ~/.claude.json (mcpServers):

{
  "mcpServers": {
    "openpx": {
      "command": "npx",
      "args": ["-y", "@openpx/mcp"]
    }
  }
}

Cursor

In ~/.cursor/mcp.json (or per-workspace .cursor/mcp.json):

{
  "mcpServers": {
    "openpx": {
      "command": "npx",
      "args": ["-y", "@openpx/mcp"]
    }
  }
}

Claude Desktop

In ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "openpx": {
      "command": "npx",
      "args": ["-y", "@openpx/mcp"]
    }
  }
}

After editing, restart the client.

What's exposed

Tools

| Tool | What it does | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | search_methods | Fuzzy search across method names, summaries, descriptions, tags. Optional tag filter (Markets, Orders, Positions, Balance, Orderbook, Trades, Fills, Server). | | get_method | Full signature, typed parameter list, return type, and a runnable snippet in python | typescript | rust for the chosen exchange (kalshi | polymarket). | | get_type | Resolve a type from openpx.schema.json (Market, Order, Orderbook, Fill, …) with referenced sub-types inlined. | | list_websocket_channels | Enumerate orderbook, trades, fills, crypto, sports, etc. with their messages. | | get_websocket_channel | Full description of one channel + a runnable subscribe snippet in the chosen language. | | get_setup_instructions | Auth/credentials guidance for kalshi or polymarket, plus a minimal Exchange construction snippet. | | get_version | Returns the openpx version this MCP was built against and the sync timestamp. Use it to detect drift. |

Resources

• openpx://spec/openapi — the full OpenAPI 3.1 spec (YAML)
• openpx://spec/asyncapi — the full AsyncAPI 3.0 spec (YAML)
• openpx://schema/types — the unified JSON Schema for all resource types
• openpx://docs/llms.txt — the LLM-tuned docs index
• openpx://sdk/python/readme, openpx://sdk/typescript/readme
• openpx://sdk/typescript/types — the actual NAPI-generated index.d.ts
• openpx://setup/kalshi, openpx://setup/polymarket

Prompt

• bootstrap_openpx_client — slash-command-friendly preset that walks the agent through scaffolding a fresh openpx client.

How it stays current

Every openpx release cuts a matching @openpx/mcp@<version>. The pipeline:

1. openpx CI publishes Rust crates / PyPI / npm SDKs as it does today.
2. After SDKs publish, openpx CI fires a repository_dispatch (openpx-released) at this repo with the new tag.
3. .github/workflows/sync-on-release.yml re-vendors the specs, bumps package.json to match openpx semver, runs the test suite, and opens an auto-merge PR.
4. On merge, .github/workflows/publish.yml ships @openpx/mcp@<version> to npm.
5. A daily cron run also polls the openpx Releases API as a fallback if the dispatch is ever missed.

When agents call npx -y @openpx/mcp they always pull the latest version, and the server reports its bundled openpx version via get_version so an agent can warn the user if the installed openpx differs.

Develop

npm install
npm run sync-specs            # vendor specs from ../openpx (sibling checkout)
npm run build
npm test
node dist/server.js           # run over stdio for manual testing

npm run sync-specs accepts:

• --from-local <path> (default: ../openpx) — copy from a local openpx checkout
• --from-github <ref> — fetch from raw.githubusercontent.com at a tag/branch/sha
• --bump-package — also write the detected version into package.json

License

MIT