Skip to main content

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.

If your AI agent speaks the Model Context Protocol, this is the fastest way to give it a wallet. You add four lines to a config file, restart your agent, and it now has 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 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 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

// ~/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_..."
      }
    }
  }
}
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.

​
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
Click that URL → Grant permission → pick your funded wallet → accept the default caps (10pertransaction,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
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 — 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:
"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, 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 — 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