Skip to main content

mcpip-sdk (Python)

Typed Python client for the MCPIP authorization gateway — authorize every AI action before execution.

  • Import package: mcpip_sdk · distribution: mcpip-sdk
  • Python ≥ 3.10 · single runtime dependency: httpx (plus tomli only on the 3.10 CLI floor, where stdlib tomllib does not yet exist)
  • Fully typed (py.typed), mypy --strict-clean, frozen-dataclass wire models (no pydantic — the SDK never collides with your agent framework's pin)
  • Ships the mcpip CLI on your PATH (see below)
pipx install ./sdk/python       # isolated install, `mcpip` on PATH (recommended)
pip  install ./sdk/python       # into the active environment
pipx install mcpip-sdk          # once published to PyPI

# Homebrew (works TODAY from git, no published release needed):
brew install --HEAD mcpip/tap/mcpip
# after a tagged release: brew tap mcpip/tap && brew install mcpip

Quickstart (sandbox)

Run a sandbox gateway (MCPIP_SANDBOX_MODE=true uvicorn app.main:app --port 8080, Redis on :63790), then:

from mcpip_sdk import Allowed, MCPIPDenied, SandboxClient, Staged

with SandboxClient("http://localhost:8080") as client:
    # SANDBOX ONLY: mint a demo identity. Production tokens come from YOUR IdP.
    client.set_token(lambda: client.dev_token(agent_id="agent-quickstart"))

    print([item.alias for item in client.catalog()])   # metadata, never targets

    outcome = client.authorize("skill_spend_summary", {"period": "2026-Q2"})
    assert isinstance(outcome, Allowed)
    print(outcome.transaction_ref, outcome.worm_sequence)

sdk/python/examples/quickstart.py is the runnable version of the above.

The mcpip CLI — zero to authorized in three commands

Installing the SDK also installs the mcpip command (argparse, no new dependency). It wraps the very same typed clients — nothing is reimplemented — and inherits the gateway's discipline: a deny prints only a correlation id, secrets never touch stdout/argv/logs, and exit codes are stable for scripts.

# 1) point at a gateway and save a named context (mints NO token)
mcpip login --gateway http://localhost:8080 --sandbox --context sbx

# 2) SANDBOX ONLY: mint a demo identity straight into the 0600 token store
#    (the JWT is never printed). Production tokens come from YOUR IdP —
#    supply them via MCPIP_TOKEN, --token-file, or --token-cmd, never argv.
mcpip --context sbx sandbox dev-token --agent agent-quickstart

# 3) authorize one tool call through the choke point
mcpip --context sbx authorize skill_spend_summary --arg period=2026-Q2

Everything scripts: --json emits the typed model, --quiet prints only the load-bearing id, a deny exits 3 with just {"error":"denied","correlation_id":…}. The step-up ceremony works headless too — a non-interactive authorize on a pin_required alias persists the exact envelope and exits 9; resume with mcpip complete --challenge <id> (OTP via --otp-stdin or an interactive no-echo prompt, never argv). Full reference: docs/start/CLI.md.

The three clients

Client Surface
MCPIPClient Agent surface: authorize, complete, catalog, mcp_call (JSON-RPC 2.0 on /v1/mcp), health, ready, version, license, audit_attestation (production-available signed audit snapshot), authz_decision (OpenID-AuthZEN / COAZ pre-execution PDP verdict), protected_resource_metadata (public OAuth 2.1 RS discovery, RFC 9728 — no token)
SandboxClient MCPIPClient + sandbox-only: dev_token, authenticator_code, audit_verify, audit_proof — each answers 404 on production gateways by design
MCPIPAdminClient CAP_DIRECTORY_ADMIN control plane: skills, principals, decisions_recent, directory (incl. directory_relations, the ReBAC Knowledge-Graph read), workspace plans, cloud environments, vault secrets, quarantine(), canaries(), compliance_evidence (portable evidence bundle — evidence, never a certification); forensic_get (distinct CAP_FORENSIC_READ); community-extension review extensions_pending / extension_approve / extension_reject + registry-governance verified_publishers_get / verified_publishers_put (distinct CAP_CATALOG_REVIEWER) + Contributor extension_submit (no capability)

The PIN ceremony (step-up)

A pin_required alias never executes on the first call. The gateway stages a payload-bound, one-time lock and the approval code travels out-of-band:

staged = client.authorize("skill_payroll_run", {"run_id": "PR-7"})
if isinstance(staged, Staged):                       # HTTP 202 — a RESULT, not an error
    pin = client.authenticator_code(staged.challenge_id)  # sandbox stand-in for the
                                                          # enrolled authenticator
    receipt = client.complete(staged, pin)           # resubmits the IDENTICAL payload

Rules the gateway enforces (and the SDK is built around):

  • The lock binds (tenant, agent, alias, arguments). complete() resends the exact envelope kept on staged.envelope — any argument drift is an opaque deny (the lock survives for a correct retry).
  • The lock lives staged.expires_in seconds (300), allows 5 wrong-PIN attempts, and is consumed exactly once — replays deny.
  • The OTP is never in the 202 and never in any log. In production it reaches the approver's enrolled authenticator; model acquisition as your own callback, with authenticator_code as the sandbox default.
  • A step-up staged on the MCP edge (tools/call → isError result with a challenge_id) completes on /v1/authorize: client.authorize(tool_call=<same JSON-RPC dict>, source_format="mcp_jsonrpc", pin=..., challenge_id=...) — the lock is format-independent.

Denials are opaque — by design

Every policy deny raises MCPIPDenied carrying only correlation_id (and the HTTP status). No reason ever crosses the agent boundary; the concrete cause lives in the gateway's WORM audit log, where an operator resolves it by that id (MCPIPAdminClient.decisions_recent shows it operator-side).

Never retry a denied call. Token expiry and policy denials are indistinguishable on the wire, and a retried step-up consume is itself a real deny that double-counts audit events. The SDK never retries anything for you.

Tokens in production

The gateway verifies JWTs; it never mints them. Your IdP does (EdDSA or RS256; 8 required claims — see scripts/mint_principal.py in the gateway repo for the reference minter, including capabilities for admin clients).

# Static (externally rotated):
client = MCPIPClient("https://gateway.example", token=os.environ["MCPIP_TOKEN"])

# Callback (your IdP/STS integration) — invoked lazily, cached, and refreshed
# proactively ~30s before the token's own exp; NEVER refreshed on a deny:
client = MCPIPClient("https://gateway.example", token=fetch_token_from_idp)

dev_token is a sandbox convenience only; it raises MCPIPSandboxOnly where /v1/dev/token does not exist (production — identity stays IdP-sovereign).

Errors

Exception Meaning
MCPIPDenied(correlation_id, http_status) Policy deny — opaque, final, never retry
MCPIPInvalidRequest Malformed/oversized envelope (422/413, JSON-RPC -327xx/-32601)
MCPIPUnavailable(retry_after) Unreachable / timed out / shedding (503)
MCPIPNotFound Unknown challenge/event on a live endpoint
MCPIPSandboxOnly Sandbox-only endpoint called against production

There is deliberately no MCPIPStaged exception — a staged step-up is a successful Staged result.

Full documentation for both SDKs (Python and TypeScript): docs/start/SDK.md in the gateway repository.

Metadata

Release files for mcpip-sdk 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcpip-sdk 0.1.0
File Size Uploaded Provenance Actions
mcpip_sdk-0.1.0.tar.gz 112.4 kB Without provenance Details for mcpip_sdk-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcpip-sdk 0.1.0
File Interpreter ABI Platform Actions
mcpip_sdk-0.1.0-py3-none-any.whl Python 3 none any Details for mcpip_sdk-0.1.0-py3-none-any.whl

Total release size: 236.2 kB

Release files / mcpip_sdk-0.1.0.tar.gz

Download URL mcpip_sdk-0.1.0.tar.gz
Size 112.4 kB
Tags Source
SHA-256 checksum
How to use checksums
64e73ecadcdbee813e6112b3583d340c128cdb6f41c69adcc0fb9915caaa16a1
BLAKE2b-256 checksum
How to use checksums
67a1caf51d421cc1f091d07b75dd0cb3eec4d49df8dad4a9aff2a7618ec01804
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / mcpip_sdk-0.1.0-py3-none-any.whl

Download URL mcpip_sdk-0.1.0-py3-none-any.whl
Size 123.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
56ba96288d599220ac86db7760256dc7b0aaa26cafe10a3c7bf1f00469a47a9d
BLAKE2b-256 checksum
How to use checksums
22a8354e328a41d24e3f494e20847560889728ab251e3f426c28e23dee1b439c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.13

Security for mcpip-sdk 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page