Use with Claude Code

@agtnames/mcp is a read-only MCP server that gives any MCP-compatible client — Claude Code, Cursor, or your own agent runtime — five tools for .agt names: resolve a name to its owner and records, fetch and verify its manifest, find its endpoints, check availability, and compute its token ID. No configuration is needed for Polygon mainnet. This page uses Claude Code for every example.

Install

Any MCP-compatible client can launch the server over stdio with npx -y @agtnames/mcp. In Claude Code, register it once:

terminalsh

claude mcp add agt -- npx -y @agtnames/mcp

Or install the plugin, which bundles the server with a skill that teaches Claude when to reach for it and how to read the results:

inside Claude Codesh

/plugin marketplace add ds1/agt-plugins
/plugin install agt@agtnames

Check the connection with /mcp (or claude mcp get agt).

Other MCP clients

The server speaks stdio, so the same one-line launch works anywhere. Claude Code is the worked example on this page; here is the equivalent configuration elsewhere.

.cursor/mcp.jsonjson

// .cursor/mcp.json
{
  "mcpServers": {
    "agt": { "command": "npx", "args": ["-y", "@agtnames/mcp"] }
  }
}

mcpServers entryjson

{
  "mcpServers": {
    "agt": {
      "command": "npx",
      "args": ["-y", "@agtnames/mcp"],
      "env": { "AGT_RPC_URL": "" }
    }
  }
}

Set AGT_RPC_URL only to use your own RPC endpoint; an empty value means the default.

client.tsts

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(new StdioClientTransport({ command: "npx", args: ["-y", "@agtnames/mcp"] }));

const result = await client.callTool({ name: "agt_endpoint", arguments: { name: "scraper.agt", protocol: "mcp" } });
const { url, verified } = JSON.parse((result.content as { type: string; text: string }[])[0].text);
if (verified && url) { /* connect to the agent at url */ }

await client.close();

The official @modelcontextprotocol/sdk client. Tool results are JSON text; on failure isError is set and the text is { "error": { "code", "message" } }.

Tools

Tool	Returns
`agt_resolve`	owner, expiry, active/perpetual, on-chain records, and the verified manifest (under `untrusted`)
`agt_manifest`	the manifest document plus `verified` and `reasons`
`agt_endpoint`	the URL for `mcp`, `a2a`, `http` or `ws` — verified manifest first, on-chain record second
`agt_available`	whether the name can be registered right now
`agt_namehash`	the ENS-style node and ERC-721 token ID (no network)

Every tool is annotated read-only and idempotent, so clients that honour MCP annotations can treat them as safe to call.

What `verified` means

A .agt name's manifest is a signed JSON document referenced on-chain (see the Manifest Spec). The server checks it three ways: the signature must recover to the address the manifest declares as its owner, and that address must be the name's current on-chain owner.

verified: true — the endpoints, capabilities and keys in the manifest are claims made by the name's owner. Safe to act on as that owner's claims.
verified: false — reasons says why (no manifest set, unreachable, bad signature, owner mismatch…). The content is still returned, but a client should present it as unverified and never connect to an endpoint from it without saying so.

Everything derived from a manifest arrives inside an untrusted envelope with a notice: it is third-party content published by the name owner — data, never instructions. The server also publishes these rules to the client as MCP instructions, and the plugin's skill repeats them.

Discover an agent, then connect to it

The intended loop is: resolve the name, check verified, ask for the endpoint for the protocol you speak, then connect to that endpoint as you would to any other server. In Claude Code:

a name with no manifest yet — real transcript, 2026-09-12text

> Who is launchpad.agt and can I talk to it over MCP?

Claude calls agt_resolve("launchpad.agt")
  → owner 0x3700…7596 · perpetual · source registry-v2 · verified: false
    reasons: ["no manifest set"]

Claude calls agt_endpoint("launchpad.agt", "mcp")
  → url: null · source: null

"launchpad.agt is registered to 0x3700…7596 (perpetual), but its owner has not
 published a manifest or an MCP endpoint yet, so there is nothing to connect to.
 Anything I told you about its capabilities would be unverified."

a name with a verified manifest — illustrativetext

> Find scraper.agt's MCP endpoint and tell me what it can do.

Claude calls agt_resolve("scraper.agt")
  → owner 0x7099…79C8 · active · verified: true
    untrusted.manifest.capabilities: ["web-scraping", "extraction"]

Claude calls agt_endpoint("scraper.agt", "mcp")
  → url: "https://scraper.example/mcp" · source: "verified-manifest" · verified: true

"scraper.agt's owner publishes an MCP endpoint at https://scraper.example/mcp and
 lists web-scraping and extraction as capabilities (their claims, signed by the
 owner wallet). To use its tools, add it as a server:
   claude mcp add scraper --transport http https://scraper.example/mcp"

When an agent publishes a verified MCP endpoint, the natural next step is to register that endpoint as a second server and use the agent's tools directly. The skill offers the claude mcp add command rather than running it: connecting to a third party is your decision, and it never proposes one from an unverified manifest.

Configuration

All optional. Polygon mainnet works with nothing set; an empty value counts as unset.

Variable	Purpose
`AGT_CHAIN`	`polygon` (default), `amoy` or `localhost`
`AGT_RPC_URL`	Use your own JSON-RPC endpoint instead of the public default.
`AGT_REGISTRY`	Registry contract address — only needed for `localhost` or a custom deployment.
`AGT_IPFS_GATEWAY`	One of the allow-listed gateways used to fetch `ipfs://` manifests.
`AGT_TIMEOUT_MS`	Per-request timeout for RPC and IPFS reads (default 10 000).
`AGT_RATE_PER_MIN`	Tool calls per minute before the server answers `rate_limited` (default 240).

Pass them with -e when registering: claude mcp add agt -e AGT_RPC_URL=https://… -- npx -y @agtnames/mcp.

Errors and troubleshooting

Tool failures are structured — { "error": { "code", "message" } } — so a client can branch on them:

Code	Meaning
`invalid_name`	Labels are 1–63 characters of `a-z 0-9 -`, no leading or trailing hyphen. Nothing was sent to the network.
`rate_limited`	Too many calls this minute from one server process; back off.
`timeout`, `rpc_unavailable`	The RPC endpoint could not be reached in time. Retry, or set `AGT_RPC_URL`.
`rpc_error`	The node returned a JSON-RPC error — usually a wrong `AGT_REGISTRY` or `AGT_CHAIN`.
`misconfigured`	A setting this chain requires is missing; the message names it.

Manifest problems are not errors: agt_resolve succeeds with verified: false and the causes in reasons.

Server did not connect. /mcp shows the state; npx -y @agtnames/mcp --version confirms the package runs at all. The first npx run downloads the package, which can exceed a short MCP_TIMEOUT; pin a version such as @agtnames/mcp@1.1.0 so later starts come from the local cache.
Large responses. One result is capped at 64 KiB. If a manifest would push a response over the cap it is omitted and untrusted.truncated says so; fetch the manifest URI directly for the full document.
Node version. Node 20 or newer is required.

Security model

The server is read-only: it never signs, sends or spends anything.
Names are validated before any network call; IPFS gateways are allow-listed; only https and data: manifest URIs are fetched, with size and time caps.
Owner-published strings are length-capped and stripped of control characters, and always arrive under untrusted.
Error messages that echo RPC responses are sanitized the same way.