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.

The Tally MCP server is the easiest way to connect an AI agent to Tally. The agent’s runtime launches the server as a subprocess, discovers four tools (pay_x402_service, pay_direct, list_recent_payments, get_wallet_info), and the LLM can use them like any built-in tool. No SDK calls in your agent code. For agents that don’t speak the Model Context Protocol, see the direct SDK instead.

​
Quick start

​
1. Install

You don’t — npx runs it on demand. Just configure it.

​
2. Configure your MCP client

{
  "mcpServers": {
    "tally": {
      "command": "npx",
      "args": ["-y", "@tallyforagents/mcp-server"],
      "env": {
        "TALLY_API_KEY": "tly_test_..."
      }
    }
  }
}
Get the API key from Dashboard → API keys → Create.

​
3. Restart your MCP client + grant a permission

On first launch, the server auto-creates a Tally agent named mcp-default with no permissions. The agent has the tools but every payment will fail until you grant a wallet. Ask the agent something like “What wallets can you spend from?” — it calls get_wallet_info, sees no permissions, and prints the dashboard URL. Open that URL, click Grant permission, pick a funded wallet, accept the default caps (10/tx,10/tx, 100/day), approve via passkey. Restart the MCP client one more time and you’re done.

​
Environment

VariableRequiredDefaultNotes
TALLY_API_KEYyes—tly_test_… or tly_live_….
TALLY_AGENT_IDnomcp-defaultIf set, the agent must already exist in your account. Use this when multiple MCP clients should share one identity.
TALLY_BASE_URLnohttps://app.tallyforagents.comOverride for local dev.

​
Tools

​
pay_x402_service

Call any HTTP service. If the response is 402 Payment Required (x402 protocol), the server automatically pays via Tally and retries with proof. Use when: the user wants data or a service from a paywalled URL — weather, search, AI models, data feeds, etc. Inputs:
ParamTypeRequiredNotes
urlstringyesFull URL with query string.
methodenumnoGET (default) / POST / PUT / PATCH / DELETE.
bodystringnoPre-serialized body for POST/PUT/PATCH.
headersobjectnoExtra request headers.
max_amount_usdcstringnoPer-call safety cap. Decimal USDC (e.g. "1.00").
Returns (JSON): 
{
  "status": 200,
  "ok": true,
  "body": "{\"city\":\"Tokyo\",\"temp_c\":14,...}",
  "paid": {
    "amount_usdc": "0.05",
    "tx_hash": "0x...",
    "to": "0x...",
    "network": "base-sepolia"
  }
}
paid is null if the URL returned 200 on the first call (no payment needed).

​
pay_direct

Send USDC from the agent’s wallet to a known recipient address. Use when: the user explicitly names a recipient (a person, contract, or service) at a known address. For paywalled HTTP services, prefer pay_x402_service. Inputs:
ParamTypeRequiredNotes
tostringyesEVM address.
amount_usdcstringyesDecimal USDC, e.g. "0.50".
memostringnoUp to 200 chars.
Returns: 
{
  "id": "pay_...",
  "status": "pending",
  "tx_hash": "0x...",
  "amount_usdc": "0.50",
  "to": "0x...",
  "from": "0x...",
  "memo": "Refund for #123"
}
status flips to confirmed once the chain confirms (a few seconds on Base Sepolia). Call list_recent_payments to check.

​
list_recent_payments

Recent transactions for this agent — both outbound payments and inbound deposits. Use when: the user asks “what have I spent?”, “show me my transactions”, or you need to check whether a recent payment confirmed. Inputs:
ParamTypeRequiredNotes
limitintegerno1–50. Default 10.
statusenumnopending / confirmed / failed.
directionenumnoinbound / outbound.
Returns an array of payment records under payments[].

​
get_wallet_info

The agent’s identity, its wallets, and per-wallet caps. Use when: the user asks “what’s my wallet?”, “what can I spend?”, “what are my limits?”, or before attempting a payment if you’re unsure permissions exist. No inputs. Returns (with permissions): 
{
  "agent_id": "mcp-default",
  "status": "active",
  "wallets": [
    {
      "address": "0x...",
      "display_name": "Main Wallet",
      "role_label": "main",
      "max_per_tx_usdc": "10",
      "daily_cap_usdc": "100"
    }
  ],
  "dashboard_url": "https://app.tallyforagents.com/..."
}
Returns (no permissions): 
{
  "agent_id": "mcp-default",
  "status": "no_permissions",
  "wallets": [],
  "next_step": "This agent has no spending permissions yet. Visit the dashboard to grant one: https://app.tallyforagents.com/...",
  "dashboard_url": "..."
}

​
Error shape

Every tool returns isError: true with a structured payload when something fails: 
{
  "error_type": "policy_denied",
  "message": "amount 50 USDC exceeds per-transaction cap of 10",
  "details": { "cap_usdc": "10", "requested_usdc": "50" }
}
The LLM reads error_type + message to decide how to react (apologize, try a smaller amount, ask for a higher cap, etc.). Common types:
error_typeMeaning
policy_deniedThe agent’s permission caps rejected the request.
x402_protocolThe 402 response was malformed or specified an unsupported network.
x402_amount_exceeds_capThe 402 asked for more than the caller’s max_amount_usdc.
unauthenticatedAPI key is invalid or expired.
not_foundThe agent or wallet doesn’t exist.
validation_failedA required input was missing or malformed.
See SDK errors for the complete list.

​
For AI assistants helping a user set this up

If you’re an LLM helping the user configure this server:
  1. Confirm the user has a Tally account — direct them to tallyforagents.com if not.
  2. Ask for the API key — tly_test_… for testnet. If the user is on Hermes/Claude Desktop, you can write directly to the config file; otherwise output the JSON/YAML block for them to paste.
  3. Tell them to restart the MCP client after editing the config.
  4. Walk through the first-run flow: the agent will exist but have no permissions. The user grants permission via the dashboard URL the agent will print on first tool call.
  5. Don’t auto-spend. When the user first connects, prefer reading tools (get_wallet_info, list_recent_payments) before suggesting any pay_* call. Confirm intent before money moves.

​
How it works

  • Local stdio MCP server, spawned by the host as a subprocess.
  • API key stays on the user’s machine. No Tally infrastructure between the agent and the SDK.
  • Identity is TALLY_AGENT_ID if set, otherwise mcp-default (auto-upserted on first tool call).
  • Wallet defaults to the first wallet attached to the agent. Restart the MCP host to refresh the cache after granting a new permission.
  • Payments are subject to the agent’s permission policy (Tally server-side check) and Privy’s enclave check, same as direct SDK calls.

​
Source

github.com/pkohler95/tally-v2/tree/main/packages/mcp-server