> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentScore Pay (MCP Server)

> Give AI agents and assistants access to wallet, payment, and identity tools via the Model Context Protocol.

`agentscore-pay --mcp` exposes the AgentScore CLI as an MCP server over stdio. AI agents and coding assistants can register the binary once and call every wallet, payment, and identity command as a tool; wallet management, x402/MPP payments, on-the-fly assessments, verification sessions, operator credentials, and wallet attribution all in one server.

## Install

```bash theme={"dark"}
npm install -g @agent-score/pay
# or: npx @agent-score/pay <command>
```

Set `AGENTSCORE_API_KEY` for identity tools (`assess`, `sessions`, `credentials`, and `associate-wallet`) available on every tier and metered by quota (paid tiers raise the limits). Wallet and payment tools are local and need no key.

## Register with your agent

```bash theme={"dark"}
agentscore-pay mcp add                     # auto-detect (Claude Code, Cursor, Amp, ...)
agentscore-pay mcp add --agent claude-code # target a specific agent
```

This writes the MCP config for your agent so the tools appear automatically.

### Manual config: Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json theme={"dark"}
{
  "mcpServers": {
    "agentscore-pay": {
      "command": "agentscore-pay",
      "args": ["--mcp"],
      "env": {
        "AGENTSCORE_API_KEY": "as_live_your_key_here"
      }
    }
  }
}
```

### Manual config: Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) with the same shape.

## Available tools

Every command from `agentscore-pay --help` is exposed as a tool. The most agent-relevant ones:

### Wallet + payment

| Tool | Purpose |
| - | - |
| `init` | First-run setup: creates encrypted keystores for Tempo, Solana, Base |
| `wallet_create` / `wallet_import` / `wallet_address` / `wallet_list` | Keystore CRUD |
| `balance` | USDC balance across chains |
| `fund` / `faucet` | Receive QR + balance poll on mainnet; programmatic mint or faucet URL on testnet |
| `pay` | Send an HTTP request and auto-handle the 402 round-trip |
| `check` | Probe a 402 response and show accepted rails (without paying) |
| `discover` | List paid services from the x402 Bazaar + MPP services directory |
| `fund-estimate` | "How many calls does my balance cover for this URL?" |

### Identity (any tier: set `AGENTSCORE_API_KEY`)

| Tool | Purpose |
| - | - |
| `assess` | On-the-fly assessment with policy (KYC, age, sanctions, jurisdiction) |
| `sessions_create` / `sessions_get` | Identity verification flow: returns `verify_url` + polls for `operator_token` |
| `credentials_create` / `credentials_list` / `credentials_revoke` | Operator credential (`opc_...`) lifecycle |
| `associate-wallet` | Report a signer wallet seen paying under a credential (cross-merchant attribution) |

Run `agentscore-pay --llms` for the full machine-readable manifest (or `--llms --format json` for JSON Schema).

## Denial-code handling

`assess`, `sessions`, `credentials` and `associate-wallet` turn the API's typed errors into structured `CliError` codes with `hint` lines, so agents act from the response without parsing raw 4xx/5xx shapes: `config_error` (an API-key problem, or an operator token that expired or is not recognized; `extra` carries `verify_url` / `session_id` / `poll_secret` when the API minted a recovery session), `insufficient_balance` (the endpoint is not enabled for the account), `quota_exceeded` (account cap reached; retrying will not help), and `network_error` (rate limit, timeout or transient failure; retry with backoff). A compliance `deny` is not an error: it comes back as `decision: "deny"` with `decision_reasons`.

A merchant's own denial codes (`missing_identity`, `identity_verification_required`, `wallet_not_trusted`, ...) reach the agent through `pay`, in the merchant's 403 body and its `agent_instructions`.

## Use cases

**Agent-to-agent trust**; run `assess` on another agent's wallet before initiating a transaction.

**Gateway pre-screening**; an agent acting as a gateway screens incoming requests with `assess`.

**Autonomous payment**; discover a 402-gated endpoint, probe it with `agentscore-pay check`, dry-run with `agentscore-pay pay --dry-run`, then settle the payment via `agentscore-pay pay`. All without leaving the MCP loop.

**Identity bootstrap**; an agent encounters an AgentScore-gated merchant for the first time, receives a `missing_identity` denial, calls `sessions_create` → polls `sessions_get` → uses the returned `operator_token` to retry the original request.

## Environment variables

| Variable | Description |
| - | - |
| `AGENTSCORE_API_KEY` | API key for identity tools (`assess`, `sessions`, `credentials`, `associate-wallet`). Get one at [agentscore.com/sign-up](https://www.agentscore.com/sign-up). |
| `AGENTSCORE_PAY_PASSPHRASE` | Skip the interactive passphrase prompt for keystore operations. |
| `AGENTSCORE_PAY_HOME` | Override the state dir (default `~/.agentscore`). |

## Running locally

```bash theme={"dark"}
AGENTSCORE_API_KEY=as_live_your_key_here agentscore-pay --mcp
```

The server communicates over stdio using the MCP protocol. Pipe `{"jsonrpc":"2.0","id":1,"method":"tools/list"}` to it to enumerate tools.

## Links

* [npm](https://www.npmjs.com/package/@agent-score/pay)
* [GitHub](https://github.com/agentscore/pay)
* [AgentScore Pay docs](/integrations/pay-cli)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.