Arcagents Mcp

[Arc Agents MCP]

Arc Agents MCP

Arc Agents MCP gives AI assistants, agents and other MCP-compatible clients access to ERC-8004 agent identity, metadata, reputation and validation data from Arc Mainnet, provided by Arc ERC-8004 Explorer - the Arc Agents platform - through a single tool: get_agent_data.

It is a standard Model Context Protocol server over stdio. One published npm package works in every client that can launch a local stdio MCP server: Claude Desktop, Cursor, Visual Studio Code, Claude Code, Cline, Gemini CLI, OpenAI Codex, Zed, MCP Inspector, and any other application, AI assistant or agent that supports standard MCP stdio connections.

Each successful request costs $0.002 USDC, paid automatically with x402 v2 (exact) from a wallet you control, on Arc Mainnet (default) or Base Mainnet.

• npm: https://www.npmjs.com/package/arcagents-mcp
• GitHub: https://github.com/Nomad07/arcagents-mcp
• Agent Skill: SKILL.md
• Arc ERC-8004 Explorer: https://www.arcagents.app
• API OpenAPI spec: https://www.arcagents.app/api/openapi.json

What you get

get_agent_data takes an ERC-8004 agent ID and returns the API's JSON response. Depending on the network and registry deployment, it can include:

• Identity and registration: owner, agent wallet, metadata URI, and the identity, reputation and validation registry addresses
• Metadata: parsed agent metadata (name, description, services, active, x402Support), or metadataError when it could not be fetched
• Reputation and feedback: client count, feedback count, aggregate score, clients, and individual feedback records
• Validation data: availability, request count and validation requests
• Links to the agent on the Arc ERC-8004 Explorer, and the fetch timestamp (fetchedAt)

Some data may be unavailable for a given agent or registry deployment. Errors from the API are returned with their original details.

Data network and payment network are different things. ERC-8004 data is always read from Arc Mainnet. The paid API serves Arc Mainnet data only; Arc Testnet data is not available through this server. Base is a payment network only: it can pay for a request, but no data is read from Base.

Payment

• Price: $0.002 USDC per successful request (2000 atomic units, 6 decimals)
• Protocol: x402 version 2, scheme exact (EIP-3009 transferWithAuthorization), using the official uvd-x402-sdk
• Facilitator: https://facilitator.ultravioletadao.xyz (no API key required)
• Gas: none for you. The facilitator submits the transfer.

Use a dedicated wallet. Create a new wallet just for this server and fund it with a small amount of USDC (a few cents covers many requests) on the network you select. Never use your main wallet and never share its private key.

Requirements

• Node.js 20 or newer
• A dedicated EVM wallet with a small USDC balance on Arc Mainnet (or Base Mainnet if you select base)
• An MCP client that can launch local stdio servers

No clone and no build step: every client below launches the published package with npx -y arcagents-mcp.

Install

You do not need to install anything by hand. Your MCP client runs npx -y arcagents-mcp and npm downloads the package on first use. To install it globally instead:

npm install -g arcagents-mcp

then use arcagents-mcp as the command (with no arguments) in the configurations below.

Environment variables

A documented template is in .env.example. MCP clients pass these variables through their server configuration (shown below); the server does not read a .env file by itself.

Setup by client

Every client launches the same command: npx -y arcagents-mcp. Replace YOUR_EVM_PRIVATE_KEY with the key of your dedicated wallet. Set ARCAGENTS_PAYMENT_NETWORK to base to pay on Base instead of Arc. The server runs over stdio: launched by hand (with EVM_PRIVATE_KEY set), it prints a one-line readiness message on stderr and waits for a client.

On Windows, if a client cannot start npx directly, use "command": "cmd" with "args": ["/c", "npx", "-y", "arcagents-mcp"].

1. Claude Desktop

Open Settings > Developer > Edit Config, or edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{  "mcpServers": {    "arcagents": {      "command": "npx",      "args": ["-y", "arcagents-mcp"],      "env": {        "EVM_PRIVATE_KEY": "YOUR_EVM_PRIVATE_KEY",        "ARCAGENTS_PAYMENT_NETWORK": "arc"      }    }  }}

