FirstKey

FirstKey MCP サーバー

Internet Computer 上でカニスターとして動作する MCP（Model Context Protocol）サーバーです。 LangChain/LangGraph、CrewAI、AutoGen、Vercel AI SDK、OpenAI Agents SDK、Google ADK、 Claude Desktop、Cursor など、MCP 互換のあらゆるエージェントフレームワークがネイティブに利用できる統合ポイントです。

エンドポイント： 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	エージェントの principal に対する、FirstKey faucet の一度限りの無料 1T cycles 付与を受け取ります。
deploy_site	サイトカニスターを作成し、静的ホストをインストールしてファイルをアップロードし、公開された https://<canister>.icp.net URL を返します。エージェントは自身のサイトのコントローラーになります。エージェントごとに無料デプロイは 1 回です。
deploy_upload_chunk	デプロイ済みのエージェントサイトに、大きなファイルを分割してアップロードします。
check_cycles	cycles ledger から principal の cycles 残高を読み取ります。
get_fuel_link	エージェントに追加の燃料を補給する FirstKey Fuel のカード決済リンク（https://firstkey.io/fuel?for=<principal>）を返します。
get_swap_quote	ICPSwap の最新の読み取り専用見積もり（オンチェーンの factory→pool）を取得します。支払いトークン／金額から受取金額と算出価格を返します。シンボルまたは ledger 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（更新コンテキスト）に切り替わります。これは、 raw_rand（ウォレット）、faucet の claim_for（付与）、 cycles ledger（残高）、管理カニスター（デプロイ用の create_canister_with_extra_cycles／install_code／update_settings）への カニスター間呼び出しを行うためです。
• 静的サイトホストの WASM（firstkey-static-host）は include_bytes! を介して 埋め込まれ、デプロイされるすべてのサイトカニスターにインストールされます。
• デプロイプール：カニスター自身の cycles 残高です。エージェント principal ごとに無料デプロイは 1 回です （安定メモリに記録）。プールでデプロイ費用を賄えない場合、ツールは 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"

カニスターはすでに /.well-known/ic-domains を提供しています。

レジストリへの公開

• 公式 MCP レジストリ（registry.modelcontextprotocol.io）：registry/server.json （ドラフト）を参照してください。リポジトリの CI から GitHub OIDC を使って公開します。
• Smithery（smithery.ai/new）：mcp.firstkey.io が公開されたら、パブリック HTTPS URL を送信します。

Faucet の対応処理

claim_for(agent) は faucet カニスター（3l667-lyaaa-aaaam-ajkqa-cai、 ソース ~/workspace/firstkey-faucet/）にあります。エージェント principal に対して principal ごとに一度限りのルールを適用し、標準の 1T ledger 付与を実行します。 set_mcp_canister で設定された principal（コントローラーのみ）だけがこれを呼び出せます。