Phase 7: MCP protocol extensions proposal — IAM-grade auth headers

[hanwencheng]

Context

After Phase 1-6 land + 10+ vendor deployments + multiple runtime adapters integrate, AgentKeys earns the right to engage with the MCP working group on protocol extensions. Per agent-iam-strategy.md §6 Risk 5: premature standards engagement looks like vendor lobbying. Standards work happens AFTER deployed reference implementations exist — not before.

This is the proposal phase of M7. The bet: by the time we propose X-AgentKeys-* headers as standard MCP extensions, our reference implementation has been the de-facto standard for 12+ months. The proposal codifies what already exists.

Scope (M7 — long horizon, multi-month)

Spec proposal

Headers to standardize:

• X-AgentKeys-Actor (or vendor-neutral equivalent like MCP-Actor) — per-actor scoping at the MCP transport layer
• X-AgentKeys-Cap-Token (or MCP-Cap-Token) — cap-token forwarding through MCP tool chain
• X-AgentKeys-Audit-Chain (or MCP-Audit-Chain) — chain-of-custody header for cross-MCP-server audit reconstruction

Each header gets:

• Wire format definition
• Required/optional semantics
• Security considerations (what happens when the header is missing, forged, replayed)
• Reference implementation pointer

Reference implementation

Already shipped per Phase 1 (#107). The proposal cites our MCP server's behavior as the reference; we don't write a parallel implementation.

Engagement

• Submit to MCP working group via modelcontextprotocol.io (or wherever the working group settles)
• Round-table at relevant conference (Anthropic MCP summit / similar) — present the deployed-implementation case
• Iterate based on working-group feedback (expect 6-12 months of iteration)

Adoption signal

• 2+ third-party MCP servers cite the reference implementation
• 1+ major MCP host (Claude Code, Cursor, Continue.dev) signals interest in adopting the headers natively

Precondition (HARD)

Do not start until ALL of these are true:

• Phase 1-6 (M1-M6) all shipped and stable in production
• 10+ vendor deployments live (not pilots)
• Multiple runtime adapter integrations (Hermes, OpenClaw, Doubao, others) in active use
• AgentKeys' MCP server has been live + deployed at scale for ≥ 12 months

If any precondition fails, this issue stays open and untouched until they're all met. Don't compromise — premature standards engagement is the #5 risk; do not own this risk-incident by shipping early.

Out of scope (forever)

• AgentKeys-specific branding in the spec — the headers must be vendor-neutral
• Proprietary extensions that only our server implements (defeats the purpose of standards)
• Charging for the spec or the reference implementation — open standards mean open

Acceptance criteria

• Draft spec proposal published as a public document (markdown in our repo + submitted to MCP working group's process)
• Working group feedback incorporated through at least 2 revision rounds
• Reference implementation cited by at least 2 third-party MCP servers (proof of adoption beyond our own)
• At least one major MCP host has internally tested our reference implementation against their existing flows
• Spec progressed to the MCP working group's "Draft Standard" or equivalent state

Risks

Risk	Mitigation
Working group rejects the proposal entirely	Be prepared for that — our reference impl still works as a vendor-specific extension; standards adoption is a bonus, not the goal
Spec evolves in directions that break our reference impl	Document the divergence; commit to either updating our impl or maintaining a vendor-specific variant
Standards engagement diverts attention from M5/M6 hardening	M7 is multi-month standards work in parallel to ongoing product; budget a fixed time slice (10-20% of one senior eng's time, NOT a full team)

References

• docs/spec/plans/milestones-roadmap.md §8 (M7 scope) + §9 (post-M7 horizons)
• docs/research/agent-iam-strategy.md §5 Phase 5, §6 Risk 5 (premature standards work)
• Model Context Protocol spec
• Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107 (reference implementation — already shipped; this issue cites it)
• Phase 7: OAuth-for-Agents specification engagement #125 (OAuth-for-Agents — sibling standards work)

Effort

N/A on the engineering side — multi-month standards work. Per the strategy doc: 10-20% of one senior eng's time, sustained over 6-12 months. Most of the work is writing, presenting, and iterating with the working group.

Pickup notes for the next agent / human

• This is a standards engagement issue, not an engineering issue. The "next agent" here is whoever owns external standards work (likely a senior eng + ops support).
• Do not start until preconditions met. Re-check the precondition list quarterly; mark this issue blocked-by until conditions hold.
• Read milestones-roadmap.md §8 for M7 framing + agent-iam-strategy.md §6 Risk 5 for why premature standards is risky
• The reference implementation already exists. Don't reinvent it for this issue; cite the deployed code.
• Strong norm: deployed code first, spec second. Standards bodies trust deployed reference implementations over slide decks. Show, don't tell.
• For working-group engagement: be a participant, not a vendor lobbyist. The framing is "here's what's working in production; standardizing it benefits the whole ecosystem" — not "we want our proprietary thing to be the standard."