Portable declaration of a paid (pay-per-call) MCP server in an Agent Plugin

[dhyabi2]

Proposal: a portable way to declare a paid (pay-per-call) MCP server in an Agent Plugin

The concrete interoperability problem

Agent Plugins wraps MCP servers for clients like ChatGPT, Cursor, Copilot, VS Code and Kiro, but the spec's mcp.json gives a client no way to know that a declared streamable-http server is paid — i.e. that an unpaid tool call will return HTTP 402 Payment Required with an accepts[] payment-requirement envelope, and that the client is expected to settle and retry.

Paid MCP servers are a real and growing category today (pay-per-call marketplaces already ship streamable-http servers that sell tool calls per request and settle the quote on-chain). Without a portable marker, a client cannot distinguish a free server from a pay-per-call one before running a workflow, and plugin authors cannot declare a monetized server in a way every client understands.

Who encounters it

• Plugin authors shipping monetized MCP servers (per-call billing, quoted settlement) who want their server installed as a conformant Agent Plugin.
• Client implementers (ChatGPT, Cursor, Copilot, VS Code, Kiro) that must decide whether to pre-authorize a payment budget or surface a settlement step when a call returns 402.

Why it belongs in the portable spec, not client policy

Whether a server is paid is part of its interoperation contract: a client that silently treats a 402 as a generic error will fail every paid call, while a client that pre-charges every server would block free ones. A portable declaration lets each client handle the settlement handshake it supports, without divergence.

A concrete, schema-conformant starting shape

A paid server is still declared as a normal streamable-http server; the payment handshake lives at the HTTP layer (an unpaid call returns 402 + accepts[]). What is missing is a marker + a documentation example. Both files below validate clean against the shipped schemas/1.0.0:

plugin.json — validated against plugin.schema.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "nano-x402-pay"
}

mcp.json — validated against mcp.schema.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "nano-paid": {
      "type": "streamable-http",
      "url": "https://PAID-MCP-ENDPOINT.example/mcp"
    }
  }
}

(Example is not a live endpoint.) The point of this proposal is the marker, so a client and a server can agree a server is paid before the first call. Suggestions for the exact shape welcome — e.g. a "payment": true or an explicit "settlement" field listing the accepted x402 accepts[] schemes, of which a feeless, instant rail (zero gas, no fee floor) is one option alongside USDC. I'd be glad to draft the spec language + schema change and an editorial PR once the shape is agreed here.

Verification performed

• python3 -m jsonschema validated both example files against the repo's shipped schemas/1.0.0/plugin.schema.json and schemas/1.0.0/mcp.schema.json (draft 2020-12). A negative control (server type set to a bogus value) is rejected by the schema, so the positive result is meaningful.
• Default rails are unchanged: USDC/any existing scheme stays the default; this only adds a portable way to declare a server is paid and which schemes it accepts.