Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only

[hanwencheng]

Context

The AgentKeys MCP server is the integration surface that makes the Agent IAM thesis legible to xiaozhi-server's LLM (and any other MCP-speaking host). Without this server, the broker + signer + workers shipped in Phase 0 are invisible to the agent runtime — there's no clean way for the xiaozhi LLM to ask "what does this actor have permission to do?" or "fetch my Chengdu trip memory." The MCP server is the answer.

This is THE critical-path issue for M1. Every other M1 issue (#108 namespace, #109 two-tier audit, #110 revocation, #111 parent UI) plumbs through the tools defined here. M1's three-act demo storyboard reads as "Agent IAM, not chatbot" only when these 7 tools return the right answers in the right shape.

Scope (M1)

Active tools (7) — answer real calls

Tool	Signature	What it returns
agentkeys.identity.whoami	(actor)	{omni, display_name, vendor, scopes} from the chain identity tree
agentkeys.memory.get	(actor, namespace)	cap-token-verified S3 read filtered by namespace (per #108)
agentkeys.memory.put	(actor, namespace, content)	cap-token-verified S3 write with namespace binding
agentkeys.permission.check	(actor, scope, params?)	deterministic policy engine (no LLM) — accept / deny / ask-parent verdict
agentkeys.cap.mint	(actor, op, params, ttl)	bounded-TTL cap-token per agent-iam-strategy.md §3.1
agentkeys.cap.revoke	(cap_id)	immediate online; bounded offline per #110
agentkeys.audit.append	(actor, event)	emits to two-tier audit (real-time off-chain + 2-min on-chain batch) per #109

Schema-only tools (3) — return not_implemented_in_v1

• agentkeys.delegation.grant(...)
• agentkeys.delegation.revoke(...)
• agentkeys.approval.request(...)

These ship as schema previews so vendors integrating in M1 see the full API shape; the wire format won't change when M4 lights them up. Return JSON shape: {"error": "not_implemented_in_v1", "scheduled_for": "M4", "spec_url": "https://github.com/litentry/agentKeys/blob/main/docs/spec/plans/milestones-roadmap.md#m4"}.

Stack

• Python (Anthropic mcp SDK) as fallback only
• Rust (mcp-rs) preferred
• Thin adapter layer over existing broker / signer / worker RPCs. No new backend code; the MCP server is plumbing.
• Auth: per-vendor Bearer token at the MCP transport layer + X-AgentKeys-Actor header for per-actor scoping. The header binds to a device.actor_omni for the duration of the call.

Out of scope (defer to M2+)

• Vendor onboarding portal (M2 Phase 2: Tuya Cloud Development connector #114)
• Hermes / OpenClaw as MCP tools (M3 Phase 3: Hermes-MCP server (hermes.execute_task as MCP tool) #117, Phase 3: OpenClaw-MCP server (openclaw.execute_task as MCP tool) #118)
• Active delegation + approval workflows (M4)
• Native mobile SDK (M5)
• Direct payment-cap surfacing — payment rails ship as a separate MCP namespace later

Acceptance criteria

• All 7 active tools respond correctly when invoked from a stock xiaozhi-server with this MCP server registered in mcp_server_settings.json
• All 3 schema-only tools return {"error": "not_implemented_in_v1", ...} with the documented JSON shape
• Per-vendor Bearer token auth + X-AgentKeys-Actor header per-actor scoping verified by negative test (wrong token → 401, no-header → 403, wrong actor → 403 with audit row)
• Unit tests for each tool's happy path + at least 1 negative path per tool
• Integration test against a mock backend (mock broker + signer + memory worker) exercising the three-act demo storyboard from agent-iam-strategy.md §4.3
• CI publishes the MCP server image; one-command deploy to a Volcano Ark-marketplace-compatible host
• Demo: invoke each active tool from a real xiaozhi-server session against a live broker — verify Status=Done on this issue requires the full demo, not just unit tests

Assumptions

• Phase 0 backend (broker + signer + workers + OIDC) is live and stable. If broker auth changes during M1, this server's adapter layer absorbs the change without breaking the MCP wire format.
• Namespace model (Phase 1: Memory namespace model — wire to cap-token + worker filter #108) lands before memory.get / memory.put can pass acceptance. If Phase 1: Memory namespace model — wire to cap-token + worker filter #108 slips, those tools ship as best-effort without namespace filter and Phase 1: Memory namespace model — wire to cap-token + worker filter #108 backfills.

Risks

Risk	Mitigation
Python MCP SDK lags features we need (e.g., streaming)	Identify the gap in week 1; switch to mcp-rs for the affected tool only
Vendor's MCP host interprets the tool spec differently than the spec implies	Hit both xiaozhi-server + Volcano Ark in CI; document drift per host
Per-vendor bearer auth creates a "single tenant of tenants" key-sprawl problem	Tenant tokens live in agentkeys-broker-server issuance flow; rotation policy is part of M2
The demo's three-act storyboard depends on deterministic verdicts from permission.check	permission.check is policy-engine-driven (declarative rules, NOT LLM); no inference variance possible

References

• docs/spec/plans/milestones-roadmap.md §2 (M1 scope) — operational source of truth
• docs/research/agent-iam-strategy.md §4.2 (Phase 1 MCP scope), §3.5 (namespace model), §3.1 (revocation), §4.3 (three-act demo)
• docs/research/volcano-ark-mcp-integration.md — Volcano Ark integration architecture + AgentKeys MCP tool inventory
• docs/research/xiaozhi-hermes-architecture.md — xiaozhi-server's first-class MCP support; why no bridge fork is needed
• docs/arch.md §17 (per-data-class isolation), §4 (K-key inventory) — invariants this server must not break

Effort

~1 week of focused engineering. Suggested sequencing:

1. (Day 1-2) Python MCP SDK skeleton + Bearer auth + actor scoping
2. (Day 2-3) identity.whoami + permission.check + cap.mint + cap.revoke (broker-adapter tools)
3. (Day 3-4) memory.get + memory.put (worker-adapter tools)
4. (Day 4-5) audit.append + schema-only stubs + error envelope
5. (Day 5-7) Unit tests + integration test + mock backend + CI image publish

Pickup notes for the next agent / developer

• Start by reading docs/spec/plans/milestones-roadmap.md §2 for M1 scope context
• Then docs/research/agent-iam-strategy.md §4 for the Phase 1 demo storyboard this server enables
• Existing Phase 0 backend lives in crates/agentkeys-broker-server/ + crates/agentkeys-worker-*/ — the MCP server adapts these RPCs, doesn't replace them
• For xiaozhi-server MCP integration shape: see docs/research/xiaozhi-hermes-architecture.md Diagram C (per-turn flow)
• For Volcano Ark integration shape: see docs/research/volcano-ark-mcp-integration.md Pattern B
• Watch for: permission.check returning the wrong allow/deny verdict in Act 2 of the demo breaks the demo. The verdict is deterministic — policy-engine, not LLM. If you're tempted to use an LLM here, stop and re-read agent-iam-strategy.md §2.4 (hard line: zero orchestration in v1).
• Use the /agentkeys-issue-create skill (defined in ~/.claude/skills/agentkeys-issue-create/SKILL.md) for any follow-up issues you open during this work.