MCPIP Documentation

TOKEN=$(curl -s localhost:8080/v1/dev/token \
  -H 'content-type: application/json' -d '{}' | jq -r .jwt)

Authorization: Bearer <jwt>     # never a URL, never a query string, never a log line

In production a real agent token is issued out-of-band by your IdP (the analog of /v1/dev/token is scripts/mint_principal.py, signed with your IdP key). Confirm what a token actually carries with GET /v1/whoami — it echoes the verified tenant, agent, compartment, and effective capabilities, so you never have to diagnose entitlements through opaque denies.

{
  "correlation_id": "…",
  "decision": "allow",
  "status": "committed",
  "transaction_ref": "txn_…",
  "executed_target_class": "cloud_rest",   // coarse CLASS, never the real target
  "worm_sequence": 4213
  // "vended_credential": {…}  present ONLY for a cloud_iam skill
}

{
  "correlation_id": "…",
  "action_required": "approve in the enrolled authenticator",
  "challenge_id": "…",          // the payload-bound lock id (step 05)
  "risk_tier": "pin_required"
}

{ "error": "MCPIP: request denied by policy.", "correlation_id": "…" }

Need only a verdict, not execution? POST /v1/authz/decision answers as an OpenID-AuthZEN PDP — { decision: bool } — and never executes, vends, or stages.

OTP=$(curl -s localhost:8080/v1/authenticator/$CHALLENGE_ID \
  -H "authorization: Bearer $TOKEN" | jq -r .otp)   # sandbox peek

curl -s localhost:8080/v1/authorize -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d "{
  \"source_format\":\"openai_tool_call\",
  \"tool_call\":{ …the SAME envelope… },
  \"pin\":\"$OTP\", \"challenge_id\":\"$CHALLENGE_ID\"}"
# → 200 ExecutionReceipt. Replay the spent triple → 403 (consumed exactly once).

result = client.authorize("skill_financial_ledger_post", {"amount_cents": 2418000})
if result.is_staged:                       # 202 — a challenge_id came back
    receipt = client.complete(result, pin=one_time_code)   # same payload + pin → 200

The PIN is bound to sha256(canonical_json(tenant, agent, alias, arguments)) and consumed by a single atomic Redis operation — one byte of drift is payload_mismatch, and the lock survives a correct retry. In production the human who reads the delivered code proves possession of a per-user RFC 6238 TOTP authenticator (POST /v1/authenticator/reveal) — the human 2FA that gates reading the code, distinct from the payload-bound PIN itself.

In the SDK the receipt is a frozen result object — read correlation_id, transaction_ref, and worm_sequence directly; a cloud_iam receipt also carries vended_credential.

The reason your call was denied is real and recorded — it just lives operator-side. The full deny-reason taxonomy (WORM-only) is in the reference; an operator resolves your correlation_id against it.

# verify the signed release manifest + every listed artifact on disk
mcpip verify --manifest release/manifest.json \
  --pubkey release/keys/release_root_ed25519.pub.pem --base-dir .

# independently re-verify the tamper-evident WORM chain (Merkle + Ed25519)
mcpip export-audit --redis-url "$MCPIP_REDIS_URL" --out audit_export.jsonl --verify

The same integrity manifest is re-hashed at boot: the running process re-checks every shipped source file against MCPIP_INTEGRITY_MANIFEST_PATH before a socket is bound, and refuses to start on any mismatch. There is no self-update and no self-heal — an upgrade is a signed redeploy by immutable digest.

You generate two Ed25519 keypairs the vendor never holds (scripts/provision_gateway_keys.py): a WORM epoch-signing key (MCPIP_WORM_SIGNING_KEY_PATH, gateway-held) and your IdP’s public key (MCPIP_JWT_PUBLIC_KEY_PATH, verify-only — the IdP private key never touches the gateway). The signed license (gen_license.py) and the release/license-root public keys round out the set. The complete boot surface is the environment variable reference.

python scripts/provision_gateway_keys.py --keys-dir <offline> --public-dir <staging>
#  worm_signing_ed25519.key  -> MCPIP_WORM_SIGNING_KEY_PATH  (private, gateway-held)
#  worm_signing_ed25519.pub  -> auditors  (mcpip export-audit --verify --pubkey ...)
#  idp_signing_ed25519.key   -> your token minter / KMS  (NEVER the gateway)
#  idp_signing_ed25519.pub   -> MCPIP_JWT_PUBLIC_KEY_PATH  (public, gateway verifies)

# place the SIX files in ./secrets (never commit): the IdP public key, the WORM
# signing key, license.json, integrity_manifest.json, and the release/license
# root public keys. Then:
docker compose -f docker-compose.prod.yml up --build
curl -s http://localhost:8080/healthz     # {"status":"live","glyph":"◐",...}
curl -s http://localhost:8080/readyz      # {"status":"ready","redis":"up"}

# for a sandbox eval instead: the one-command ./scripts/quickstart_demo.sh, or the
# manual bring-up below

python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
redis-server --port 63790 --daemonize yes --appendonly yes --appendfsync always
MCPIP_SANDBOX_MODE=true MCPIP_REDIS_URL=redis://localhost:63790/0 \
  .venv/bin/python -m uvicorn app.main:app --port 8080 &
curl -s http://localhost:8080/healthz      # {"status":"live","version":"3.0.0"}
curl -s http://localhost:8080/readyz       # {"redis":"up"}

With the gateway up in sandbox mode, connect an agent and run the governed calls from Get started (the CLI tab): the verified connect → authorize → step-up → sandbox audit verify sequence. Production drops sandbox mode and swaps the dev-token minter for your IdP (scripts/mint_principal.py).

curl -s localhost:8080/v1/admin/users/invite -H "authorization: Bearer $ADMIN" \
  -H 'content-type: application/json' -d '{"email":"ops@acme.example","role":"member"}'
# → 201 {"user":{...},"invite_token":"…once…"}

# 1) begin — returns { secret, provisioning_uri (otpauth://), digits, period_s } ONCE
curl -s -X POST localhost:8080/v1/authenticator/enroll -H "authorization: Bearer $JWT"
# 2) confirm a live code from the app → activates the enrollment
curl -s -X POST localhost:8080/v1/authenticator/enroll/confirm \
  -H "authorization: Bearer $JWT" -H 'content-type: application/json' -d '{"code":"123456"}'
# → {"enrolled":true}

Agent identities are minted by your IdP, not MCPIP — the production analog of the sandbox minter is scripts/mint_principal.py, scoping an agent to a tenant plus capability/compartment entitlements the gateway enforces.

The durable audit record is the Redis-backed, signed Merkle-epoch WORM chain — written before dispatch — not a stdout log line. Every protected request lands as one of three decisions with a WORM-only reason code; the full taxonomy is the WORM decision reference. Structured JSON logs still go to stderr for your SIEM, but the WORM ledger is the authoritative evidence.

Deploy by image.digest, never a mutable tag — chart/ (Helm) or k8s/ (plain manifests) for a cluster, docker-compose.prod.yml for single host. The chart runs ≥2 replicas behind a PodDisruptionBudget with a default-deny NetworkPolicy and an internal-only durable Redis. An upgrade is a verified redeploy of a new digest; roll back by redeploying the previous verified digest. Because replicas share the same Redis WORM buffer and durable anchor, the audit chain stays continuous — no lost or duplicated evidence.

/healthz reports the running version — confirm it before admitting traffic. TLS is terminated upstream, so there is no in-process certificate to validate here.