Docs Connect

Keep tool keys out of KIFF

Choose who holds a connected tool’s key: KIFF, nobody, or your own relay. For owners of a tool connected through the MCP gateway who don’t want KIFF to hold its key. Switch the connection to verify or relay and check KIFF’s permit before the tool acts.

Mode Who holds the tool’s key What KIFF sends the tool
sealed (the default) KIFF, stored encrypted the call and the stored credential
verify nobody: the tool checks KIFF itself the call and an execution permit
relay your relay, from your own vault the call and an execution permit

The execution permit

For each allowed call, KIFF sends a permit in the KIFF-Permit header: a 60-second Ed25519 JWT (typ: kiff-permit+jwt) naming the account, the connection’s audience, the tool, a hash of the exact arguments, the operation id, the agent and the Card. Keys are published at https://api.kiff.dev/.well-known/kiff-permit-keys.json.

Verify mode: the tool checks the permit

For a tool you run. Check the permit before the tool does anything:

pip install "kiff-guard[verifier]"
from kiff_guard.permit import JWKSKeys, SQLiteStore, Verifier

verifier = Verifier(
    issuer="https://api.kiff.dev",
    audience="https://refunds.example.com/mcp",  # the connection's audience
    tenant="<your KIFF account id>",
    keys=JWKSKeys(),
    store=SQLiteStore("/var/lib/refunds/permits.db"),
)

outcome = verifier.run(headers["KIFF-Permit"], "refund_order", arguments, adapter)

adapter makes the one downstream call (execute) and finds its result again (lookup). The verifier refuses a permit that is not KIFF’s, not for this tool, audience and arguments, or expired, and runs each operation at most once. Run verifier.sweep(...) at start-up and periodically; verifier.unknown() lists what a person must check.

Relay mode: your relay holds the key

For a service that won’t check KIFF’s permit. Run kiff_guard.permit.relay.Relay next to your vault: it verifies the permit, then makes the one call with your key.

Moving a connection

Under Connected tools, choose Change who holds the key. Over the API:

curl -s -X PUT https://mcp.kiff.dev/v1/connections/refund_order/mode \
  -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "verify", "audience": "https://refunds.example.com/mcp"}'

Moving to verify deletes the credential KIFF held. A verify or relay connection needs an idempotency argument.

When revoking or expiring a Card takes effect

KIFF checks the Card at every call, so no new call is allowed once a Card is revoked or expired. A call allowed just before can still start: in sealed mode if it is already on its way, and in verify or relay mode for up to 90 seconds (the permit’s 60 seconds plus 30 seconds of clock tolerance). Nothing undoes a call already sent.