ENS Omnigraph MCP (AI agents)

Every ENSNode instance exposes the ENS Omnigraph API over the Model Context Protocol at /api/mcp, using the streamable-HTTP transport. This lets MCP clients — Cursor, Claude Desktop, and any agent that speaks MCP — run Omnigraph queries directly.

It’s first-party and built in: the same endpoint works locally (http://localhost:4334/api/mcp) and against any hosted instance, so there’s nothing to install or deploy — point your client at a URL and go.

No backend required

You don't need to run your own ENSNode to follow this guide — the steps below default to a NameHash-hosted instance. Browse the available deployments below.

Version compatibility with hosted instances

Our hosted ENSNode instances currently run ENSNode 1.15.1. The Omnigraph GraphQL schema is bundled inside the SDK and consumed by the gql.tada TypeScript plugin to type your queries, so pin an exact version (no ^ or ~) of enssdk@1.15.1 (and enskit@1.15.1 when using React) to keep your generated types matched to the deployed schema. Use these exact install commands:

npm install enssdk@1.15.1
# or, for React apps:
npm install enskit@1.15.1 enssdk@1.15.1

Hosted ENSNode Instances

Tools and resources

The server exposes two read-only tools:

• omnigraph_query — accepts a GraphQL query or vetted exampleId (and optional variables) and returns the raw { data, errors } JSON, exactly as the HTTP endpoint does. Because it’s the full Omnigraph behind one tool, an agent can answer any question the Omnigraph can — resolve records, search Domains, list a user’s Domains, and much more — without a fixed, hand-written tool per use case.
• omnigraph_schema — looks up Omnigraph types and fields from the bundled schema (no network). Use it before writing custom queries, especially for filter inputs like DomainsNameFilter.

It also ships resources: condensed schema at omnigraph://schema/condensed, example query index at omnigraph://examples/index, and per-example payloads at omnigraph://examples/{exampleId}. Pick a vetted exampleId from the index when you want a starting point (e.g. account-profile, domain-profile) — the agent chooses the right one for your question.

Cursor

Cursor supports streamable-HTTP MCP servers natively via a url in mcp.json.

Project-scoped (recommended when working in one repo) — create .cursor/mcp.json in the project root:

.cursor/mcp.json

{
  "mcpServers": {
    "ENS": {
      "url": "https://api.v2-sepolia.ensnode.io/api/mcp"
    }
  }
}

User-scoped (all projects) — use ~/.cursor/mcp.json with the same shape.

For a local ENSApi instance:

.cursor/mcp.json

{
  "mcpServers": {
    "ENS": {
      "url": "http://localhost:4334/api/mcp"
    }
  }
}

Then:

1. Open Cursor Settings → Tools & MCP (or Features → MCP).
2. Confirm ENS is listed with a green status and the omnigraph_query and omnigraph_schema tools.
3. In chat, ask ENS questions in plain language — e.g. “Who owns vitalik.eth?” or “List domains owned by 0x…” — and let the agent call omnigraph_query. Use the server key "ENS" in your config so the MCP entry is easy to spot; the agent picks the right exampleId or writes a custom query for your question.

Pair with ensskills

MCP gives the agent execution; ensskills gives it query authoring. Install the omnigraph skill so the agent writes correct GraphQL on the first try — see the ensskills quickstart or examples/ensskills-example to sync skills into .cursor/skills/.

Claude Desktop

Claude Desktop configures MCP servers in a JSON file (restart Claude after editing):

OS	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Many Claude Desktop builds expect stdio MCP servers rather than a remote URL. Bridge to ENSNode’s streamable-HTTP endpoint with mcp-remote:

claude_desktop_config.json

{
  "mcpServers": {
    "ENS": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.v2-sepolia.ensnode.io/api/mcp"
      ]
    }
  }
}

For local development, swap the URL for http://localhost:4334/api/mcp.

After restart, start a new conversation and ask ENS questions — Claude should invoke omnigraph_query when it needs indexed ENS data.

Claude Code / other MCP clients

Clients that support streamable HTTP directly (like Cursor) can use the "url" form instead of mcp-remote. Check your client’s MCP docs for whether it accepts a remote url or requires a stdio command.

Verify the connection

To smoke-test without an editor, use the MCP Inspector:

npx @modelcontextprotocol/inspector

Set Transport to Streamable HTTP, URL to your /api/mcp endpoint, connect, then List Tools — you should see omnigraph_query and omnigraph_schema. Call omnigraph_query with:

{
  "query": "{ __typename }"
}

Authoring queries

The MCP endpoint runs whatever GraphQL you hand it — it does not author queries for you. Use omnigraph_schema or read omnigraph://schema/condensed to discover the schema, then write queries (or pick a vetted exampleId from omnigraph://examples/index). You can also:

• Explore interactively in the GraphiQL playground at /api/omnigraph.
• Browse the Omnigraph Schema Reference and Omnigraph examples.
• Give your agent the ensskills omnigraph skill, which teaches the unified ENSv1 + ENSv2 datamodel, resolution, pagination, and vetted example queries — so it writes queries that work the first time.

Read-only

The Omnigraph is a read-only API, and so is this MCP server. It indexes and serves ENS state; it does not send transactions or mutate onchain data.

Where to go next

• Want to call the same API over plain HTTP, curl, or your own GraphQL client? See the ENS Omnigraph API (GraphQL) guide.
• Building integration code rather than driving an agent? Use enssdk (typed client) or enskit (React).

ENS Omnigraph API (GraphQL) The HTTP GraphQL API this MCP server wraps.

ensskills (AI agents) Agent skills that teach how to author Omnigraph queries.

Model Context Protocol The open protocol this endpoint implements.