Keel MCP ingress — local release candidate

This unreleased package exposes operator-enrolled, schema-verified managed MCP tools over standard MCP stdio. It delegates every call to the existing Keel managed-MCP API. Listing a tool grants no authority. This candidate is not available from a public package registry yet.

Prerequisites

Use a Keel project with the required plan, active policies, and upstream MCP servers enrolled by the Keel operator. Server registration and discovery alone do not confer trust. Custom/unmapped servers are not exposed by this initial catalog. Initial catalog reads are bounded to 100 enabled servers and 1000 accepted tool contracts per project; larger catalogs return a clear refusal rather than silently dropping tools. Use managed MCP directly for larger catalogs. Starter cannot positively authorize arbitrary non-payment MCP calls.

Obtain a live agent-bound Client key: an owner creates an Admin key; the Admin creates an AgentPrincipal (POST /v1/principals) and a Client key bound to its agent_principal_id (POST /v1/api-keys). Keep the Admin/owner and upstream credentials outside the agent. An ordinary project Runtime/service key has no agent binding and cannot use this execution path. Upstream secrets stay in Keel.

Install the provided candidate wheel in a new Python environment:

python3 -m venv .venv
.venv/bin/python -m pip install /path/to/keel_mcp_ingress-0.1.0-py3-none-any.whl

Configure any MCP stdio client (including Claude-compatible clients):

{
  "mcpServers": {
    "keel": {
      "command": "/absolute/path/to/.venv/bin/keel-mcp",
      "env": {
        "KEEL_BASE_URL": "https://api.keelapi.com",
        "KEEL_API_KEY": "YOUR_AGENT_BOUND_CLIENT_KEY",
        "KEEL_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}

The candidate requires the matching local API candidate with /v1/mcp/runtime-tools; it is not a claim that the production API supports this unreleased ingress. Use the provided isolated candidate URL during certification. HTTPS is required; HTTP is accepted only for an isolated loopback runtime. Project identity is checked against the key. The ingress supplies required per-request freshness headers without exemptions.

Calls and outcomes

Use tools/list. Tool names are stable opaque aliases; descriptions identify the upstream server/tool. Supply the original upstream arguments under the arguments field and a caller-generated idempotency_key. Keep that key and the exact arguments for the whole intended request. Nested argument content is forwarded unchanged. Expired, drifted or disabled contracts disappear from the catalog; existing API admission remains the final authority.

tools/call returns the existing API response under response, plus keel_http_status, idempotency_key, and, when Keel names it, the permit_id used to find the call's signed evidence. It marks refusals/failures as MCP isError. ALLOW dispatches only through existing admission. DENY, unapproved REVIEW and THROTTLE cause zero managed dispatch. For REVIEW, the owner approves the returned Permit through the dashboard; retry the exact arguments and key. Approval itself never dispatches. Changed arguments and authority cannot reuse approval. A new key requests new authority; it does not reuse an approval.

For an unknown outcome or lost Keel response, reconcile using the original key and downstream records. Do not generate a new key to retry a possibly completed effect. The gateway does not retry automatically. Invalid input is refused.

Permit, dispatch, receipt and closure evidence use existing Keel export and proof-pack APIs and the verifier. A successful MCP result is not itself signed proof of an external state change. Distinguish authorization, Keel dispatch, provider receipt, provider execution and independently observed external state. Checkpoint publication remains PAUSED; this ingress does not resume it.

This initial ingress supports initialization, tool listing/calling and stdio session cleanup. It does not add a policy engine, approval path, provider credential delegation, remote OAuth service or unrelated MCP features. A model Permit still does not authorize host-executed tools outside this managed boundary.