Molpha MCP

A Model Context Protocol (MCP) server that lets AI agents create, fetch, verify, and publish Molpha oracle data.

Molpha turns HTTP API responses into threshold-signed payloads that can be verified on Solana, EVM, and Starknet. This server exposes that workflow as a small set of MCP tools and keeps signing behind a local, Privy, or Turnkey-backed wallet.

[!WARNING] This release targets Solana Devnet and Sepolia verifier networks. Treat it as testnet software, not a production security boundary. Write tools spend SOL and may consume subscription quota unless dry-run mode is enabled.

What you can do

• Discover the active registry, oracle nodes, gateways, and verifier deployments.
• Derive a feedId locally from a declarative API spec — no transaction, no subscription required. Feeds are created lazily on first settle.
• Request a threshold-signed result and build verifier arguments for multiple chains, paid for either by an active USDC subscription or a self-funded x402 round.
• Build EVM/Starknet verifier call args, or submit a verified update to a Solana feed.
• Use a local keypair, Privy server wallet, or Turnkey wallet without changing the MCP tool surface.
• Put daily caps and a global dry-run default around agent-initiated writes and x402 spend.

MCP tools

molpha_verify stops at calldata by design: the Molpha verifier is stateless, so the agent executes verify() itself and the server never submits an EVM/Starknet transaction or vouches for a result it did not verify on-chain. Solana is the one leg this server settles — via molpha_execute or molpha_fetch_verified's autoSubmit — and there is no standalone Solana verify-simulation path; submit, then read the result back with molpha_get_latest.

molpha_execute and molpha_verify take the molpha_fetch_verified response as-is: no field remapping between calls, and short hex fields (the gateway emits a one-signer signersBitmap as "4") are zero-padded to their canonical widths server-side.

Quick start

Requirements

• Node.js 20 or later
• A Solana wallet funded with Devnet SOL
• Devnet USDC if you plan to use an active subscription or the x402 pay-per-request path
• An MCP client such as Cursor, Claude Desktop, or Codex

1. Install and build

git clone https://github.com/molpha/mcp.git
cd mcp
npm ci
cp .env.example .env
npm run build

2. Configure a signer

For local development, point OWNER_KEYPAIR at a Solana JSON keypair. Use an absolute path when an MCP client launches the server.

SIGNER_BACKEND=memory
OWNER_KEYPAIR=/absolute/path/to/owner-keypair.json
SOLANA_RPC=https://api.devnet.solana.com
GATEWAY_ENDPOINTS=

The same wallet owns feeds and any x402 escrow, authenticates gateway requests, and signs Solana transactions. Do not commit .env, wallet files, or credentials.

Other supported signer configurations:

See .env.example and the ready-to-edit files in examples for every backend.

3. Check the setup

npm run doctor

The doctor checks the compiled entry point, signer configuration, wallet availability, and Solana RPC. It also prints configuration snippets with resolved absolute paths.

4. Bootstrap a subscription

Subscription operations debit USDC, so they are deliberately kept out of the MCP tool surface. Run the provisioning CLI once with the same signer configuration used by the server:

# Preview without sending a transaction
npm run provision -- subscribe --plan Basic --max-price-usdc 20000000 --dry-run

# Subscribe, with a maximum approved price of 20 USDC (6 decimals)
npm run provision -- subscribe --plan Basic --max-price-usdc 20000000

Extend an existing subscription with:

npm run provision -- extend --max-price-usdc 20000000

--max-price-usdc is a safety cap in raw USDC base units, not a quoted plan price. The transaction aborts if the live on-chain price exceeds the cap.

5. Connect an MCP client

Pick one of the install paths below. In both cases the server speaks stdio JSON-RPC and needs the same signer settings from step 2.

Claude Desktop (MCPB)

Package the built tree into an MCP Bundle and install it as a desktop extension. The repo already includes a manifest.json that declares the Node entry point, tools, and user-config fields.

npm run build
npx @anthropic-ai/mcpb pack . molpha-mcp.mcpb

That writes molpha-mcp.mcpb in the repo root. Install it in Claude Desktop by any of:

• Double-click the .mcpb file
• Drag it into the Claude Desktop window
• Settings → Extensions → Advanced settings → Install Extension… → select the .mcpb file

During install, set the signer backend and related fields (local keypair path, Privy, or Turnkey). Those map to the same env vars as .env.example.

Cursor, Codex, or manual Claude Desktop config

Point the client at the built server (dist/src/server.js), not at src/server.ts:

{
  "mcpServers": {
    "molpha": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/src/server.js"],
      "env": {
        "SIGNER_BACKEND": "memory",
        "OWNER_KEYPAIR": "/absolute/path/to/owner-keypair.json",
        "SOLANA_RPC": "https://api.devnet.solana.com"
      }
    }
  }
}

• Cursor: save the JSON under mcpServers in .cursor/mcp.json or ~/.cursor/mcp.json. Ready-to-edit copies live in examples (cursor-memory.mcp.json, cursor-privy.mcp.json, cursor-turnkey.mcp.json).
• Claude Desktop: add the same block to claude_desktop_config.json and restart, or prefer the MCPB path above.
• Codex: use one of the Codex TOML examples, or run codex mcp add molpha -- node /absolute/path/to/mcp/dist/src/server.js and then add the signer variables to config.toml.

Restart the client after changing configuration or rebuilding. A direct node dist/src/server.js invocation waits silently for JSON-RPC on stdin; that is expected for a stdio server.

Example prompts

Once the server is connected, these prompts exercise the main workflows.

Discover the network

Use Molpha to inspect the current oracle capabilities. Summarize the registry version, node count, supported chains, gateway endpoints, and verifier addresses. Do not make any writes.

Preview a feed

Derive a Molpha feedId for https://api.example.com/v1/finalized/price using the JSON path $.price and 3 required signatures. Show me the API config hash, the derived feedId, and any determinism warnings. Do not send a transaction.

Replace the example URL with a public endpoint that returns stable, independently reproducible data. Live ticker endpoints may produce different values across oracle nodes and fail to reach quorum.

Fetch and verify a result

For that same feed, fetch a signed result with payment: "auto" and a maximum age of 60 seconds, for the EVM chain. Summarize the signed value, timestamp, registry version, quorum, and EVM verifier call, and tell me whether it was paid for via subscription or x402. Treat the signed artifact as the trust anchor; do not trust the value by itself.

Check x402 spend before paying

Call molpha_agent_status for 3 required signatures. Tell me the escrow's USDC balance, committed amount, and quoted next price before I authorize any x402 spend.

Publish with an approval checkpoint

Read the latest value for Molpha feed <FEED_ID>. If I provide a newer signed result, preview molpha_execute with dryRun: true, explain the fee-paying wallet and exact write, and wait for my confirmation before submitting it to Solana.

Architecture