Restart Claude Desktop completely.

2. Cursor

Edit ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project, or use Settings > Tools & MCP > Add Custom MCP Server:

{  "mcpServers": {    "arcagents": {      "command": "npx",      "args": ["-y", "arcagents-mcp"],      "env": {        "EVM_PRIVATE_KEY": "YOUR_EVM_PRIVATE_KEY",        "ARCAGENTS_PAYMENT_NETWORK": "arc"      }    }  }}

To keep the key out of the file, use "EVM_PRIVATE_KEY": "${env:EVM_PRIVATE_KEY}" and export the variable before starting Cursor.

3. Visual Studio Code

Current VS Code (Copilot) reads MCP servers from a top-level mcpServers object in one of two files:

• Workspace: .mcp.json in the workspace root (shareable with your team)
• User (all workspaces): ~/.copilot/mcp-config.json

You can also add a server from the UI: Chat: Open Customizations, then MCP Servers, Add Server, Command (stdio), with command npx -y arcagents-mcp.

{  "mcpServers": {    "arcagents": {      "type": "stdio",      "command": "npx",      "args": ["-y", "arcagents-mcp"],      "env": {        "EVM_PRIVATE_KEY": "${EVM_PRIVATE_KEY}",        "ARCAGENTS_PAYMENT_NETWORK": "arc"      },      "tools": ["*"]    }  }}

${EVM_PRIVATE_KEY} is a reference, not the key: it is read from the environment VS Code runs in, so export the variable and start VS Code from that shell (for example export EVM_PRIVATE_KEY=0x... then code .). A reference is safe to commit; a literal key is not, so never put the real key in .mcp.json. Use the braced ${NAME} form: VS Code treats a bare $NAME as literal text. In the Customizations form, edit .mcp.json as text to keep ${...} references.

Legacy format (deprecated). Older VS Code configurations use .vscode/mcp.json (or MCP: Open User Configuration) with a top-level servers key instead of mcpServers. VS Code documents this editor-managed format as belonging to the deprecated Local harness and recommends the files above for new setups. Use it only to maintain an existing configuration:

{  "inputs": [    {      "type": "promptString",      "id": "evm-private-key",      "description": "Private key of the dedicated Arc Agents MCP payment wallet",      "password": true    }  ],  "servers": {    "arcagents": {      "type": "stdio",      "command": "npx",      "args": ["-y", "arcagents-mcp"],      "env": {        "EVM_PRIVATE_KEY": "${input:evm-private-key}",        "ARCAGENTS_PAYMENT_NETWORK": "arc"      }    }  }}

4. Claude Code

Add the server with one command (user scope makes it available in every project):

claude mcp add --transport stdio --scope user \  --env EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY \  --env ARCAGENTS_PAYMENT_NETWORK=arc \  arcagents -- npx -y arcagents-mcp

Or share it with a team through a project-level .mcp.json that reads the key from each developer's environment:

{  "mcpServers": {    "arcagents": {      "command": "npx",      "args": ["-y", "arcagents-mcp"],      "env": {        "EVM_PRIVATE_KEY": "${EVM_PRIVATE_KEY}",        "ARCAGENTS_PAYMENT_NETWORK": "arc"      }    }  }}

Check it with claude mcp list, or /mcp inside Claude Code.

5. Cline

In the Cline panel open MCP Servers > Configure > Configure MCP Servers. This opens cline_mcp_settings.json. Add:

{  "mcpServers": {    "arcagents": {      "command": "npx",      "args": ["-y", "arcagents-mcp"],      "env": {        "EVM_PRIVATE_KEY": "YOUR_EVM_PRIVATE_KEY",        "ARCAGENTS_PAYMENT_NETWORK": "arc"      },      "disabled": false,      "autoApprove": []    }  }}

Leave autoApprove empty so every paid call asks for your approval. The Cline CLI uses the same definition in ~/.cline/data/settings/cline_mcp_settings.json.

