# MCP Server

> **NOTE — unofficial library.** `@p4n/erc8004-ui` is an independent, community-built project. It is not affiliated with, maintained by, or endorsed by the authors of ERC-8004. It reads the standard's on-chain data through public subgraphs; it does not speak for the standard.

An MCP server that gives AI coding agents structured access to this library — the same component documentation the docs site renders, plus live checks against the deployed subgraph that static documentation cannot provide.

If your agent can already fetch [llms.txt](https://erc8004-ui.vercel.app/llms.txt), the MCP server adds three things: selective retrieval (fetch one component's docs instead of a 90KB bundle), no network dependency for documentation, and two live tools that answer questions about real on-chain state.

## Two ways to connect

| | Hosted HTTP | Local stdio |
| --- | --- | --- |
| Endpoint | `https://erc8004-ui.vercel.app/api/mcp` | `npx -y @p4n/erc8004-ui-mcp` |
| Transport | Streamable HTTP | stdio |
| Install | none | npm |
| Graph API key | not used | optional |
| Documentation tools | yes | yes |
| Live subgraph tools | no | yes, with a key |

The hosted endpoint is the fastest way in: no install, no key, open CORS, and a discovery manifest at [/.well-known/mcp](https://erc8004-ui.vercel.app/.well-known/mcp). It serves the four documentation tools only. The live tools stay local because they spend a Graph API key, and a public endpoint should not spend someone else's quota.

### Hosted endpoint

```bash
claude mcp add --transport http erc8004-ui https://erc8004-ui.vercel.app/api/mcp
```

It is a stateless dual-era server: it answers the current per-request-metadata revision (`2026-07-28`, including the mandatory `server/discover`) and the `initialize` handshake used by `2025-11-25` and earlier, so any current client works.

### Local server

Add the server to your MCP client configuration. For Claude Code:

```bash
claude mcp add erc8004-ui --env GRAPH_API_KEY=your-graph-api-key -- npx -y @p4n/erc8004-ui-mcp
```

Or configure it directly:

```json
{
  "mcpServers": {
    "erc8004-ui": {
      "command": "npx",
      "args": ["-y", "@p4n/erc8004-ui-mcp"],
      "env": { "GRAPH_API_KEY": "your-graph-api-key" }
    }
  }
}
```

`GRAPH_API_KEY` is the same read-only Graph key the components use — see [API Keys](https://erc8004-ui.vercel.app/docs/api-keys). It is optional: without it the four documentation tools work normally and the two live tools return setup instructions instead of results.

## Documentation Tools

These read a build-time snapshot of the same registry that generates this site, so they cannot drift from what you are reading. They need no network access.

### list_components

Lists every component grouped by registry. Takes an optional `group` filter (`Providers`, `Identity`, `Reputation`, `Validation`, `Activity`).

### get_component

Full documentation for one component — description, caveats, import line, usage, worked examples, an in-context composition example, the props table, and how it handles loading, error, and empty states. Accepts a name (`ReputationScore`) or a slug (`reputation-score`).

### get_setup_guide

Returns any guide from this site: `introduction`, `installation`, `concepts`, `api-keys`, `components`, `theming`, or `mcp`. Defaults to `installation`.

### get_types

The library's exported TypeScript definitions — the shape of the on-chain data these components render.

## Live Tools

These query The Graph at runtime. They exist because the deployed subgraph schema drifts from the documented data model, and because whether a component renders anything depends on the specific agent you point it at.

### check_chain_support

Introspects a chain's deployed subgraph and reports which components will actually work on it. Accepts a chain id (`8453`), a chain name (`base`), or a full `agentRegistry` string. Call it with no argument to list every chain the library has a subgraph for.

This catches a failure mode documentation cannot: when a deployed schema stops exposing a field that a component queries, that component breaks on that chain even though its docs are still correct. Checking first is cheaper than debugging an empty component later.

### check_agent

Looks up a specific agent and reports which components will render real data for it, which will render an empty state, and which are unsupported on its chain. Use it to verify an `agentRegistry` / `agentId` pair is real before building a UI around it.

An agent with no validations will render an empty `ValidationList` no matter how correct your code is. This tool tells you that before you write it.

## Why Both

The documentation tools answer *how do I use this component*. The live tools answer *will it show anything*. Static documentation can only answer the first — the second depends on chain state that changes independently of this library.

## If you would rather not use MCP

The same documentation is published as a plain read-only JSON API, described by an OpenAPI 3.1 document. No key, no client library, open CORS:

```bash
curl https://erc8004-ui.vercel.app/api                        # endpoint index
curl https://erc8004-ui.vercel.app/api/components             # every component
curl https://erc8004-ui.vercel.app/api/components/agent-card  # one component, in full
curl https://erc8004-ui.vercel.app/api/guides/installation
curl https://erc8004-ui.vercel.app/api/chains
```

Add `?format=markdown` to `/api/components/{slug}`, `/api/guides/{slug}` or `/api/types` to get the markdown rendering instead of JSON. Errors are JSON with a stable `error.code`, a `hint` saying what to do next, and an `allowed` list when the failure was an unknown identifier.
Every response carries the `RateLimit` and `RateLimit-Policy` headers (plus the older `RateLimit-Limit` / `-Remaining` / `-Reset` triple) describing a fair-use quota of 300 requests per 60 seconds; going over it returns a JSON `429` with `Retry-After`. If you want the whole reference and would rather not think about pacing, fetch [/llms-full.txt](https://erc8004-ui.vercel.app/llms-full.txt) once instead.

The specification is at [/openapi.json](https://erc8004-ui.vercel.app/openapi.json) (YAML at [/openapi.yaml](https://erc8004-ui.vercel.app/openapi.yaml)), and [/agents.md](https://erc8004-ui.vercel.app/agents.md) covers when to reach for this library at all.

## Reference

- Live page: https://erc8004-ui.vercel.app/docs/mcp
- Markdown source: https://erc8004-ui.vercel.app/docs/mcp.md