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.

# Stage a step-up first — this is what produces CHALLENGE_ID. skill_email_send is
# pin_required, so it answers 202 rather than the 200 the step 03 example returns.
CHALLENGE_ID=$(curl -s localhost:8080/v1/authorize -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{
  "source_format":"openai_tool_call",
  "tool_call":{"id":"c1","type":"function","function":{"name":"skill_email_send",
    "arguments":"{\"to\":\"board@mcpip-inc.example\",\"subject\":\"Q3 report\"}"}}}' \
  | jq -r .challenge_id)

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).

from mcpip_sdk import Staged

# skill_email_send is pin_required AND visible to the token minted in step 02.
result = client.authorize("skill_email_send",
                          {"to": "board@mcpip-inc.example", "subject": "Q3 report"})

# authorize() returns Allowed | Staged — branch on the type, which is the SDK's
# actual contract. There is no .is_staged attribute.
if isinstance(result, Staged):             # 202 — result.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.

Two different packages install a command called mcpip. sdk/python — the one install.sh and the quickstart give you — provides the agent CLI (login, authorize, catalog…). The root package provides the release verifier. Running mcpip verify against the SDK CLI fails with invalid choice: 'verify' and exit 2, so the commands below use python -m mcpip_verify.cli, which is unambiguous whichever mcpip is on your PATH.

# from a checkout — unambiguous regardless of which mcpip is on PATH
python -m mcpip_verify.cli 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)
python -m mcpip_verify.cli export-audit \
  --redis-url "$MCPIP_REDIS_URL" --out audit_export.jsonl \
  --verify --pubkey worm_signing_ed25519.pub.pem

# --base-dir must hold the artifacts the manifest lists. The wheel and sdist are
# release assets, not committed, so a bare checkout exits 2 on their absence.

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  (python -m mcpip_verify.cli 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 a .env beside the compose file — it hard-requires both
# of these and refuses to interpolate without them (compose fails before any
# container starts, naming the missing variable):
printf 'MCPIP_JWT_ISSUER=https://idp.example.com/
MCPIP_JWT_AUDIENCE=mcpip-gw.example
' > .env

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.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…"}

# list the roster
curl -s localhost:8080/v1/admin/users -H "authorization: Bearer $ADMIN"

# change a role, or disable without deleting (at least one field required)
curl -s -X PUT localhost:8080/v1/admin/users/ops@acme.example \
  -H "authorization: Bearer $ADMIN" -H 'content-type: application/json' \
  -d '{"status":"disabled"}'

# remove the record entirely
curl -s -X DELETE localhost:8080/v1/admin/users/ops@acme.example \
  -H "authorization: Bearer $ADMIN"

# 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.

That placement is the whole design. The console talks to the same admin endpoints you can curl, over the same CAP_DIRECTORY_ADMIN credential, and renders the WORM projection the gateway wrote before dispatch. There is no console database and no second source of truth: if the console and the ledger ever disagreed, the ledger is right and the console has a bug.

cd dashboard
npm install
npm run dev            # http://localhost:5173

# then set the gateway endpoint in the UI, or pre-pin it:
#   localStorage['mcpip.gateway.base'] = 'https://mcpip.internal:8080'

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.

# The blocks below read these. Set them once:
export MCPIP_URL=http://localhost:8080
export MCPIP_TOKEN=$(cat /tmp/admin.jwt)   # CAP_DIRECTORY_ADMIN — see Administer → Register skills

# NOT every block below uses that one token. The capabilities are disjoint by design —
# neither contains the other — so a forensic read with the admin token is a 403, and an
# attestation read with the forensic token is a 403. Mint the second when you reach it:
#   mcpip sandbox capabilities                       # the UUIDs, by name
#   mcpip sandbox dev-token --agent auditor \
#     --cap d5f0c9a2-4b71-4e6a-9c83-1a7f2e6b4d90     # CAP_FORENSIC_READ

curl -sS "$MCPIP_URL/v1/audit/attestation" \
  -H "Authorization: Bearer $MCPIP_TOKEN" | jq

Do not poll this. It runs a full verify_chain— re-hashing every epoch, recomputing every Merkle root, checking every Ed25519 signature. That is CPU-bound work on the event loop: four concurrent readers were measured moving authorize p50 from 8.2 ms to 260 ms. Run it on a schedule, off-peak, or against a replica.

python -m mcpip_verify.cli export-audit \
  --redis-url "$MCPIP_REDIS_URL" --out audit_export.jsonl \
  --verify --pubkey worm_signing_ed25519.pub.pem --require-anchor

It runs the same five checks the gateway runs: chain linkage (monotonic epochs, contiguous seq), Merkle roots cross-checked against stored leaf hashes, epoch_hash recomputation, the Ed25519 epoch signature, and the out-of-tamper-domain anchor low-watermark that catches rollback and truncation. It fails closed on a missing key, an unparseable header, or a partially deleted epoch — and names which check failed and the first bad epoch.

curl -sS "$MCPIP_URL/v1/admin/forensic/$CORRELATION_ID" \
  -H "Authorization: Bearer $MCPIP_TOKEN"

A 404 here is not a refusal — it means you are authorized and no capture exists for that id. An authorized-but-empty lookup stays distinguishable from a capability denial (403), which matters when the question is “was there evidence?” rather than “may I ask?”

python scripts/soc2_report.py --gateway "$MCPIP_URL" \
  --token-file operator.jwt --from-ms "$START" --to-ms "$END" > report.md

Two things the report states rather than glosses. It only claims the window was fully walked when the gateway asserted exhausted; anything else reads as a lower bound. And the decision history is a bounded scan over a trimmed buffer — if the period starts before the retention horizon, the report says partially retained and names the signed epoch chain as the record for the missing span.

curl -sS "$MCPIP_URL/v1/authz/decision" \
  -H "Authorization: Bearer $MCPIP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"subject":{"type":"agent","id":"agent-eng-1"},
       "action":{"name":"invoke"},
       "resource":{"type":"skill","id":"skill_company_overview"}}'

# -> {"decision": true}

The verdict carries no reason. { decision: bool } and nothing else — thresholded as an invariant, because a PDP response that explained itself would be an oracle for probing the policy surface from outside the tenant. At 5 output tokens it is also the cheapest surface on the gateway.

curl -sS "$MCPIP_URL/v1/admin/extensions/pending" \
  -H "Authorization: Bearer $MCPIP_TOKEN"

This is the clearest demonstration that MCPIP has no super-admin. The operator — the most privileged human persona — is 403 on this route, and the reviewer is 403 on everything the operator holds. Neither capability subsumes the other.

That separation is the point: registering an alias (operator) and approving a new catalog surface (reviewer) are the two ways the reachable-target set can grow, and they deliberately require two different identities.