# AI agent connection

Connect the wallet MCP so agents in MCP clients such as Claude Code and Hermes pay only within the limits the user approved.

The agent only requests payments. The user reviews the recipient, amount, number of runs and period on the Pouchi approval screen and approves once with a PIN or a passkey. After that, the agent's payments run only within the approved limits, and the wallet contract checks those limits.

**Public testnet MCP**

Add one URL to get all 9 wallet tools and the `shop_*` shopping tools. No local server or install script is required. This public endpoint is a staging service on Maroo Testnet (450815).

## MCP connection

```text wrap
https://mcp.15-164-50-132.sslip.io/mcp
```

Add this URL as a **Streamable HTTP** server and authorize the connection in your browser. Your client must support OAuth 2.1 with dynamic client registration (DCR) and authorization code + PKCE. Authorizing the MCP connection and signing in to your Pouchi wallet are separate steps.

  **Claude Code**

```sh
claude mcp add --transport http pouchi https://mcp.15-164-50-132.sslip.io/mcp
claude mcp list
```

Start Claude Code, open `/mcp` and select `pouchi` to authenticate. Authorize in your browser, then check the tool list for `wallet_status`, `pay_intent` and `shop_*`. If `claude mcp list` says authentication is needed, authorization is still pending.

[Claude Code MCP setup](https://code.claude.com/docs/en/mcp)

  **Claude Desktop / claude.ai**

Open **Connectors** and choose **Add custom connector**. Enter `Pouchi` as the name and the URL above as the remote MCP server URL. If asked for a connector type, choose Web.

Select OAuth authentication. If an OAuth client option appears, choose **Register automatically**. Authorize the connection, then enable Pouchi in your conversation. A team administrator may need to add the connector first.

[Claude remote connector setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

  **Cursor**

Add this to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` to use it across projects.

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "pouchi": {
      "url": "https://mcp.15-164-50-132.sslip.io/mcp"
    }
  }
}
```

Restart Cursor and authorize `pouchi` through OAuth in MCP settings. Check that Agent lists both the wallet tools and `shop_*` tools.

[Cursor MCP setup](https://docs.cursor.com/context/model-context-protocol)

  **Hermes**

Add a remote URL entry under `mcp_servers` in `~/.hermes/config.yaml`.

```yaml title="~/.hermes/config.yaml"
mcp_servers:
  pouchi:
    url: "https://mcp.15-164-50-132.sslip.io/mcp"
    auth: oauth
    timeout: 300
```

```sh
hermes mcp login pouchi
hermes mcp list
hermes mcp test pouchi
```

Authorize in the browser opened by the login command, then start a new Hermes conversation. For a named profile, edit that profile's configuration and run the commands with `hermes -p PROFILE_NAME`.

[Hermes remote MCP setup](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

  **Other MCP clients**

Set the server name to `Pouchi`, the URL to the public endpoint above and the transport to **Streamable HTTP**. Enable OAuth with DCR and PKCE, then authorize in your browser. A separate shopping server is not needed.

The MCP connection is ready when the tool list shows 9 wallet tools and `shop_*`. MCP elicitation is not required. Wallet sign-in and payment approvals use text links in tool responses.

## Wallet connection and first payment

1. **Check the wallet status.** After connecting the MCP, tell the agent:

```text wrap
Call wallet_status on pouchi.
If connected:false and next_tool is wallet_login, call wallet_login.
Show me the returned user_message and approval_url. I will open the link to sign in.
If the status is waiting_for_user, call payment_status with the returned job_id.
After connection completes, use wallet_status to show my wallet address and balance.
```

`connected:false` from `wallet_status` means wallet sign-in is needed. Open the `approval_url` returned as text by `wallet_login` and finish signing in on the Pouchi screen.

Before requesting payment, check the asset and balance returned by `wallet_status`. The SDK transfer example uses native test OKRW; a shop demo may use a separate payment token. If funds or an invite are needed, contact [business@pouchi.app](mailto:business@pouchi.app) with the wallet address, network and demo name. Follow a returned `topup_url` only for the asset shown in the response, then check the balance again.

2. **Choose a product and request payment.** Use `shop_*` tools on the same MCP to browse products and create a payment request.

```text wrap
Show me products using pouchi's shop_* tools. After I choose a product,
use the matching shopping tool to create an intent_url and pass it to pay_intent.
Show me the returned user_message and approval_url.
I will open the link to review the recipient, amount, number of runs and period, then approve.
If the status is waiting_for_user, call payment_status with the returned job_id.
```

`pay_intent` also returns the approval link and instructions as text. User authentication (passkey, PIN or another method) happens on the Pouchi approval screen. Typing "approve" in chat does not approve a payment.

3. **Check the result and remaining limits.** `my_payments` shows payments and receipts, and `my_budget` shows the remaining limit and runs. The next payment within the same limit runs without asking again.

## Expected result

The approval screen shows the requesting agent, the shop, the amount and the approval scope. Check these details before approving. The [Pouchi tour](/en/docs/tour/) links to Ticketly and SaveOn.

## Tools

| Tool | When |
|---|---|
| `wallet_login` | Sign up or sign in and connect. The user finishes on the approval screen |
| `wallet_status` | Wallet address, balance and approved permissions |
| `pay_intent` | Run an `intent_url` from a service. The wallet MCP tool that initiates a payment |
| `change_mandate` | Change a permission, such as renewing a subscription or raising a limit (needs user approval) |
| `my_budget` | Approved permissions, remaining limit and runs, period |
| `my_payments` | Payment history with receipts |
| `revoke_mandate` | Stop gateway payments immediately. Complete any returned on-chain revocation approval link |
| `wallet_disconnect` | Disconnect the wallet. Agents connected to it can no longer pay |
| `payment_status` | Wait for a pending job, up to 50 seconds per call |

Arguments and result states are in the [wallet MCP reference](/en/docs/reference/wallet-mcp/).

## Agent restrictions

- Approve a payment by writing "approved" in chat. Approval happens only on the approval screen.
- Run a payment request built by an unregistered site. The gateway fetches intents only from registered service origins.
- Exceed the approved limits. The wallet contract checks amount, runs and period on chain.

**Use a payment-only agent**

Turning on shell, file or web tools in a paying agent widens the impact of prompt injection. Limits contain the damage, but enable only the tools you need.

## Common errors

| Response | Meaning | Fix |
| --- | --- | --- |
| `waiting_for_user` with `approval_url` | Not an error. Waiting for the user | Open the link and approve. The agent calls `payment_status(job_id)` again |
| `needs_topup` (`INSUFFICIENT_BALANCE`) | The wallet balance is below the payment | Check the required asset and network in the response. Follow its top-up instructions or request test funds from [business@pouchi.app](mailto:business@pouchi.app). Check the balance, then retry |
| `OVER_LIMIT` | Over the per-run limit, the remaining limit or the remaining runs | Send the service's limit-change intent with `change_mandate`; the user approves again |
| `PERIOD_LIMIT` | The runs or amount for this period are used up | Request again after `next_period_at` in the response |
| `MANDATE_EXPIRED` | The approved permission's period ended | Call `pay_intent` with a new `intent_url` and approve again |
| `WALLET_DISCONNECTED` | The user disconnected the wallet | Connect again with `wallet_login` |
| `TESTER_REQUIRED` | The account is not invited to an invite-only demo | Request an invite from [business@pouchi.app](mailto:business@pouchi.app) |
| `USE_SERVICE_MCP` | A shop payment was requested from the wallet MCP directly | Get an `intent_url` from the service MCP's `buy` and pass it to `pay_intent` |
| The approval link says the request expired | The connection request timed out | Call `wallet_login` again for a new link |

## Advanced: local stdio

Use local stdio only when developing the repository. This is optional for public URL users. Prepare the local API, gateway and service servers separately; the configuration below starts only the wallet MCP process. Approvals still happen on the Pouchi screen.

```yaml title="~/.hermes/config.yaml"
mcp_servers:
  agentpay:
    command: "node"
    args: ["/path/to/agent-pay/apps/local-wallet/server.mjs"]
    env:
      AGENT_PAY_WALLET_HOME: "/Users/<you>/.agent-pay/local-wallet"
      REGISTRY_PATH: "/path/to/agent-pay/registry/shops.tkrw.json"
```

## Developer MCP comparison

To let an AI coding tool write your integration code, use the [developer MCP](/en/docs/ai/) (`pouchi-dev`). It has docs search, examples and integration checks, and no wallet payment tools.

## Next steps

- [Delegated payments](/en/docs/delegation/): how the wallet contract enforces limits
- [Service MCP implementation](/en/docs/services/): connect your shop to agent payments
- [Intents and mandates](/en/docs/intents/): the `intent_url` format and permission scope
- [Wallet MCP tools reference](/en/docs/reference/wallet-mcp/)