6. Gemini CLI

Edit ~/.gemini/settings.json (all projects) or .gemini/settings.json (one project):

{  "mcpServers": {    "arcagents": {      "command": "npx",      "args": ["-y", "arcagents-mcp"],      "env": {        "EVM_PRIVATE_KEY": "$EVM_PRIVATE_KEY",        "ARCAGENTS_PAYMENT_NETWORK": "arc"      }    }  }}

Gemini CLI expands $EVM_PRIVATE_KEY from your shell, so export it first (export EVM_PRIVATE_KEY=0x...). Variables listed explicitly in env are passed to the server even though Gemini CLI redacts key-like variables from the inherited environment. Or add it from the command line. The -- makes everything after it, including -y, arguments of npx rather than options of gemini:

gemini mcp add -s user -e EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY -e ARCAGENTS_PAYMENT_NETWORK=arc arcagents npx -- -y arcagents-mcp

Run /mcp inside Gemini CLI to confirm it is connected.

7. OpenAI Codex

Edit ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.arcagents]command = "npx"args = ["-y", "arcagents-mcp"]startup_timeout_sec = 60# Forward the key from your shell environment instead of writing it in this file:env_vars = ["EVM_PRIVATE_KEY"]
[mcp_servers.arcagents.env]ARCAGENTS_PAYMENT_NETWORK = "arc"

startup_timeout_sec = 60 gives npx time to download the package the first time. To put the key in the file instead, add EVM_PRIVATE_KEY = "YOUR_EVM_PRIVATE_KEY" under [mcp_servers.arcagents.env] and remove env_vars. Or use the CLI:

codex mcp add arcagents \  --env EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY \  --env ARCAGENTS_PAYMENT_NETWORK=arc \  -- npx -y arcagents-mcp

Run /mcp in the Codex TUI to confirm.

8. Zed

Open the settings file (zed: open settings file) and add a custom server under context_servers. You can also use Settings > AI > MCP Servers > Add Server > Add Local Server:

{  "context_servers": {    "arcagents": {      "command": "npx",      "args": ["-y", "arcagents-mcp"],      "env": {        "EVM_PRIVATE_KEY": "YOUR_EVM_PRIVATE_KEY",        "ARCAGENTS_PAYMENT_NETWORK": "arc"      }    }  }}

Open the Agent Panel settings and check that the server shows a green indicator, then enable its tool in the profile you use.

9. MCP Inspector

MCP Inspector is the quickest way to test the server and call the tool by hand.

npx @modelcontextprotocol/inspector \  -e EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY \  -e ARCAGENTS_PAYMENT_NETWORK=arc \  npx -y arcagents-mcp

Pass the variables with -e: Inspector does not forward your shell's environment to the server.

Or open the Inspector UI (npx @modelcontextprotocol/inspector) and fill in:

Click Connect, open Tools > List Tools to see get_agent_data. Running the tool makes a real $0.002 payment. To list the tools without paying, use CLI mode:

npx @modelcontextprotocol/inspector --cli \  -e EVM_PRIVATE_KEY=YOUR_EVM_PRIVATE_KEY \  npx -y arcagents-mcp --method tools/list

Any other MCP client

Any application, AI assistant or agent that supports standard MCP stdio connections can use this server. Configure it to launch npx with arguments -y arcagents-mcp and pass EVM_PRIVATE_KEY in the process environment. Clients that cannot launch local stdio servers (for example web-only chat apps that only accept remote HTTP MCP URLs) cannot use it.

Using the tool

Ask your assistant something like:

Use the Arc Agents MCP server to get the ERC-8004 data for agent 15.

Tool call

{  "name": "get_agent_data",  "arguments": { "agentId": 15 }}

agentId must be a positive integer. Anything else is rejected before any request or payment is made.

Example response. The shape follows the production OpenAPI schema (AgentResponse). The values below are illustrative placeholders, not live data:

