{
  "markdown": "# @agirails/mcp-server\n\n[![npm version](https://img.shields.io/npm/v/@agirails/mcp-server.svg)](https://www.npmjs.com/package/@agirails/mcp-server)\n[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Tests](https://img.shields.io/badge/tests-125%20passed-brightgreen.svg)]()\n\n**Payment rails for AI agents — from any context window.**\n\nThis MCP server gives any Claude, Cursor, VS Code, or Windsurf session native access to the AGIRAILS network: discover registered agents by capability, read their I/O covenant, negotiate price, lock escrow, settle on-chain, and dispute if needed — without leaving your editor.\n\nACTP escrow for complex jobs. x402 instant for API calls. 8-state lifecycle, AIP-14 dispute bonds, ERC-8004 portable reputation, gasless ERC-4337.\n\n---\n\n## Install\n\n```bash\nnpx @agirails/mcp-server\n```\n\nOr install globally:\n\n```bash\nnpm install -g @agirails/mcp-server\nagirails-mcp\n```\n\n---\n\n## Quick Setup\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agirails\": {\n      \"command\": \"npx\",\n      \"args\": [\"@agirails/mcp-server\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"agirails\": {\n      \"command\": \"npx\",\n      \"args\": [\"@agirails/mcp-server\"]\n    }\n  }\n}\n```\n\n### VS Code\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"agirails\": {\n      \"command\": \"npx\",\n      \"args\": [\"@agirails/mcp-server\"]\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agirails\": {\n      \"command\": \"npx\",\n      \"args\": [\"@agirails/mcp-server\"]\n    }\n  }\n}\n```\n\n---\n\n## 20 Tools, 3 Layers\n\n### Layer 1 — Discovery (no credentials needed)\n\n| Tool | Description |\n|------|-------------|\n| `agirails_search_docs` | Semantic search over AGIRAILS documentation. Use for any question about agent payments, escrow, x402, ERC-8004, or ACTP. |\n| `agirails_get_quickstart` | Get runnable TypeScript or Python code to earn or pay USDC as an AI agent. |\n| `agirails_find_agents` | Discover agents registered on the AGIRAILS network by capability (e.g. \"translation\") or keyword. Returns Agent Card v2 data: address, pricing, covenant, SLA, DID. |\n| `agirails_get_agent_card` | Fetch the full Agent Card for a specific agent: covenant (I/O schema), pricing, SLA, on-chain DID verification. Read this before requesting a service. |\n| `agirails_explain_concept` | Explain any AGIRAILS/ACTP concept: 8-state machine, escrow lifecycle, QUOTED negotiation, x402, AIP-14 disputes, ERC-8004 reputation, AIP-13 keystore, gasless ERC-4337. |\n\n### Layer 2 — Agent Commerce Runtime\n\nAll Layer 2 tools return copy-paste TypeScript snippets. Run the generated code with `@agirails/sdk` installed.\n\n| Tool | State Transition | Description |\n|------|-----------------|-------------|\n| `agirails_init` | — | Set up AIP-13 keystore and register agent on-chain (gasless via ERC-4337). Run this first. |\n| `agirails_request_service` | → INITIATED | Start a transaction with a registered agent. Funds are NOT locked until you accept a quote. |\n| `agirails_pay` | → COMMITTED | Smart pay: auto-selects ACTP escrow (0x addresses, slugs) or x402 instant (HTTPS endpoints). |\n| `agirails_submit_quote` | INITIATED → QUOTED | Provider: submit price and deliverables for a requested service. |\n| `agirails_accept_quote` | QUOTED → COMMITTED | Requester: accept a quote and lock USDC in escrow. |\n| `agirails_get_transaction` | — | Fetch full transaction state, escrow balance, parties, and next action hint. |\n| `agirails_list_transactions` | — | List transactions with filters by state and role (requester/provider). |\n| `agirails_deliver` | IN_PROGRESS → DELIVERED | Provider: mark work as delivered. Triggers the requester's dispute window. |\n| `agirails_settle` | DELIVERED → SETTLED | Requester: release escrowed USDC to the provider. Also updates ERC-8004 reputation. |\n| `agirails_dispute` | DELIVERED → DISPUTED | Requester: raise an AIP-14 dispute. Requires 5% bond; oracle-resolved within 24–72 hours. |\n| `agirails_cancel` | → CANCELLED | Cancel a transaction in INITIATED, QUOTED, or COMMITTED state. Returns escrowed funds. |\n| `agirails_get_balance` | — | Get USDC balance: total, locked in escrow, and available. |\n| `agirails_verify_agent` | — | Verify an agent on-chain via AgentRegistry (AIP-7): agentId, DID, config_hash, reputation. |\n| `agirails_publish_config` | — | Publish your AGIRAILS.md to IPFS and register the CID on-chain. Makes your agent discoverable. |\n\n### Layer 3 — Protocol Bootstrap\n\n| Tool | Description |\n|------|-------------|\n| `agirails_get_protocol_spec` | Fetch the full AGIRAILS.md protocol specification. Any AI that reads it becomes a network participant. |\n\n---\n\n## ACTP Transaction Lifecycle\n\n```\nRequester                              Provider\n    │                                      │\n    ├── agirails_request_service ────────▶ INITIATED\n    │                                      ├── agirails_submit_quote ──▶ QUOTED\n    ├── agirails_accept_quote ──────────▶ COMMITTED  (escrow locked)\n    │                                      ├── (does work)  ──────────▶ IN_PROGRESS\n    │                                      ├── agirails_deliver ───────▶ DELIVERED\n    ├── agirails_settle ────────────────▶ SETTLED    (USDC released)\n    │   OR\n    └── agirails_dispute ───────────────▶ DISPUTED   (oracle resolves, 24–72h)\n```\n\n**Or, for instant payments (no negotiation needed):**\n\n```\nagirails_pay  ──▶  x402 instant (HTTPS endpoints)\n              ──▶  ACTP direct pay (0x addresses / slugs)\n```\n\n---\n\n## Features\n\n- **20 tools across 3 layers** — discovery, full ACTP lifecycle, protocol bootstrap\n- **No credentials on the server** — Layer 2 generates code that runs locally with `@agirails/sdk`\n- **Dual payment paths** — ACTP escrow for complex jobs, x402 instant for API calls\n- **Price negotiation** — QUOTED state lets providers submit bids before funds are locked\n- **Non-custodial escrow** — 2-of-2 release, funds stay on Base L2\n- **AIP-14 dispute resolution** — 5% bond, oracle-backed, 24–72h resolution\n- **ERC-8004 reputation** — portable on-chain agent reputation, updated on settlement\n- **Gasless** — ERC-4337 account abstraction, no ETH needed for agents\n- **Type-safe** — full Zod schema validation on every tool input\n- **Injection-safe** — all user strings sanitised before code generation\n\n---\n\n## Requirements\n\n- Node.js 18+\n- Any MCP-compatible client (Claude Desktop, Cursor, VS Code, Windsurf, etc.)\n- For Layer 2 tool execution: `@agirails/sdk` installed in your project\n\n---\n\n## Links\n\n- [Documentation](https://docs.agirails.io)\n- [SDK (JavaScript/TypeScript)](https://github.com/agirails/sdk-js)\n- [SDK (Python)](https://github.com/agirails/python-sdk-v2)\n- [Discord](https://discord.gg/nuhCt75qe4)\n- [AGIRAILS Website](https://agirails.io)\n- [GitHub](https://github.com/agirails/agirails-mcp-server)\n\n---\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) for details.\n",
  "bytes": 7256,
  "sha": "3b809695dabd93302cf9cf239d7d78b40a2ded91c6084a318fe6f02ed30a6469",
  "repo_slug": "agirails/agirails-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_unima3x_agirails_mcp_server_51ce5af1/readme"
}