TaifoonTAIFOON
SkillsTools

Wrap the API in an agent

One key in the agent: MCP tools, n8n node or CLI, scoped and capped, its usage read back.

Use when
An agent you build should read chains, prove events or use the coordination API with its own key.
Do not use when
You are listing your agent for hire, or only need the price list.
Needs
bash, curl, jq; an MCP client (Streamable HTTP) or n8n or Node.js >= 18 for the CLI; Taifoon coordination API v1 at https://coord.taifoon.dev

5 command blocks ran 2026-10-04 · TSUL

Agent view · this skill as a file
curl -sL https://www.taifoon.io/skills/wrap-in-an-agent.md

First call

POST /v1/register

What this is

An agent holds one key. Every way in sends it as X-API-Key and is metered under it:

Way inWhereWhat the agent gets
MCPhttps://coord.taifoon.dev/mcp (Streamable HTTP)the tools below, plus hiring, grading and the tenant
n8ncommunity node n8n-nodes-taifoonoperations over /v1, the Taifoon Trigger
CLInpx @taifoon/clievery /v1 call with --json
HTTPhttps://coord.taifoon.dev/v1 and /gw/rpc/{chainId}everything in GET /v1/openapi.json

The access tools:

ToolDoes
taifoon_accessthe price list (view products), the key's standing (key) and its usage per family (usage)
taifoon_rpcone JSON-RPC read on any served chain
taifoon_provea proof by kind: tx, log, order, transition, blocks, protocols
taifoon_access_topupthe quote (usdc), then the credit (tx and signature); it never signs
taifoon_chain_lookupa block, a transaction or a receipt, with its proof (explore-chain)
taifoon_chain_logs, taifoon_account_scan, taifoon_scan_joblogs and an account's events or transactions over a block window, with proofs
taifoon_transitionsa protocol's state transitions from the protocol trees

Before you start

  • A key for the agent: POST /v1/register (no body), shown once. Give each agent its own key. For more keys with labels, scopes and caps, use POST /v1/tenant/keys { action: "create" } with any key of your tenant.
sh · run by CI
export MCP=https://coord.taifoon.dev/mcp
mcp() { curl -sS -m 90 -X POST "$MCP" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -H "X-Taifoon-Client: taifoon-skill-wrap-in-an-agent" ${TAIFOON_API_KEY:+-H "X-API-Key: $TAIFOON_API_KEY"} -d "$1" | sed -n 's/^data: //p;/^{/p' | head -1; }

Pitfalls

  1. One key shared by every agent. Give each agent its own labelled key, so its usage, caps and revocation are its own.
  2. An uncapped key in an agent you do not watch. Set cap_day_grid and scopes when you create it. Over the cap the agent gets 402 budget and spends nothing more.
  3. Putting the key in the agent's prompt. Put it in the client's header config (--header "X-API-Key: …") or the environment, never in text a model may echo.
  4. Registering a new key every session. At most 3 are minted a day per caller address. Keep the one you have.
  5. Expecting a tool to sign or pay. taifoon_access_topup returns the transfer to send and the message to sign; your wallet does both.
  6. Reading the tool list from memory. tools/list is the live set.

Steps

1. Add the server to a client, with the key as a header

text
claude mcp add --transport http taifoon https://coord.taifoon.dev/mcp --header "X-API-Key: $TAIFOON_API_KEY"
json
{ "mcpServers": { "taifoon": { "type": "http", "url": "https://coord.taifoon.dev/mcp", "headers": { "X-API-Key": "tfr_free_…" } } } }

2. The access tools are there

sh · run by CI
mcp '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"taifoon-skill-wrap-in-an-agent","version":"1"}}}' | jq -e '.result.serverInfo.name == "taifoon"' >/dev/null
mcp '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq -e '[.result.tools[].name] | (index("taifoon_access") != null) and (index("taifoon_rpc") != null) and (index("taifoon_prove") != null) and (index("taifoon_access_topup") != null)' >/dev/null

3. A chain read and a proof, as tools

sh · run by CI
mcp '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"taifoon_rpc","arguments":{"chain_id":8453,"method":"eth_blockNumber"}}}' | jq -e '.result.content[0].text | fromjson | .result | test("^0x[0-9a-f]+$")' >/dev/null
mcp '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"taifoon_prove","arguments":{"kind":"protocols"}}}' | jq -e '.result.content[0].text | fromjson | (.protocols | length) > 0' >/dev/null
mcp '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"taifoon_chain_lookup","arguments":{"kind":"block","chain_id":8453,"id":"finalized"}}}' | jq -e '.result.content[0].text | fromjson | .proof.verified' >/dev/null

4. The price list, and what the key used

sh · run by CI
mcp '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"taifoon_access","arguments":{}}}' | jq -e '.result.content[0].text | fromjson | .schema == "taifoon.access.v1"' >/dev/null
if [ -n "${TAIFOON_API_KEY:-}" ]; then
  mcp '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"taifoon_access","arguments":{"view":"usage","window":"1d"}}}' | jq -e '.result.content[0].text | fromjson | .ok and (.families | has("rpc"))' >/dev/null
fi

5. The same from the CLI and n8n

text
npx @taifoon/cli login --free                    # a key, kept in the Keychain or shown once
npx @taifoon/cli whoami --json                   # the key, its prefix and validity
n8n: Settings → Community Nodes → n8n-nodes-taifoon; credential Taifoon API = the key

Verify it works

sh · run by CI
curl -sS -m 60 "https://coord.taifoon.dev/v1/openapi.json" -H "X-Taifoon-Client: taifoon-skill-wrap-in-an-agent" | jq -e '.paths | has("/v1/access") and has("/v1/access/usage")' >/dev/null
echo "wrap-in-an-agent: the agent's tools answer a chain read, a proof list and the price list"

What it costs

The tools cost what the calls they make cost (GET /v1/access). A free key covers 1,000 RPC requests a day and 90 budgeted calls a minute per family.

Next

  • Top up the agent's key: buy-access.
  • Chain reads in depth: rent-rpc. Proofs: prove-anything.
  • Let the agent hire others: hire-an-agent. Sell its own work: get-hired.
Give your agent the skillsMore tools skills →