# Connect your agent to Payments AI

> Server status, one way to connect your MCP client, one fallback, and the check that proves the connection works.

No account needed to read this page. Follow it top to bottom: status first, then one way to connect, then one check.

## Server status

<McpServerStatus />

The status reads the server card, the public document the MCP server answers at `/.well-known/mcp/server-card.json` on its own host. **Degraded** means the problem is on our side: wait before changing your setup. **Unreachable** means this browser got no answer at all, which can be your network as well as our server.

## Connect

Pick your client. You get one way to connect and one fallback if it does not work.

<McpConnectPath />

## Verify the connection

Do not trust "added" or "connected" in your client: it only means the server is registered. Ask your agent:

```text
Call whoami on the Payments AI MCP server and show me exactly what it returns.
```

`whoami` takes no arguments and needs no scope, so every valid credential can call it. It proves the connection without depending on what you granted.

- **Connected:** `whoami` returns your `accountName`, your `userId`, your `scopes`, the `host` and the `endpoint`. `accountName` is the business name of the account you are connected to, never an email: confirm it with `host` (live or sandbox) and check it is your own business account. `null` means no label is known. `host` is `live` or `sandbox` and names the MCP URL you connected to, not a merchant. `endpoint` is that MCP URL: check it is the one you meant. `scopes: null` means every scope except `transaction:read`. It also returns `merchantIds`, `credentialExpiresAt` and `credentialExpiresInSeconds`; in the last 14 days of an OAuth connection it adds a `credentialExpiryWarning` with the link to re-approve.
- **Not connected:** the tool is missing, or the call fails with `401`. Reload MCP in your client, then repeat the check. The `401` codes and their fixes are listed under [When the MCP endpoint answers 401](/mcp#when-the-mcp-endpoint-answers-401); `token_expired` means the credential ran out, and the fix depends on how you connected: browser or OAuth client, re-approve it in the client; device grant (no terminal), run the device grant again and replace the `Authorization` header ([Connect without a terminal](#connect-without-a-terminal)); MCP key, generate a new key under **Developer Tools → MCP Tokens**. If your client cannot finish the browser sign-in at all, generate a token in the dashboard under **Developer Tools → MCP Tokens** and follow [Manual: User MCP Key](/mcp#manual-user-mcp-key), or see [Connect without a terminal](#connect-without-a-terminal).
- **Connected, but a tool is denied:** the connection works and a scope is missing. `get_my_merchant`, for example, needs `merchant:read`. Re-approve with that scope instead of reconnecting.

## Connect without a terminal

Use this only when nothing in your setup can open a browser or answer a terminal prompt: a headless agent, CI, a container, an SSH session without a TTY. The steps above stay the way to connect everywhere else.

The agent runs an OAuth device authorization (RFC 8628) over plain HTTP and shows you a short code. You approve it on any device with a browser, such as your phone. Your MCP client never opens a browser itself: the agent hands it the resulting token as an `Authorization: Bearer` header.

1. **Register a device-only client.** `POST /v1/oauth/register` with `grant_types: ["urn:ietf:params:oauth:grant-type:device_code"]` and no `redirect_uris`. A device-only client cannot use `/authorize`.
2. **Start the authorization.** `POST /v1/oauth/device_authorization` with the `client_id` and the MCP URL as `resource`. The answer carries `user_code`, `verification_uri`, `expires_in` (30 minutes) and `interval` (5 seconds).
3. **You approve.** The agent shows you `user_code` and `verification_uri` exactly as returned. Open the address and type the code. If you are not signed in, sign in or sign up first: the page keeps the code and pre-fills it afterwards, but you still press **Continue**, and only then do the scopes appear. Tick the scopes you want to grant. Write scopes start unticked. The page marks the client as an unverified application; approve only if you started this connection. **Deny** ends it.
4. **The agent polls.** `POST /v1/oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code`, every `interval` seconds, until it gets an `access_token`.

<McpDeviceGrantExample />

What the poll can answer, as an RFC 6749 body `{ "error", "error_description" }` with status `400`:

| `error`                 | What the agent does                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `authorization_pending` | You have not approved yet. Keep polling at the same interval.                           |
| `slow_down`             | Polling too fast. Add 5 seconds to the interval for this and every later poll.          |
| `access_denied`         | You pressed **Deny**. Stop and tell you so.                                             |
| `expired_token`         | The 30 minutes passed. Start again at step 2.                                           |
| `invalid_grant`         | The code is unknown, already used, or belongs to another client. Start again at step 2. |

`device_authorization` answers `429 temporarily_unavailable` with `Retry-After: 60` when too many authorizations are waiting: the agent backs off and tries again later instead of looping. The token it receives is the same `pai_mcp_*` credential OAuth issues, valid for 90 days. The agent then calls `whoami` as above. When the credential is about to expire (`whoami` warns) or has expired (`token_expired`), run these steps again and replace the `Authorization` header: the client never ran OAuth, so there is nothing to re-approve in it.

The page allows 5 code attempts per account every 15 minutes, a correct one included. If a code is rejected, check it against the one the agent shows, or have the agent start again.

Your client decides what it can do with that token. Find it below.

<McpConnectNoTty />

## Open this page on your phone

Scan the code to continue on another device, or type the address.

<McpConnectPageQr />

Still stuck? Write to [merchants@payments.ai](mailto:merchants@payments.ai) (see [Getting help](/getting-help)).
