FirstKey

FirstKey MCP 服务

一个作为 Internet Computer 上 canister 运行的 MCP（Model Context Protocol）服务。 每个兼容 MCP 的 Agent 框架都可原生使用的集成入口： LangChain/LangGraph、CrewAI、AutoGen、Vercel AI SDK、OpenAI Agents SDK、Google ADK、 Claude Desktop、Cursor 等。

端点： POST https://mcp.firstkey.io/mcp（JSON-RPC 2.0，Streamable HTTP）

返回纯 JSON，无状态（无会话 ID）。已启用 CORS（*）。

工具

工具	功能
create_wallet	生成一个全新的 Ed25519 钱包（principal + PKCS#8 PEM 私钥）。密钥只返回一次，且永不存储。
claim_faucet_grant	为 Agent principal 领取 FirstKey 水龙头提供的一次性免费 1T cycles 赠款。
deploy_site	创建站点 canister、安装静态主机、上传文件，并返回可访问的 https://<canister>.icp.net URL。Agent 将成为其站点的控制器。每个 Agent 可免费部署一次。
deploy_upload_chunk	将大文件分块上传到已部署的 Agent 站点。
check_cycles	在 cycles 账本上读取 principal 的 cycles 余额。
get_fuel_link	返回 FirstKey Fuel 的银行卡付款链接，为 Agent 补充燃料（https://firstkey.io/fuel?for=<principal>）。
get_swap_quote	获取实时、只读的 ICPSwap 报价（链上 factory→pool）：支付代币/金额 → 收到的金额 + 推算价格。接受符号或账本 principal；不会转移代币。

快速测试

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":{}}}'

架构

• http_request（查询）：提供 initialize、tools/list、ping、CORS 预检请求、 /.well-known/ic-domains 和落地页。
• tools/call 会升级为 http_request_update（更新上下文），因为它会进行 canister 间调用：raw_rand（钱包）、水龙头的 claim_for（赠款）、 cycles 账本（余额），以及管理 canister （部署时使用 create_canister_with_extra_cycles / install_code / update_settings）。
• 静态站点主机 WASM（firstkey-static-host）通过 include_bytes! 嵌入，并安装到每个已部署的站点 canister 中。
• 部署资金池：canister 自身的 cycles 余额。每个 Agent principal 可免费部署一次 （记录在稳定内存中）；资金池无法支付部署费用时，工具会改为返回 Fuel 链接。

构建与部署

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>")'

自定义域名（mcp.firstkey.io）

Porkbun 上需要配置以下 DNS 记录（参见 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

然后验证并注册：

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"

canister 已提供 /.well-known/ic-domains。

注册表发布

• 官方 MCP 注册表（registry.modelcontextprotocol.io）：参见 registry/server.json （草稿）。通过仓库 CI 使用 GitHub OIDC 发布。
• Smithery（smithery.ai/new）：待 mcp.firstkey.io 上线后，提交公开的 HTTPS URL。

水龙头对应实现

claim_for(agent) 位于水龙头 canister（3l667-lyaaa-aaaam-ajkqa-cai， 源码位于 ~/workspace/firstkey-faucet/）。它针对 Agent principal 执行每个 principal 仅可领取一次的规则， 并发放标准的 1T 账本赠款。只有通过 set_mcp_canister 设置的 principal（仅限控制器）才能调用它。