AI agent connection

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.

MCP connection

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 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

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

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

{
  "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

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

mcp_servers:
  pouchi:
    url: "https://mcp.15-164-50-132.sslip.io/mcp"
    auth: oauth
    timeout: 300

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

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

Check the wallet status. After connecting the MCP, tell the agent:
```
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 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.

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

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.

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 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.

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.

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. 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
`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.

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 (pouchi-dev). It has docs search, examples and integration checks, and no wallet payment tools.

Next steps

Delegated payments: how the wallet contract enforces limits
Service MCP implementation: connect your shop to agent payments
Intents and mandates: the intent_url format and permission scope
Wallet MCP tools reference