MCP server (`@talon/mcp`)

Plug TALON into Claude Desktop, Claude Code, Cursor, or any MCP client. The server is a thin client of the REST API (docs/api.md): it holds your API key, nothing else. No wallet keys, no chain RPC, no database.

1. Get a key and an agent

Create an API key on https://www.deploytalon.com/developers. tlk_live_... targets mainnet (chain 4663), tlk_test_... targets testnet (46630).
Note your agent id from the dashboard. If the account has exactly one agent the server picks it automatically.

Sign in to the dashboard by connecting your wallet and signing a free message (no email, no password). That wallet owns your agents and keys.

Shortcut: npx @talon/cli login (the browser asks you to connect your wallet and approve the code), then npx @talon/cli mcp prints every snippet below with your key and agent filled in.

2. Connect a client

Claude Desktop

claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\):

{
  "mcpServers": {
    "talon": {
      "command": "npx",
      "args": ["-y", "@talon/mcp"],
      "env": { "TALON_API_KEY": "tlk_live_...", "TALON_AGENT_ID": "agt_..." }
    }
  }
}

Claude Code

claude mcp add talon -e TALON_API_KEY=tlk_live_... -e TALON_AGENT_ID=agt_... -- npx -y @talon/mcp

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "talon": {
      "command": "npx",
      "args": ["-y", "@talon/mcp"],
      "env": { "TALON_API_KEY": "tlk_live_...", "TALON_AGENT_ID": "agt_..." }
    }
  }
}

Hosted URL (nothing to install)

https://mcp.deploytalon.com/mcp speaks streamable HTTP. Send your key as a bearer token on every request.

{
  "mcpServers": {
    "talon": {
      "url": "https://mcp.deploytalon.com/mcp",
      "headers": { "Authorization": "Bearer tlk_live_..." }
    }
  }
}

Claude Code: claude mcp add --transport http talon https://mcp.deploytalon.com/mcp --header "Authorization: Bearer tlk_live_...". Add X-Talon-Agent: agt_... if the account has more than one agent.

3. What the model can do

Every TALON tool that is exposed to agents is an MCP tool with the same name:

Category	Tools	Risk
wallet	`agent_get`, `wallet_balances`, `wallet_portfolio`, `wallet_history`	read
wallet	`wallet_transfer`	sensitive (approval)
market	`token_lookup`, `token_price`, `token_chart`, `market_trending`, `market_new_launches`, `stock_tokens_list`	read, public
trading	`swap_quote` (read), `swap_execute`, `curve_buy`, `curve_sell`, `approve_token`	write
launch	`launch_quote` (read), `launch_token` (sensitive), `earnings_get`, `earnings_claim`	mixed
automation	`automation_list`, `automation_create`, `automation_cancel`	read / write

The exact list comes from GET /api/v1/tools at startup, so new tools appear without upgrading the package. Control tools (approval_list, approval_resolve) are never exposed to the model: only you approve things.

Each tool description ends with Risk: read | write | sensitive. read tools are marked readOnlyHint, sensitive tools destructiveHint, so clients that gate on annotations behave sensibly.

Approvals

When your policy routes a call to the approval queue the tool returns:

Approval required (id apr_...) for wallet_transfer. Reasons: ...
Ask the user to approve it in the TALON dashboard or Telegram; then call approval status with wallet_history or retry.

Approve it on https://www.deploytalon.com/approvals or tap Yes in Telegram, then tell the model to retry.

Errors

API errors come back as isError tool results with the code and message, for example POLICY_DENIED: Daily spend cap reached. The model can read the message and adjust instead of crashing the session.

Resources and prompt

talon://agent: profile, wallet address, policy summary.
talon://policy: the full policy JSON.
talon://tools: the catalogue with JSON schemas.
Prompt talon-briefing: "Summarize my agent's wallet, positions, and trending tokens."

Environment reference

Variable	Default	Purpose
`TALON_API_KEY`	required	API key
`TALON_AGENT_ID`	only agent on the account	agent to act as
`TALON_API_URL`	`https://api.deploytalon.com`	API origin; `http://localhost:4000` for local dev
`MCP_TRANSPORT`	`stdio`	`http` for the hosted mode (`--http` flag does the same)
`PORT`, `HOST`	`8787`, `0.0.0.0`	HTTP bind address
`TALON_TIMEOUT_MS`	`60000`	per-request timeout

Running the hosted mode yourself

npx -y @talon/mcp --http
curl http://localhost:8787/healthz

Each Authorization: Bearer tlk_... gets its own MCP session and its own API client; a session rejects requests that present a different key. The tool catalogue is cached for 60 seconds across sessions.

Troubleshooting

NO_API_KEY: the env block is missing or the client did not pass it through. Claude Desktop needs a full restart after editing the config.
AGENT_REQUIRED: the account has several agents; set TALON_AGENT_ID.
UNAUTHORIZED: the key was revoked or belongs to another environment (tlk_test_ vs tlk_live_).
Logs go to stderr, prefixed [talon-mcp], so they never corrupt the stdio protocol stream.

MCP server (@talon/mcp)