@bound/mcp

An MCP server that gives any MCP-capable agent — Claude Desktop, Claude Code, Cursor, your own client — the tools of Bound Protocol: verify an agent's certificate before transacting with it, pay for a service autonomously over x402, read the meter that records what a certificate has spent, price and buy coverage, and prove a false attestation on-chain so the auditor is slashed.

It is the same tool table the Bound dashboard drives through the AI SDK, defined once and adapted twice. Everything it does goes through @bound/sdk, which is a regular dependency — there is nothing else to install.

Usage

npx @bound/mcp

The server speaks MCP over stdio, so it is normally launched by a client rather than by hand. stdout is the JSON-RPC channel; every diagnostic goes to stderr.

Claude Desktop

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

{
  "mcpServers": {
    "bound": {
      "command": "npx",
      "args": ["-y", "@bound/mcp"],
      "env": {
        "AGENT_SECRET": "S...",
        "OPERATOR_SECRET": "S...",
        "AUDITOR_SECRET": "S...",
        "CHALLENGER_SECRET": "S...",
        "COUNTERPARTY_SECRET": "S..."
      }
    }
  }
}

Cursor

.cursor/mcp.json in the project, or ~/.cursor/mcp.json globally — same shape:

{
  "mcpServers": {
    "bound": {
      "command": "npx",
      "args": ["-y", "@bound/mcp"],
      "env": {
        "AGENT_SECRET": "S...",
        "OPERATOR_SECRET": "S...",
        "AUDITOR_SECRET": "S...",
        "CHALLENGER_SECRET": "S...",
        "COUNTERPARTY_SECRET": "S..."
      }
    }
  }
}

Claude Code takes the same block in .mcp.json, or claude mcp add bound -- npx -y @bound/mcp.

Environment

| Variable | Needed for | | --------------------- | ----------------------------------------------------------------------- | | AGENT_SECRET | execute_payment, fetch_paid_service, fund_float, enroll_agent | | OPERATOR_SECRET | enroll_agent, halt_certificate, resume_certificate, pay_premium | | AUDITOR_SECRET | claim_premium | | CHALLENGER_SECRET | challenge_certificate | | COUNTERPARTY_SECRET | reserved for the demo counterparty role | | STELLAR_NETWORK | optional; only testnet exists today, and it is the default |

Every key is read lazily, so a session that only reads never touches one and starts fine with none of them set. Contract addresses and network endpoints are committed inside @bound/sdk — there is nothing to configure.

These are Stellar secret keys (S...). They sign real transactions on testnet, and the write tools spend from them without asking. Bound is testnet-only today (see Status), so there is no mainnet balance to lose — but treat the config block as a credential file regardless. If you are running inside a checkout of the Bound repo, the server will also pick the same five variables up from a .env.testnet found by walking upward from its working directory.

Tools

Read-only tools simulate against the chain, sign nothing and spend nothing; they are marked readOnlyHint so a client can run them without prompting. Everything else signs with one of the keys above.

| Tool | Read | What it does | | -------------------------- | :--: | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | verify_agent_certificate | ✓ | The headline check: is this agent's certificate valid, and what bound, reserve and auditor stake back it | | get_balance | ✓ | USDC balance of an address; defaults to the agent | | get_routing_status | ✓ | Whether an address's payments are metered, which certificate against, and the float it holds | | get_cert_meter | ✓ | A certificate's routed spend, float, float cap and halt state, next to the bound they measure against | | quote_premium | ✓ | Price coverage — for a published certificate, or a hypothetical bound × duration | | get_coverage | ✓ | Premium paid, protocol fee, and how much of the auditor's yield has accrued and is claimable | | execute_payment | | Send USDC. Routed through the meter when the agent is enrolled, raw USDC when it is not | | fetch_paid_service | | x402: fetch a URL, and if it answers 402, pay the demanded price and retry — no human approves it | | enroll_agent | | Bind the agent to a certificate and set its float cap. Operator and agent both authorize | | fund_float | | Move USDC into the router's custody to pay from | | halt_certificate | | Operator's kill switch: stop every transfer, withdrawal and burn on a certificate | | resume_certificate | | Lift a halt | | pay_premium | | Operator buys coverage. Once per certificate, and only after an auditor has attested | | claim_premium | | Auditor withdraws accrued-and-unclaimed yield | | challenge_certificate | | Prove an attestation false. For InsufficientReserve the contract verifies the fraud itself, slashes the auditor's stake and compensates the victim |

Two things are worth knowing before an agent acts on these:

• There is no spending cap. The agent pays what it is asked. What protects the counterparty is the certificate — a pre-funded reserve and an auditor's slashable stake bounding the worst case — not a limit on the call.
• Routed spend is gross flow, not loss. A certificate that has routed more than its bound has broken a covenant about its own conduct; it has not thereby cost anyone that much money. get_cert_meter returns the bound alongside the counter so the comparison is explicit rather than implied.

Status

Stellar testnet only. The contract addresses, network endpoints and demo actor public keys are committed inside @bound/sdk; there is no mainnet deployment yet.

Embedding it

The package root exports the pieces, for callers who want them somewhere other than a stdio process:

import { createBoundMcpServer } from "@bound/mcp";

const server = createBoundMcpServer();
await server.connect(myOwnTransport);

@bound/mcp/tools is a second, lighter entry point carrying only the tool table — { description, parameters (a Zod raw shape), execute } per tool — with no MCP server attached. Import that to drive the same tools from a framework that is not MCP; the Bound dashboard uses it to build AI SDK tools.

Both entry points are server-side only: the write tools sign with secret keys from the environment, so they belong behind your own backend, never in a browser bundle.

Learn more

Source, contracts, and full documentation: https://github.com/iamnotdou/bound