> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tallyforagents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your agent (hosted MCP)

> The recommended way to connect an agent to Tally — over the network, no API key in config, no local install. A device-code flow for chat-based agents (Hermes, OpenClaw) and a browser popup for hosts that drive their own browser.

There are three ways to give an agent Tally tools. Pick by what your agent can do:

| Your agent…                                                                 | Use                         | What it feels like                                                         |
| --------------------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------- |
| **Chats + makes web requests** (Hermes, OpenClaw, most LLM agents)          | **Device flow** (this page) | Agent shows you a link → you approve in the browser → done. No localhost.  |
| **Controls its own browser** (Claude Desktop, ChatGPT, Cursor via a bridge) | **Native MCP OAuth**        | A browser popup opens automatically; you approve.                          |
| **Runs a local subprocess**                                                 | **Stdio + API key**         | Paste a key into config. See [Connect via stdio](/guides/connect-via-mcp). |

The device-flow and browser-popup paths connect to the hosted endpoint, which
exposes seven tools — `pay_x402_service`, `pay_direct`, `get_wallet_info`,
`get_wallet_balance` (live on-chain USDC balance), `check_x402_price` (preview a
service's cost without paying), `list_x402_services` (discover paid services via
the x402 Bazaar), and `list_recent_payments` — all bounded by the per-tx and
daily caps you set in Tally. (The stdio package exposes the four core tools.)

If you're not sure, use the **device flow** — it works for any agent that can make
HTTP requests, including chat-only ones.

## Fastest path: paste this into your agent

This drives the **device flow**, which works regardless of host (it doesn't need
your agent to open a browser or run a local listener). It then points the agent
at `/skill.md` so it knows how to use the wallet right after connecting — not just
that it has one.

```text theme={null}
Connect yourself to Tally using its OAuth Device Flow so you can hold and spend
USDC on my behalf. Tally base URL: https://app.tallyforagents.com

1. Register a client (once):
   POST /oauth/register
   JSON: {"client_name":"My Agent","redirect_uris":["http://127.0.0.1/cb"],"scope":"wallet:read wallet:transfer x402:pay"}
   Save the returned client_id.

2. Start the device flow:
   POST /oauth/device_authorization
   form body: client_id=<client_id>&scope=wallet:read wallet:transfer x402:pay
   It returns verification_uri_complete, device_code, and interval.

3. Show me ONE line, then wait — do not show the raw code:
   "Click here to connect Tally and approve: <verification_uri_complete>"

4. After I tell you I've approved, poll for the token:
   POST /oauth/token
   form body: grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=<device_code>&client_id=<client_id>
   - {"error":"authorization_pending"} → wait <interval> seconds, then retry.
   - {"error":"slow_down"} → wait a few extra seconds, then retry.
   - When you receive an access_token, stop polling and save it.

5. Fetch https://app.tallyforagents.com/skill.md and follow it as your guide for
   every Tally action — checking balance, spending limits, payments, and history.
   Use the access_token as your Bearer credential (not an API key).

6. Confirm: GET /v1/me with header Authorization: Bearer <access_token>, and tell
   me the workspace, mode, and wallet limits it returns.

From now on, for anything money- or wallet-related, use the Tally REST endpoints
from that skill — don't invent endpoints.
```

## What you'll experience

The agent shows you a single link like
`https://app.tallyforagents.com/device?code=WDJB-MJHT`. You:

1. Click it (it's your own Tally domain).
2. Sign in if needed, pick the **workspace**, **mode** (test/live), and **agent**.
3. Click **Authorize** → you see "Connected — return to your agent."

The agent's polling finishes on its own a few seconds later. **You never type the
code** — it's embedded in the link; the visible code is just a fallback for
typing it manually at `https://app.tallyforagents.com/device`.

<Note>
  This is the same pattern as `gh auth login`, the AWS CLI, and signing into apps
  on a smart TV. For a chat-based agent it's the simplest flow possible — the
  "popup opens by itself" experience requires an agent that controls its own
  browser (see below).
</Note>

## Native browser popup (browser-driving hosts)

If your host drives its own browser and can catch an OAuth redirect (Claude
Desktop, ChatGPT, or Cursor via the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)
bridge), point it at the hosted endpoint and you get the automatic popup instead
of a code:

```
https://app.tallyforagents.com/mcp
```

It's a standard OAuth 2.1 protected resource: an unauthenticated request gets a
`401` + `WWW-Authenticate` pointing at
`/.well-known/oauth-protected-resource/mcp`, which the host follows to open the
consent screen. On Hermes builds that support remote-MCP OAuth:

```bash theme={null}
hermes mcp add tally --url https://app.tallyforagents.com/mcp
hermes mcp login tally     # opens the browser → pick workspace → authorize
hermes mcp test tally
hermes gateway restart
```

<Note>
  If your host only **prints a link** instead of opening the browser and catching
  the response, it can't complete this flow — use the **device flow** above
  instead. That's the common case for chat-based agents.
</Note>

The endpoint also accepts a static API key (`tly_test_…` / `tly_live_…`) as a
bearer token, the same credential the stdio server takes.

## The OAuth endpoints

Everything is advertised at the discovery document, so a host can wire itself up:

```
GET https://app.tallyforagents.com/.well-known/oauth-authorization-server
```

| Endpoint                      | Purpose                                                         |
| ----------------------------- | --------------------------------------------------------------- |
| `/oauth/register`             | Dynamic client registration (RFC 7591) → `client_id`.           |
| `/oauth/device_authorization` | Start the device flow (RFC 8628) → `device_code` + `user_code`. |
| `/oauth/authorize`            | Browser consent for the redirect/popup flow.                    |
| `/oauth/token`                | Exchange a code / device\_code, or refresh.                     |
| `/oauth/revoke`               | Disconnect (revokes the whole session).                         |

Scopes: `wallet:read`, `wallet:transfer`, `x402:pay`. Moving money requires
`wallet:transfer`. See [OAuth 2.1](/api/oauth) for the full protocol.

## Grant a wallet permission

On first connect the agent has the tools but **no spending power** — Tally is
non-custodial, so you authorize a wallet explicitly. Ask the agent *"what's my
wallet?"* (it calls `get_wallet_info`); it returns a dashboard URL. Open it,
**Grant permission**, pick a funded wallet, set the per-tx + daily caps, and
approve via passkey. Grants are **mode-scoped** — a test-mode grant won't show in
live mode.

## Switching workspaces

The token is bound to the workspace you picked, so switching is a re-auth: run
the connect flow again and choose a different workspace, or revoke first via
`/oauth/revoke` (on Hermes, `hermes mcp logout tally`).

## Skill install (Hermes / OpenClaw)

For hosts that use a **skill manifest** instead of (or alongside) MCP, Tally
publishes one:

```bash theme={null}
hermes skills install https://www.tallyforagents.com/skill.md
```

The skill is API-key based: it collects a `TALLY_API_KEY` and teaches the agent
to call Tally's REST API directly. Use the device flow above when you want OAuth
(no key); use the skill when you want "install + paste a key."

## What's happening under the hood

* Every entry point runs the same enforcement: the Tally policy check (caps,
  allowlists, expiry) then Privy's secure-enclave signature. The MCP/OAuth layer
  can't widen those caps.
* The access token only ever sees the workspace + mode you chose on the consent
  screen, and it expires (the agent silently refreshes).
* Payments show up in the dashboard's Transactions tab with the same metadata as
  SDK or stdio calls.

## See also

* [Connect via stdio](/guides/connect-via-mcp) — the API-key subprocess path.
* [OAuth 2.1](/api/oauth) — the full protocol, including the device grant.
* [MCP server reference](/sdk/mcp-server) — tool inputs, outputs, and error shapes.