> ## 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 via stdio (local subprocess)

> The stdio path: give a stdio-only MCP host (Claude Desktop, Cursor, Cline, Goose) a Tally wallet by running a local subprocess with an API key. Most agents should use the hosted endpoint instead.

<Note>
  **Most agents should use the [hosted endpoint](/guides/connect-remote-mcp) instead.** It
  connects over the network with OAuth (a browser approval) — no local install, no
  API key in config — and it's where Tally ships new tools first (it currently has
  more tools than this stdio path). Use *this* page only if your MCP host speaks
  **stdio only** and can't reach the hosted endpoint directly or via
  [`mcp-remote`](https://www.npmjs.com/package/mcp-remote).
</Note>

If your AI agent runs an MCP server as a local subprocess (stdio), this gives it a wallet: you add four lines to a config file, restart your agent, and it gets tools to pay for paywalled APIs (x402), send USDC, and read its own transaction history — all bounded by per-tx and daily caps you set in Tally.

This guide is for the user side. If you're an LLM helping a human set this up, the [MCP server reference](/sdk/mcp-server) has a dedicated AI-assistant playbook section.

## What you'll have at the end

A working AI agent that, when you ask *"what's the weather in Tokyo?"*, decides on its own to:

1. Call the x402-paywalled weather endpoint
2. Receive `402 Payment Required` with terms (0.05 USDC to a specific address)
3. Pay via Tally — your wallet, your scoped permissions
4. Retry with proof, receive the data
5. Answer you

You can ask *"what have I spent?"* and it'll list the transaction. You can ask *"send 1 USDC to 0x…"* and (within the caps you set) it does.

The agent gets four new tools: `pay_x402_service`, `pay_direct`, `list_recent_payments`, `get_wallet_info`.

## Prerequisites

* A Tally account with a **funded testnet wallet** ([Quickstart](/quickstart) walks through this in 3 minutes).
* A **Tally API key** (Dashboard → API keys → Create — `tly_test_…`).
* An MCP-aware AI client. Confirmed working: **Claude Desktop**, **Cursor**, **Hermes**, **Cline**, **Goose**.

That's it. No SDK install. No code.

## Step 1 — Add the server to your client config

<CodeGroup>
  ```json Claude Desktop theme={null}
  // ~/Library/Application Support/Claude/claude_desktop_config.json   (macOS)
  // %APPDATA%\Claude\claude_desktop_config.json                       (Windows)
  {
    "mcpServers": {
      "tally": {
        "command": "npx",
        "args": ["-y", "@tallyforagents/mcp-server"],
        "env": {
          "TALLY_API_KEY": "tly_test_..."
        }
      }
    }
  }
  ```

  ```yaml Hermes theme={null}
  # ~/.hermes/config.yaml
  mcp_servers:
    tally:
      command: "npx"
      args: ["-y", "@tallyforagents/mcp-server"]
      env:
        TALLY_API_KEY: "tly_test_..."
  ```

  ```json Cursor theme={null}
  // Settings → MCP → Add new MCP server, OR ~/.cursor/mcp.json
  {
    "mcpServers": {
      "tally": {
        "command": "npx",
        "args": ["-y", "@tallyforagents/mcp-server"],
        "env": {
          "TALLY_API_KEY": "tly_test_..."
        }
      }
    }
  }
  ```

  ```json Cline / Goose / generic theme={null}
  {
    "mcpServers": {
      "tally": {
        "command": "npx",
        "args": ["-y", "@tallyforagents/mcp-server"],
        "env": {
          "TALLY_API_KEY": "tly_test_..."
        }
      }
    }
  }
  ```
</CodeGroup>

<Tip>
  Paste your real API key in place of `tly_test_...`. Keep it out of any code that goes to git; the config file location above is local-only by convention.
</Tip>

## Step 2 — Restart your agent

Quit and relaunch your MCP client. On startup it spawns `npx -y @tallyforagents/mcp-server` as a subprocess and discovers its tools.

You can confirm the connection by asking the agent: *"what tools do you have for Tally?"*. It should list `pay_x402_service`, `pay_direct`, `list_recent_payments`, `get_wallet_info`.

## Step 3 — Grant the agent a wallet permission

On first connect, the server auto-creates a Tally agent called `mcp-default` in your account. But it has **no spending permissions yet** — you have to authorize a wallet before any payment can happen. (This is by design — Tally is non-custodial, so the human wallet owner consents to every signer.)

Ask the agent: *"What wallets can you spend from?"*

It'll call `get_wallet_info`, see no permissions, and respond with something like:

> This agent has no spending permissions yet. Visit the dashboard to grant one:
> [https://app.tallyforagents.com/\{your-slug}/agents/mcp-default](https://app.tallyforagents.com/\{your-slug}/agents/mcp-default)

Click that URL → **Grant permission** → pick your funded wallet → accept the default caps (**$10 per transaction, $100 daily** — easy to lower or raise) → approve via passkey.

Restart your MCP client one more time so the server picks up the new permission.

## Step 4 — Try it

Ask your agent something that needs payment. The hosted demo endpoint Tally runs returns weather for any city, paywalled at 0.05 USDC:

> Get the weather in Tokyo from [https://app.tallyforagents.com/api/demo/x402-weather](https://app.tallyforagents.com/api/demo/x402-weather)

The agent will call `pay_x402_service`, the server will pay 0.05 testnet USDC from your wallet, retry the request, and the agent will summarize the weather for you. Open your [Tally dashboard's transactions tab](https://www.tallyforagents.com) — the payment is there.

## Common follow-up tasks

### Use a custom agent name

By default the server auto-creates `mcp-default`. If you want the agent to use a name you choose (so you can manage multiple MCP-connected agents from one Tally account):

1. Register the agent in the dashboard first (Dashboard → Agents → Register agent), name it whatever you like.
2. Grant it a wallet permission.
3. Set `TALLY_AGENT_ID` in your MCP client config:

```json theme={null}
"env": {
  "TALLY_API_KEY": "tly_test_...",
  "TALLY_AGENT_ID": "hermes"
}
```

Restart. The server now identifies as `hermes`.

### Tighten the per-call spending cap

The agent's policy ceiling is set in the dashboard (\$10/tx default). For an extra defensive layer, the LLM can include `max_amount_usdc` per call:

> Search arxiv via [https://paid-arxiv.example.com](https://paid-arxiv.example.com), but don't spend more than \$0.10 per query.

The agent will pass `max_amount_usdc: "0.10"` and the server will throw before paying anything above that.

### Share one agent across multiple clients

If you want Claude Desktop *and* Cursor *and* Hermes to all act as the same Tally agent (so the transaction history is unified), set the same `TALLY_AGENT_ID` in every client's config. The single agent has one permission per wallet; all three clients spend from the same caps.

## Troubleshooting

**Agent reports "no spending permissions"**: you haven't granted a wallet in the dashboard yet, or you granted it after the MCP server started. Restart the MCP client.

**Tools don't appear after restart**: check the MCP client's logs (Claude Desktop has a MCP log viewer in settings). If you see `TALLY_API_KEY is required`, the env block in your config wasn't picked up — check the JSON/YAML syntax and that the API key is wrapped in quotes.

**Payment fails with `policy_denied`**: the request exceeded your wallet's per-tx or daily cap. Either lower the request or raise the cap in the dashboard (Agents → \{your agent} → edit permission).

**`unauthenticated` errors**: API key is invalid, revoked, or in the wrong account. Generate a new one in the dashboard.

## What's happening under the hood

* The MCP server runs as a local subprocess of your agent. **Your API key never leaves your machine.**
* The server is a thin wrapper around the [Tally SDK](/sdk/installation) — same enforcement rules, same audit trail. Every payment shows up in the dashboard with the same metadata as SDK calls.
* The agent identity (`mcp-default` or your custom `TALLY_AGENT_ID`) is the same one you manage in the dashboard. Granting/revoking permissions, rotating keys, viewing transactions, setting webhooks — all the dashboard tools apply.
* Tally is non-custodial. The server holds your API key, but spending is always bounded by the wallet owner's signed permission policy (enforced server-side by Tally and again by Privy's secure enclave). The MCP server can't change those caps.

## Next steps

* [MCP server reference](/sdk/mcp-server) — full tool docs, env vars, error shapes.
* [Permissions](/permissions) — how the per-tx and daily caps work.
* [Webhooks](/sdk/webhooks) — get notified when the agent makes a payment.
* Want code-level control instead? Use the [SDK directly](/sdk/installation).