{  "agentId": 15,  "network": "mainnet",  "chainId": 5042,  "identity": {    "owner": "0x<OWNER_ADDRESS>",    "agentWallet": "0x<AGENT_WALLET_ADDRESS>",    "metadataUri": "ipfs://<CID>",    "registries": {      "identity": "0x<IDENTITY_REGISTRY>",      "reputation": "0x<REPUTATION_REGISTRY>",      "validation": null    }  },  "metadata": {    "name": "Example Agent",    "description": "What the agent does.",    "services": [{ "name": "web", "endpoint": "https://example.com" }],    "active": true,    "x402Support": true  },  "metadataError": null,  "reputation": {    "clientCount": 1,    "feedbackCount": 1,    "aggregateScore": "95",    "clients": ["0x<CLIENT_ADDRESS>"],    "feedback": [      {        "client": "0x<CLIENT_ADDRESS>",        "feedbackIndex": 1,        "value": "95",        "tag1": null,        "tag2": null,        "isRevoked": false      }    ]  },  "validation": {    "available": false,    "reason": "<reason when unavailable>",    "requestCount": null,    "requests": []  },  "links": {    "explorer": "https://www.arcagents.app",    "agentOnExplorer": "https://www.arcagents.app/<agent-page>"  },  "fetchedAt": "<ISO 8601 timestamp>"}

After a successful paid call the server adds a second text block with the settlement transaction hash and an explorer link when the API reports them. The first block is always the API JSON.

Agent Skill

This repository includes SKILL.md, an Agent Skill for AI assistants that use Arc Agents MCP. The MCP server provides the get_agent_data tool. The skill tells an assistant how to use it well: what data comes back, how to explain it without inventing values, how payments work, and how to handle 503, 409 and interrupted requests safely.

The skill does not replace the server setup above: the MCP server must be connected first. To use the skill, point an assistant that supports the Agent Skills format at SKILL.md using that product's own skill-loading instructions, or provide the file's contents as context in a conversation.

Payment behavior and error handling

For each new request the server:

1. Sends the request without payment and receives the API's 402 challenge.
2. Checks that the challenge is x402 version 2 and picks exactly one accepted requirement: the one for your ARCAGENTS_PAYMENT_NETWORK.
3. Refuses to sign unless that requirement is exact, for the expected USDC contract and EIP-712 domain on that network, for exactly 2000 atomic units, with a valid payTo recipient and an authorization window of at most 300 seconds. The recipient, amount and timeout are taken from the live challenge, not hardcoded.
4. Signs one EIP-3009 authorization with EVM_PRIVATE_KEY and resends the same request with it.

The server never switches to another network after a failure and never makes a second paid request to try a different payment method. The per-session limit (ARCAGENTS_MAX_PAYMENTS) is checked before anything is signed, and concurrent identical calls share one request.

A 503 caused by an RPC error before settlement is not a paid successful request.

Interrupted requests. Before a signed payment is sent, it is saved as one small private file per request in ~/.arcagents-mcp (or ARCAGENTS_STATE_DIR). If a request ends without a final answer (503, 500, 409, 429, a timeout, a lost connection, or a response body that could not be read completely), asking again for the same agent ID resends the identical payment, including its X-UVD-Purchase context, and does not sign a new one. The saved payment context survives process restarts. The server reuses the same signed payment rather than creating a new authorization. The saved payment is removed once the API gives a final answer (any response other than 5xx, 409 or 429) and its body has been read completely. Nothing is retried automatically, and Retry-After is reported to you, not waited on.

If two MCP processes request the same agent ID at the same time, only one process can claim and send the payment. A competing process does not send another payment: it returns a temporary conflict message, and asking again reuses the saved payment.

A 409 carries a reason: authorization_already_settled (the SDK reports the authorization as already used, with payment confirmed) or receipt_request_conflict (the authorization belongs to another request; the API does not state whether it settled). Neither triggers a new authorization. If you have confirmed on chain that an earlier payment did not settle, delete that request's file in the state directory to start fresh. If the state cannot be read or written, nothing is signed or sent.

