@antfeed/mcp

Discover and transact on the AntSeed P2P AI network from any MCP-compatible AI agent.

A Model Context Protocol server that turns the AntFeed Explorer into a one-line discovery front door for Claude Code, Cursor, Claude Desktop, and any other MCP host. List sellers, look up provider addresses, inspect on-chain payment channels, and (when a local AntSeed buyer is running) open new sessions — all from inside your agent.

Install

Add the following block to ~/.claude.json (Claude Code), claude_desktop_config.json (Claude Desktop), or your IDE's MCP config:

{
  "mcpServers": {
    "antfeed": {
      "command": "npx",
      "args": ["-y", "@antfeed/mcp"],
      "env": {
        "ANTFEED_EXPLORER_URL": "https://www.antfeed.org",
        "ANTSEED_BUYER_URL": "http://localhost:8377"
      }
    }
  }
}

Restart your MCP host. The server boots over stdio and exposes the tools below.

Tools

Every tool returns both structuredContent (typed object matching its declared outputSchema) and content[0].text (the same payload serialized as JSON, for older MCP clients). Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are exposed so hosts like Claude Desktop / Cursor can render confirm dialogs before destructive calls.

Example: list top providers

// tool call
{ "name": "list_providers", "arguments": { "limit": 3, "sort": "score" } }

Returns the top three sellers ranked by total USDC earned. To paginate, pass back the returned nextCursor as cursor on the next call.

Data sources

The MCP wraps the following AntFeed Explorer endpoints:

• GET /api/providers — provider directory (displayName, services, per-service pricing, region, on-chain aggregates). Refreshed hourly from network.antseed.com. Backs list_providers and lookup.
• GET /api/sellers/{address}/services — one seller's service catalog + live pricing. Backs get_pricing.
• GET /api/channels — on-chain payment channel records. Backs get_session_status.
• GET /api/stats — network-wide aggregates (revenue, sessions, drift). Backs network_stats.
• GET /api/gas — current Base gas price. Backs network_stats.
• GET /api/buyers/{address} + GET /api/score/{address} — buyer detail, session history, top sellers, and trust-score breakdown. Backs get_buyer.
• GET /api/metrics/dau — daily active users, by UTC day. Backs dau_trend and the DAU field in network_stats.

A few small client-side adaptations remain:

• No server-side /api/search yet → lookup performs client-side substring matching over the top page of /api/providers (matching against address, displayName, and service names). A future server-side endpoint will let lookup scale past 1000 providers — the MCP will switch over without any client changes.
• No per-channel /api/channels/{id} yet → get_session_status paginates /api/channels (sorted by last_activity desc) and filters client-side. Channels deeper than 5000 records may return SESSION_OUT_OF_RANGE.

Config

All values are optional. Resolution order: --config file.json → environment variable → built-in default.

You can also pass --config path/to/config.json with the same keys (camelCase: explorerUrl, buyerUrl, timeoutMs, logLevel, buyerStrict, maxDepositUsdc).

Buyer auto-detect

On startup the server probes GET <ANTSEED_BUYER_URL>/health with a 500 ms timeout:

• reachable → registers create_session.
• not reachable → registers buyer_setup (a diagnostic tool with install instructions) instead, and create_session is omitted from the tool list.

Detection runs once at startup. Restart the MCP host after installing or starting a buyer.

Error model

Every tool returns either a successful structured payload or an MCP error result with isError: true and a structured body of shape:

{ "error": { "code": "EXPLORER_DOWN", "message": "..." } }

Security model

Installing @antfeed/mcp is an explicit trust decision. Read this section before letting an autonomous agent call its tools.

• The agent caller is treated as untrusted. Every tool argument is validated by a strict zod schema before any network call. peerId/providerPeerId must be 0x + 40 hex chars; sessionId must be 0x + 1–128 hex chars; service is bounded to a short identifier; initialDepositUsdc is hard-capped by ANTSEED_MAX_DEPOSIT_USDC (default 10 USDC). A prompt-injected agent cannot move arbitrary amounts or craft URL/path-traversal payloads through this MCP.
• The explorer is treated as semi-trusted. Every response from ANTFEED_EXPLORER_URL is re-validated against a strict zod shape — addresses must be 40-hex, channel IDs must be hex, numeric fields must be finite. Responses are streamed with a 2 MB byte cap so a compromised or hijacked endpoint cannot exhaust memory. Plain http:// is only permitted for loopback hosts; non-loopback URLs must be https://.
• The local buyer holds your signing key; this MCP never sees it. The MCP only ever POSTs create_session (with bounded deposit, validated input) to the buyer URL — it does not read or store any key material. To prevent another local process from impersonating the buyer (e.g. on shared/multi-tenant dev boxes), set ANTSEED_BUYER_STRICT=1 and have your buyer respond to /health with {"service":"antseed-buyer"}.
• The package itself ships minimally. dist/, README, LICENSE — no postinstall scripts, no test files, no source maps that leak local paths. npm audit --omit=dev reports zero production-tree vulnerabilities. Dependencies are pinned to ~ ranges; on publish, the package is signed with npm provenance so consumers can verify the tarball came from this repo (npm audit signatures).
• Error messages are sanitized. File paths, IP addresses, and UPPER_CASE_VAR=… patterns are scrubbed before any error reaches the agent or the MCP host's logs.

If you spot a security concern, please open a private GitHub Security Advisory — we triage these within 72 hours. Do not file a public issue for security-impacting bugs.

For sellers

If you already operate an AntSeed seller and you appear in the AntFeed Explorer directory, you are automatically discoverable through this MCP — no extra registration. New sellers join the directory by simply transacting on-chain (the explorer indexes Base mainnet AntSeed Channels events). Once /api/services and /api/sellers/{address}/services land, get_pricing and list_providers#servicesOffered will populate without any client changes.

Develop

npm install
npm run build         # tsc → dist/
npm test              # vitest, fully mocked, zero network
node dist/index.js    # stdio server (MCP host wires this up; not interactive)

Smoke test the MCP handshake with the official inspector:

npx @modelcontextprotocol/inspector dist/index.js

Registry submission

The package is submitted to the public MCP server registries (registry.modelcontextprotocol.io, Smithery, PulseMCP, Glama, mcp.so) so any MCP-aware client can discover and install it without copy-pasting the snippet above. Source of truth for the official registry submission is server.json; the Smithery descriptor is smithery.yaml. The full submission checklist with current URLs lives in REGISTRIES.md. Registry repo: https://github.com/modelcontextprotocol/registry.

For per-tool usage observability on the Vercel dashboard, see USAGE.md.

Links

• AntFeed Explorer: https://antfeed.org
• AntFeed Explorer API docs (OpenAPI 3.0): https://antfeed.org/api/openapi.json
• AntSeed protocol contracts (Base mainnet): see the Explorer's About page

License

MIT