> ## 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, reputation lookups, 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 (`reputation`, `assess`, `sessions`, `credentials`, and `associate-wallet`) available on every tier and metered by quota (paid tiers raise the limits and unlock the full reputation response). 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                                                                            |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `reputation`                                                     | Cached trust reputation lookup (free tier)                                         |
| `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` decodes every denial code emitted by the AgentScore API into structured `CliError` codes with `hint` lines, so agents act from the response without parsing raw 4xx/5xx HTTP shapes. Codes include `missing_identity`, `identity_verification_required`, `wallet_not_trusted`, `compliance_denied`, `wallet_signer_mismatch`, `wallet_auth_requires_wallet_signing`, `token_expired`, `invalid_credential`, `payment_required`, `api_error`.

## Use cases

**Agent-to-agent trust**; verify the reputation of another agent's wallet before initiating a transaction.

**Gateway pre-screening**; an agent acting as a gateway screens incoming requests by wallet reputation.

**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 (`reputation`, `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)