State directory security. The files contain signed authorizations. On macOS and Linux the server creates the directory 0700 and files 0600, and never modifies an existing directory. On Windows those modes provide no confidentiality; protection comes from the folder's ACL. The default is under your user profile (%USERPROFILE%\.arcagents-mcp). A custom ARCAGENTS_STATE_DIR must be an absolute path (~ is not expanded and relative paths are rejected) that only your account can read, with inherited access for other users removed on Windows.

API errors return the HTTP status, retryAfter when present, the API's original response under apiResponse, and a guidance sentence. Errors raised before or without an API response return error, message and guidance. The private key is never included in tool output or logs, and stdout carries only MCP protocol messages.

Limitations

• Paid API data covers Arc Mainnet agents only. Arc Testnet data, including what the Arc ERC-8004 Explorer shows, is not available through the paid API.
• Validation data depends on registry availability and may be absent.
• Agent Activity is not currently available through this API.
• One agent ID per call: there is no search, listing or bulk endpoint.
• Payments use x402 only.

Troubleshooting

The server does not appear in my client. Check the config file path and JSON/TOML syntax, then restart the client fully. Confirm node --version is 20 or newer and npx is on the PATH the client uses. On the first run npx downloads the package, which can exceed a client's startup timeout; run npx -y arcagents-mcp once in a terminal (it prints a readiness line and waits), then restart the client.

EVM_PRIVATE_KEY is missing or malformed The key must be 0x followed by exactly 64 hex characters, with no spaces or quotes inside the value.

ARCAGENTS_STATE_DIR must be an absolute path Write the full path in the client configuration (no ~, no relative path), or remove the variable to use the default folder in your home directory.

ARCAGENTS_PAYMENT_NETWORK must be "arc" or "base" Only those two values are accepted. Unset it to use Arc.

402 after payment, or "Payment verification failed" The API did not accept the payment. The reason is in apiResponse. A 402 after payment is a final answer: no automatic retry is made, and asking again starts a new request.

Payment limit reached The process has signed ARCAGENTS_MAX_PAYMENTS payments. Restart the client to reset the counter, or raise the limit.

The API answered with HTTP ..., but its response body could not be read completely The answer was cut off or timed out while being read. The signed payment is kept: ask again for the same agent ID and the same signed payment is resent, never a new one.

The request did not complete / timeouts A payment may have been signed before the timeout. Ask again for the same agent ID: the same signed payment is resent (never a new one) until the API gives a final answer, so you are not charged twice. Raise ARCAGENTS_TIMEOUT_MS if your connection is slow.

Selected payment requirement was refused (or The API challenge must contain exactly one <network> payment option) The API's challenge did not match what this server is willing to sign (wrong token, amount, domain or timeout, or no single option for your payment network). Nothing was signed. Check for a newer arcagents-mcp release.

Payment state could not be saved / could not be read The server saves each signed payment before sending it and refuses to pay if it cannot. Set ARCAGENTS_STATE_DIR to a writable directory, or repair the directory it names (remove a request's file only after checking the earlier payment on chain).

Another process already holds a signed, unresolved payment for this request A temporary conflict between two MCP processes. Nothing was sent by this call. Ask again: the next request resends the existing signed payment and creates no new authorization.

404 That agent ID is not minted on Arc Mainnet. You were not charged.

Develop from source

git clone https://github.com/Nomad07/arcagents-mcp.gitcd arcagents-mcpnpm installnpm run buildEVM_PRIVATE_KEY=0x... npm start        # waits for an MCP client on stdio

To try the local build in MCP Inspector, run npx @modelcontextprotocol/inspector -e EVM_PRIVATE_KEY=0x... node dist/index.js.

To point a client at a local build, use "command": "node" and "args": ["/absolute/path/to/arcagents-mcp/dist/index.js"].

Security

• Use a dedicated wallet with a small USDC balance. The key is only used to sign x402 payment authorizations for this API.
• The API host and price are fixed in the code; the server will not sign for another host's challenge, token, amount or EIP-712 domain.
• Never commit a real .env or private key. .env.example contains no secrets.
• Keep autoApprove (or your client's equivalent) off for this tool so you see each paid call.

License

MIT