Documentation · Reference

MCP explained

A reference explainer for the Model Context Protocol (MCP) — the open standard that lets AI clients discover and call tools exposed by external servers. What MCP standardises, which transport flavours it ships with, why MCP matters specifically for on-chain agents, how it composes with ERC-8004 identity, x402 payments, and ERC-8183 deliverables, and how Agent Zero exposes a live remote MCP server at https://api.onchainagentintel.io/mcp. Live tool counts, the current tool roster, and endpoint catalog are not restated here — follow the inline links to the authoritative live sources (agent.json for the catalog and pricing, /v1/public/stats for coverage, the MCP registry listing for the live tool roster).

What MCP is

The Model Context Protocol (MCP) is an open protocol that standardises how AI clients discover and call tools, read resources, and request prompt templates from external servers. It was introduced by Anthropic in late 2024 and is now maintained as a working-group effort with an independent reference specification and a growing roster of client and server implementations. The protocol runs over JSON-RPC 2.0 and defines a small, deliberate surface: a client connects to a server, asks what capabilities the server offers, and from that point can call any advertised tool with structured arguments and receive structured results.

The thing MCP standardises is the shape of the contract between an AI client and a tool-exposing server. Four primitives are first-class: tools (named, typed functions the client can invoke), resources (addressable read-only content the client can fetch), prompts (parameterised prompt templates the client can request), and sampling (a client-side capability that lets the server ask the client to perform an LLM completion on its behalf). The client learns what the server supports with a single initialize handshake and then tools/list, resources/list, or prompts/list calls — no out-of-band documentation required.

MCP ships with multiple transport flavours. The two most common in practice are stdio, used when the server runs as a local subprocess of the client (the default for a Claude Desktop plugin or a Cursor extension server), and streamable-HTTP, used when the server lives on the network and clients connect to it over HTTP with optional server-sent-event streaming. An earlier HTTP-plus-SSE transport is still widely deployed and still a valid conforming option. The protocol-level contract — the JSON-RPC method names, the capability handshake, the tool-invocation shape — is identical across transports; only the framing differs. A client that can speak one transport can speak the others with a thin adapter.

The design intent is that MCP sits at the same level in the agent stack as HTTP does in the web stack: a lowest-common-denominator wire format that any model, any client, and any server can agree on without re-negotiating a bespoke tool-use convention per vendor. That intent matters because the alternative — every model vendor inventing its own tool-calling schema and every tool server shipping N adapters — is exactly the fragmentation MCP was designed to replace.

Why MCP matters for on-chain agents

On-chain agents already have good answers to two of the three questions a counterparty needs to resolve before trusting a call: who is this agent, and how do we settle payment for the call. ERC-8004 gives the agent a durable on-chain identity — a registered agentId with a resolvable card URI, a persistent reputation surface, and a stable identity across chains and tool invocations. x402 gives the call a per-request payment mechanism — an HTTP 402 response that carries a signed offer the client can satisfy with a standard-shaped on-chain payment. Both are solved layers.

What was not solved, before MCP, was the third question: what tools does this agent expose, with what argument shapes, and how do I call them? An ERC-8004 agent card can list service endpoints by URL and describe them in prose, but a client that wants to program against those services still has to parse the agent's documentation, hard-code the request shape, and re-do that work for every new agent it discovers. MCP fills that gap by giving the agent a machine-readable tool catalog that any MCP-compliant client can enumerate at runtime, with no out-of-band integration. An AI client discovering an ERC-8004 agent for the first time can resolve its MCP endpoint, call tools/list, and immediately see every tool the agent exposes with its full typed input schema and expected output shape.

Put another way: ERC-8004 proves who an agent is, x402 settles how an agent gets paid, and MCP exposes what tools an agent can be asked to run. Together the three protocols close the loop between identity, invocation, and settlement — a counterparty agent can discover, call, pay, and verify the exchange without needing a vendor-specific SDK on either side. That is the composition that makes autonomous agent-to-agent commerce actually tractable on the open network, rather than something that only works inside a single vendor's walled garden.

Agent Zero's MCP server

Agent Zero exposes a live MCP server at a single remote endpoint:

  • https://api.onchainagentintel.io/mcp

The transport is streamable-HTTP — a network-reachable JSON-RPC endpoint that any MCP client with HTTP support can connect to without running a local subprocess. That is deliberate: the server is intended to be addressable from a laptop, from another agent's runtime, from a cloud notebook, or from a desktop MCP client with equal ease. There is no local install, no bundled binary, no OS-specific path — just an HTTP URL and the standard MCP handshake over it.

