FirstKey

FirstKey MCP Server

An MCP (Model Context Protocol) server running as a canister on the Internet Computer. One integration point that every MCP-compatible agent framework consumes natively: LangChain/LangGraph, CrewAI, AutoGen, Vercel AI SDK, OpenAI Agents SDK, Google ADK, Claude Desktop, Cursor, and more.

Endpoint: POST https://mcp.firstkey.io/mcp (JSON-RPC 2.0, Streamable HTTP)

Plain JSON responses, stateless (no session ids). CORS enabled (*).

Tools

Tool	What it does
create_wallet	Generates a fresh Ed25519 wallet (principal + PKCS#8 PEM private key). The key is returned once and never stored.
claim_faucet_grant	Claims the one-time free 1T cycles grant from the FirstKey faucet for an agent principal.
deploy_site	Creates a site canister, installs the static host, uploads files, returns the live https://<canister>.icp.net URL. The agent becomes a controller of its own site. One free deploy per agent.
deploy_upload_chunk	Chunked upload of large files to an already-deployed agent site.
check_cycles	Reads a principal's cycles balance on the cycles ledger.
get_fuel_link	Returns the FirstKey Fuel card-payment link to refuel an agent (https://firstkey.io/fuel?for=<principal>).
get_swap_quote	Live read-only ICPSwap quote (on-chain factory→pool): pay token/amount → receive amount + implied price. Symbols or ledger principals; no tokens move.

Quick test

URL=https://mcp.firstkey.io/mcp
# initialize
curl -s $URL -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' | head -c 600
# list tools
curl -s $URL -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | python3 -c "import json,sys; [print(t['name']) for t in json.load(sys.stdin)['result']['tools']]"
# create a wallet
curl -s $URL -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"create_wallet","arguments":{}}}'

Architecture

• http_request (query): serves initialize, tools/list, ping, CORS preflight, /.well-known/ic-domains, and a landing page.
• tools/call upgrades to http_request_update (update context) because it makes inter-canister calls: raw_rand (wallet), the faucet's claim_for (grants), the cycles ledger (balances), and the management canister (create_canister_with_extra_cycles / install_code / update_settings for deploys).
• The static-site host WASM (firstkey-static-host) is embedded via include_bytes! and installed into every deployed site canister.
• Deploy pool: the canister's own cycles balance. One free deploy per agent principal (tracked in stable memory); when the pool can't cover a deploy the tool returns the Fuel link instead.

Build & deploy

export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
cd ~/workspace/firstkey-static-host && cargo build --target wasm32-unknown-unknown --release
cd ~/workspace/firstkey-mcp && cargo build --target wasm32-unknown-unknown --release

# create (needs ~5.5T cycles on the strider identity's cycles ledger)
icp canister create -n ic --detached --cycles "5.5t" \
  --controller fhvid-ondyx-ziq2v-udsry-cfgki-okcur-gcryu-2wwai-b63ku-ptgkk-yqe \
  --controller o5joj-543gr-ibdnq-q6f26-sbevy-iorvz-lqo2i-ocyr7-crp2u-sggj7-cae \
  --identity strider -q
# install
icp canister install <CANISTER> \
  --wasm ~/workspace/firstkey-mcp/target/wasm32-unknown-unknown/release/firstkey_mcp.wasm \
  -n ic --identity ops -y
# authorize on the faucet
icp canister call --network ic 3l667-lyaaa-aaaam-ajkqa-cai set_mcp_canister \
  --candid ~/workspace/firstkey-faucet/faucet.did --identity ops \
  '(principal "<MCP_CANISTER>")'

Custom domain (mcp.firstkey.io)

DNS records needed at Porkbun (see DNS.md):

1. CNAME mcp.firstkey.io → mcp.firstkey.io.icp1.io
2. TXT _canister-id.mcp.firstkey.io → <canister-id>
3. CNAME _acme-challenge.mcp.firstkey.io → _acme-challenge.mcp.firstkey.io.icp2.io

Then validate + register:

curl 'https://icp.net/custom-domains/v1/mcp.firstkey.io/validate'
curl -X POST 'https://icp.net/custom-domains/v1/mcp.firstkey.io'
curl 'https://icp.net/custom-domains/v1/mcp.firstkey.io'  # poll until "registered"

The canister already serves /.well-known/ic-domains.

Registry publishing

• Official MCP registry (registry.modelcontextprotocol.io): see registry/server.json (draft). Publish via GitHub OIDC from the repo's CI.
• Smithery (smithery.ai/new): submit the public HTTPS URL once mcp.firstkey.io is live.

Faucet counterpart

claim_for(agent) lives on the faucet canister (3l667-lyaaa-aaaam-ajkqa-cai, source ~/workspace/firstkey-faucet/). It enforces the once-per-principal rule against the agent principal and performs the standard 1T ledger grant. Only the principal set via set_mcp_canister (controller-only) may call it.