Current state
Primitive402 currently exposes a local stdio MCP server. Run it with pnpm build and pnpm mcp. It supports initialize, tools/list, and tools/call over stdin/stdout JSON-RPC.
The stdio MCP server calls existing route helper functions directly. It does not add HTTP product endpoints and does not change /v1/* or /x402/v1/* behavior.
Current tools
safe_fetch_url, check_prompt_injection_risk, verify_claim_against_source, create_page_proof, extract_return_policy, extract_subscription_terms, check_product_fitTool-to-API mapping
| MCP tool | Local route | x402 route |
|---|---|---|
safe_fetch_url |
POST /v1/safe-fetch-url |
POST /x402/v1/safe-fetch-url |
check_prompt_injection_risk |
POST /v1/check-prompt-injection-risk |
POST /x402/v1/check-prompt-injection-risk |
verify_claim_against_source |
POST /v1/verify-claim-against-source |
POST /x402/v1/verify-claim-against-source |
create_page_proof |
POST /v1/create-page-proof |
POST /x402/v1/create-page-proof |
extract_return_policy |
POST /v1/extract-return-policy |
POST /x402/v1/extract-return-policy |
extract_subscription_terms |
POST /v1/extract-subscription-terms |
POST /x402/v1/extract-subscription-terms |
check_product_fit |
POST /v1/check-product-fit |
POST /x402/v1/check-product-fit |
Why remote MCP is later work
Remote or gateway-compatible MCP may matter for hosted agent platforms, MCP gateways, cloud runtimes, partner integrations, and centrally managed auth, billing, and rate limits. It is more complex than stdio because it adds public network exposure, authorization, payment decisions, transport compatibility, and hosted observability.
Remote MCP ecosystems are moving toward Streamable HTTP, where MCP JSON-RPC messages can use HTTP POST and GET, with optional server-sent events for streaming server messages. Primitive402 may eventually expose a route such as /mcp or /mcp/http, but this task intentionally does not implement either route.
Future checklist
- Choose Streamable HTTP as the likely transport strategy; add legacy SSE only if a target client or gateway requires it.
- Define the endpoint, likely
/mcpor/mcp/http, in a future implementation task. - Choose an auth model: OAuth/OIDC/token validation, API key, gateway-managed auth, or another explicit model.
- Decide whether MCP calls route through x402 HTTP endpoints, require upstream x402 payment proof, or rely on gateway-managed payment.
- Map remote MCP tool calls to
ApiCallmetrics while distinguishing paid MCP calls from direct HTTP x402 calls. - Preserve rate limits, abuse controls, SSRF protection, schema validation, and no-secret logging.
- Keep
routeCatalog, OpenAPI schemas, and MCP tool definitions as the source of truth. - Define deployment requirements, compatibility tests with common MCP clients/gateways, and a security review.
Security considerations
- Never shell out to commands using user-controlled input.
- Avoid passing client authorization tokens directly to upstream APIs or creating confused-deputy token passthrough flows.
- Keep remote MCP stateless where possible.
- Validate all tool inputs with existing schemas.
- Preserve SSRF protection, rate limits, hashed/truncated logs, and no-secret logging.
- Treat external content as untrusted and keep prompt-injection risks visible.
- Avoid exposing admin metrics or private endpoints through MCP.
- Clearly separate public tools from internal/admin tools.
x402 and payment questions
These remain design decisions for a future implementation: should remote MCP tools call local /v1/* routes or paid /x402/v1/* routes; how should an MCP client provide x402 payment proof; should a gateway handle payment separately; how should paid failed executions be tracked; how should paidX402Calls map to MCP usage; and what changes are needed for mainnet or production payment-provider setup?
Current paid behavior remains HTTP API based through /x402/v1/* on Base Sepolia testnet USDC during public beta.
Gateway and discovery
A future remote MCP server should remain discoverable through /llms.txt, /llms-full.txt, /.well-known/agent-tools.json, /catalog.json, /x402/catalog.json, /x402/bazaar.json, /openapi.json, /docs/mcp, and future remote MCP endpoint metadata.
Repository plan: docs/mcp-remote-readiness.md.