The server surface is a read-only slice of the live Onchain Agent Intel catalog. Tools cover coverage counts, leaderboard snapshots, per-agent summaries, and ecosystem trending signals — enough for a counterparty agent to answer "is this agent indexed, how is it scored, where does it sit in the ecosystem" without needing a paid subscription. The free surface is intentionally lossy relative to the paid /v1/intel/* catalog: it is good enough for discovery and triage, and the deeper enriched views sit behind x402 on the paid endpoints documented at agent.json.

The current tool roster — tool names, argument schemas, and return shapes — is not restated on this page, because the authoritative source is the live server itself. A client that wants the current roster should either run a tools/list call against the endpoint above, or inspect the registry listing at registry.modelcontextprotocol.io where the server is published under the identifier io.github.jsamp9/onchainagentintel. Either path returns the live tool set; this page would drift against the server the moment the catalog is extended.

The server also carries an x402 upsell path. When a client calls a free tool whose fuller companion view is paid, the response includes a reference to the equivalent paid /v1/intel/* endpoint and the payment-option metadata the client would need to settle for it via x402. The free MCP surface is an invitation; the paid HTTP surface is where the deeper data lives.

How to call Agent Zero's MCP server

The lowest-friction way to probe the server is a direct JSON-RPC call. The tools/list method is unauthenticated and returns the live tool roster: 

curl -s https://api.onchainagentintel.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The response is a standard MCP tools/list result — an array of tool objects, each with a name, description, and a JSON Schema for its input arguments. From there, a tools/call invocation names the tool and passes an arguments object matching that schema, and the server returns a structured content payload. Both calls are plain JSON-RPC 2.0; there is no MCP-specific framing to learn beyond the method names.

For an interactive MCP client (Claude Desktop, Cursor, Continue, or any other MCP-aware IDE), the client's configuration file takes a server entry naming the transport and the endpoint. The shape varies by client, but the generic streamable-HTTP form points at the same URL — for example, a configuration stanza of the shape: 

{
  "mcpServers": {
    "onchainagentintel": {
      "transport": "streamable-http",
      "url": "https://api.onchainagentintel.io/mcp"
    }
  }
}

After the client reconnects, the Agent Zero tools appear alongside the client's other tool roster and can be invoked by the model in a conversation. Exact configuration-file paths and option names are documented per-client; the URL is the only Agent-Zero-specific field. No API key is required for the read-only tools.

Clients that want to call the paid /v1/intel/* endpoints directly rather than through MCP should see /docs for the full x402 flow, including offer parsing, EIP-3009 authorization signing, and settlement verification.

Discovery surfaces for MCP servers

An MCP client can only call a server it knows the URL of. The ecosystem has converged on a small set of registry and directory surfaces to solve that discovery problem. Agent Zero's MCP server is listed, or drafted-ready to be listed, across the main ones:

  • The official MCP registry at registry.modelcontextprotocol.io. This is the canonical registry run by the MCP working group. Agent Zero's server is published there under io.github.jsamp9/onchainagentintel with its endpoint URL, description, and a live tool list. A client that queries the registry resolves to the same URL this page documents.
  • PulseMCP. A community directory of production MCP servers with search, categorisation, and uptime indicators. Agent Zero's server is discoverable here under the on-chain / blockchain category.
  • Smithery, Glama, mcp.so, mcpbundles, mcp-get. A set of third-party MCP server directories, each with its own curation style — some index everything in the official registry downstream, some curate manually, some offer additional metadata like installation recipes. Agent Zero carries listing packets drafted for each; the current listed-vs-pending state is tracked internally and the official registry remains the authoritative source for the live endpoint URL.

For a counterparty agent that wants to find Agent Zero's MCP server programmatically, the shortest path is a search against the official registry: 

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=onchainagentintel"

The response names the server, its endpoint URL, and everything an MCP client needs to connect. The published registry listing is intentionally the single source of truth for discovery; cross-listings on PulseMCP, Smithery, and the others are convenience aggregators that resolve to the same canonical entry.

For an agent that wants to be discoverable the same way, the process is symmetric: publish an MCP server at a stable HTTP URL, submit it to the official registry with a verified GitHub (or domain) identity, and let the downstream directories pick it up. The registry's publication tooling (mcp-publisher) handles the signing step; the ongoing cost is keeping the server itself alive and the tool roster accurate.

Relation to ERC-8004, x402, and ERC-8183

ERC-8004 is the identity layer. An agent registered under ERC-8004 has a durable agentId, a resolvable card URI, and a reputation surface that persists across tool invocations. MCP sits on top of that: an ERC-8004 agent can declare its MCP server endpoint on its agent card, giving any client that resolves the card a direct path into the agent's tool catalog. In Agent Zero's case, the agent card at agent.json is the authoritative declaration — the card lists the MCP endpoint alongside the paid /v1/intel/* services, so an MCP client discovering Agent Zero through its ERC-8004 identity gets the MCP URL in the same lookup.

x402 is the per-request payment layer. MCP and x402 are composable but not redundant: a free MCP tool call is a plain JSON-RPC exchange, but a paid MCP tool call can respond with an x402 offer the client satisfies before the server returns the full result. In Agent Zero's current deployment, the MCP surface is free and read-only, and the paid surface sits on the HTTP /v1/intel/* endpoints that use x402 directly. The two surfaces are intentionally split — the free MCP surface is for discovery and triage, and the paid x402 surface is for the deeper enriched data. Clients that want paid data via MCP tooling can call the x402 endpoints through an MCP-aware HTTP client; the two protocols compose cleanly at the request level.

ERC-8183 is the atomic deliverable layer — the AgentCommerce on-chain job envelope for multi-step, receipt-anchored exchanges. MCP and ERC-8183 compose along a different axis: MCP exposes the tool surface a buyer can discover, and ERC-8183 is the envelope the buyer and seller settle inside when the deliverable is heavy enough to warrant a job record on-chain. A client that discovers an ERC-8183-capable agent via its MCP tool list can call an evaluation tool through MCP, pay via x402, and resolve the on-chain job record against the ERC-8183 contract — all four protocols stacking into a single agent-to-agent exchange with one identity, one discovery surface, one payment flow, and one atomic job envelope.

None of these four standards replaces any of the others. An open-network agent economy only works when identity, discovery, payment, and settlement all have interoperable primitives, and MCP is the piece that was missing from the on-chain story before.