@tallyforagents/mcp-server

MCP server for Tally — give any MCP-aware AI agent (Claude Desktop, Cursor, Hermes, Cline, Goose) a USDC wallet with scoped spending permissions.

Once configured, the agent gets four new tools:

| Tool | What it does | |---|---| | pay_x402_service | Call any HTTP URL; auto-pay via Tally if it returns 402. | | pay_direct | Send USDC to a known address. | | list_recent_payments | Inspect the agent's transaction history. | | get_wallet_info | Discover wallets, balances, and per-tx/daily caps. |

The agent doesn't need code changes. Just config.

Authentication: OAuth or API key

The server takes one credential:

• TALLY_ACCESS_TOKEN — an OAuth access token. Hosts that support OAuth 2.1 (e.g. Hermes) run the connect flow for you and inject this — no secret in config, and you can switch workspaces without editing files. See OAuth setup (hermes mcp auth tally).
• TALLY_API_KEY — a static tly_test_… / tly_live_… key. Works on every host. The setup below uses this path.

If both are set, the access token wins.

Setup (API key)

1. Get a Tally API key

Sign in at app.tallyforagents.com, fund your wallet, then create an API key (Dashboard → API keys → Create). Copy the tly_test_… plaintext.

2. Add the server to your MCP client config

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "tally": {
      "command": "npx",
      "args": ["-y", "@tallyforagents/mcp-server"],
      "env": {
        "TALLY_API_KEY": "tly_test_..."
      }
    }
  }
}

Hermes (~/.hermes/config.yaml):

mcp_servers:
  tally:
    command: "npx"
    args: ["-y", "@tallyforagents/mcp-server"]
    env:
      TALLY_API_KEY: "tly_test_..."

Cursor, Cline, Goose, other MCP clients: same shape — command: npx, args: ["-y", "@tallyforagents/mcp-server"], env.TALLY_API_KEY.

3. Restart your MCP client

On first launch the server auto-creates a Tally agent called mcp-default. The agent starts with no permissions — the LLM has the tools but every payment will fail until you grant it a wallet.

4. Grant the agent a wallet permission

Ask the agent: "What wallets can you spend from?" — it'll call get_wallet_info, see no permissions, and return the dashboard URL. Open that URL, click Grant permission, pick your wallet, accept the default caps ($10/tx, $100/day), and approve via passkey.

Restart the MCP client one more time so the server re-fetches the agent. Now the agent can pay.

Configuration

| Env var | Required | Default | Notes | |---|---|---|---| | TALLY_ACCESS_TOKEN | one of | — | tly_oat_… OAuth access token (usually injected by the host's OAuth flow). Workspace/agent are bound to the token; resolved via GET /v1/me. | | TALLY_API_KEY | one of | — | tly_test_… or tly_live_… static key. | | TALLY_AGENT_ID | no | mcp-default | Overrides the token-bound agent (OAuth) or names the agent (API key). When set, the agent must already exist (unless mcp-default). | | TALLY_BASE_URL | no | https://app.tallyforagents.com | Override for local dev. |

How it works

The server is a local stdio process the MCP host launches as a subprocess. Your credential never leaves your machine — with OAuth, the host keeps the tokens and injects only TALLY_ACCESS_TOKEN. The server holds an in-memory cache of the agent's wallets — restart the MCP host to pick up new permission grants. Secrets are scrubbed from the server's stderr logs.

Payments go through the full Tally enforcement stack: server-side policy check, then Privy enclave verification. If the LLM tries to overspend, the call fails with a typed error and the LLM can react.

Links

• Tally docs
• MCP reference page
• Recipe: Connect your AI agent via MCP
• Issues

License

MIT