Agent setup

An agent spends a borrower’s credit through the hosted MCP server. You connect the host, complete OAuth, and keep the terminal ids that register_borrower returns. Signing and policy stay outside this page: keys are in Key management, and the person-in-the-loop steps are in Borrower onboarding.

​

Connect

1. Read setup-staging and mcp-connect-staging.
2. Point the host at https://staging.mcp.sohopay.xyz/mcp.
3. Finish OAuth in the browser. The server id for staging is sohopay-staging.

One MCP host is one terminal_id. If two clients share a remote MCP connection, pass a distinct terminal_id on register_borrower.

​

What to store

register_borrower returns:

• borrower_id — the canonical borrower UUID. Do not substitute a principal id from the OAuth token.
• operational_agent_id — the UUID for this terminal. Pass it on spend, balance, and repayment tools when the borrower has more than one terminal.
• terminal_id — the host’s terminal. Persist it with the workload key.

Prefer get_context when you need identity, credit, authorization, and the next step in one call. whoami returns JWT claims only and does not call the backend.

​

Workload key

Generate an Ed25519 key on the host with @sohopay/agent-signer and register it with register_agent_workload_key plus a proof-of-possession signature. The private key never goes to SohoPay. Until that key is registered, prepare_x402_payment returns X402_AGENT_KEY_NOT_REGISTERED.

​

Next steps