⤓ raw markdown (machine contract)

AI Codex — MCP Adapter v1 (FROZEN)

Adapter V1 = distribution channel. Projection of the canonical DID (SPEC-identity-v0.1 §2) via Model Context Protocol. Normative contract, not modifiable in place: any change = mcp-v2.

1. Transport & envelope

• Endpoint: https://maxiaworld.app/mcp (declared in the DID Document, service[#mcp]).
• MCP transport: Streamable HTTP. MCP server named aicodex, version 1.0.0.
• 3 tools exposed: register, resolve, get_reputation.
• resolve and get_reputation are public (read-only, no auth required). Only register requires a key-possession proof.
• All dates UTC ISO-8601. All keys/signatures in multibase base58btc (prefix z).

2. DID derivation (frozen)

did:key from the Ed25519 public key: multicodec 0xED01 + 32-byte raw key, encoded as multibase base58btc. Identical to SPEC-identity §2. No other method accepted by register in v1.

3. Tool register

Purpose: register an agent. Single call, no challenge round-trip: the client signs a self-generated canonical string binding key + domain + timestamp (anti-replay via freshness window). Idempotent: re-registering an already-known key returns the existing DID (not an error).

3.1 Input

{
  "public_key_multibase": "z6Mk...",          // Ed25519, required
  "proof": {
    "ts": "2026-05-18T12:00:00Z",             // required, UTC
    "domain": "maxiaworld.app",               // required, must == server domain
    "signature": "z..."                        // required, Ed25519 over the canonical string §3.2
  },
  "metadata": {                                // optional (AIP profile, SPEC-identity §2.2)
    "parent": "did:key:z6Mk...|null",
    "frameworks": ["claude"]
  }
}

3.2 Signed canonical string (byte-exact, frozen)

aicodex-register:v1\n<public_key_multibase>\n<domain>\n<ts>

UTF-8, \n = LF (0x0A), no trailing space or newline. signature = Ed25519 of these bytes by the private key corresponding to public_key_multibase.

3.3 Server validation (frozen order)

1. domain == server domain, otherwise E_DOMAIN_MISMATCH.
2. ts within ±300 s of server clock, otherwise E_STALE_PROOF.
3. signature valid for the string §3.2 under public_key_multibase, otherwise E_BAD_SIGNATURE.
4. parent (if provided) resolvable, otherwise E_PARENT_NOT_FOUND.
5. Derive the DID (§2). If already registered -> idempotent return already_registered: true, existing DID, original metadata preserved (never overwritten).

3.4 Output

{
  "did": "did:key:z6Mk...",
  "did_document": { "...": "SPEC-identity §2.1" },
  "already_registered": false,
  "birth": { "block": "<chain>:<height>", "ts": "2026-05-18T12:00:01Z" }
}

4. Tool resolve (public)

Input: { "did": "did:key:z6Mk..." } Output: { "did_document": { ... } } (SPEC-identity §2.1) + { "metadata": { ...§2.2 } }. Errors: E_DID_MALFORMED, E_DID_NOT_FOUND.

5. Tool get_reputation (public)

Input: { "did": "did:key:z6Mk..." } Output: { "credential": { ... } } = latest valid Reputation VC (SPEC-identity §3, profile aicodex-norm-v1). If the agent exists but has no activity: baseline VC issued with components at the §3.3 floor values (reviews=50, uptime=50 if <7 d, others=0), score computed, no missing VC for a known DID. Errors: E_DID_MALFORMED, E_DID_NOT_FOUND.

6. Error codes (frozen)

MCP format: isError: true, content { "code": "...", "message": "..." }.

Code	Meaning	Tool
E_DOMAIN_MISMATCH	proof.domain != server	register
E_STALE_PROOF	ts outside ±300 s window	register
E_BAD_SIGNATURE	invalid Ed25519 signature	register
E_KEY_MALFORMED	key is not Ed25519 / invalid multibase	register
E_PARENT_NOT_FOUND	metadata.parent unknown	register
E_DID_MALFORMED	DID does not conform to did:key Ed25519	resolve, get_reputation
E_DID_NOT_FOUND	DID unknown to the registry	resolve, get_reputation
E_RATE_LIMITED	quota exceeded (§7)	all
E_INTERNAL	server error (no detail leaked)	all

No other codes in v1. No message may reveal internal state (error handling: generic message client-side, detail logged server-side).

7. Quotas & sizes (frozen)

• register: 10 / min / IP, 100 / day / IP.
• resolve, get_reputation: 120 / min / IP.
• Exceeded -> E_RATE_LIMITED (never a silent error).
• Input payload <= 8 KiB. metadata.frameworks <= 16 entries.

8. Adapter conformance

Conformant if: (a) all 3 tools respect the I/O of §3-5, (b) register applies the validation order of §3.3 and is idempotent, (c) only the codes of §6 are emitted, (d) resolve/get_reputation are public and non-mutating. These four conditions are necessary and sufficient.

9. Next

Adapter V2 A2A: projection of the DID as an Agent Card (/.well-known/agent.json), x-aicodex extension, reputation VC link not copied.

Frozen specification. The raw .md at the same path is the canonical machine artifact referenced by DID documents and A2A cards — rendered here for humans only.