Credential Broker

Credential Broker MCP

A local-first MCP server that lets AI agents use gated APIs without ever holding the keys.

The agent asks the broker to make a request. The broker canonicalises the URL, checks a declarative per-operation policy, verifies any required approval at execution time, injects the secret at the last moment, calls the upstream, redacts and filters the response, and writes a content-free audit record. The secret lives with the broker process and is never relayed to the agent in any representation the broker creates: raw, Base64, base64url, percent-encoded, form-encoded, or Unicode-normalised. An upstream that transforms a secret with a one-way function of its own defeats string matching; scoped operations and metadata-only responses are the defence there, and SECURITY.md states this boundary honestly.

Early release (0.x). Published to npm with provenance from GitHub

Actions. Expect the policy format and tools to change before 1.0.

Five-minute quickstart

Needs Node 22 or 24. Keys are stored in the OS keychain: Windows Credential Manager, the macOS login keychain, or the Secret Service on Linux (GNOME Keyring or KWallet through secret-tool). Without one, set each credential's env_var instead.

1. Open the key manager. It prints a local link and opens it in your browser.

   npx -y -p @sarutobi-sasuke/credential-broker-mcp credential-broker-keys

Run through npx, the policy, audit log and approvals live in ~/.credential-broker (%USERPROFILE%\.credential-broker on Windows), so they survive npm cache clean-ups and upgrades. Set BROKER_HOME, or BROKER_POLICY_FILE, BROKER_AUDIT_FILE and BROKER_APPROVALS_FILE, to put them somewhere else. From a clone of this repo, run npm ci then npm run keys; the files then stay in the checkout.

1. Add one key. Open New key. Use the short name github, base URL https://api.github.com, paste a token, tick the agent that may use it (or add an identity such as codex), then press Add key. The key goes into your OS keychain and the policy file gets a read-only grant. Press Test on the card to prove the key works.

1. Connect your MCP client. Go to Settings → Connect an MCP client, select Codex or Claude Code, then pick the agent. For Codex, paste the copied TOML into ~/.codex/config.toml or update the existing credential-broker entry. For Claude Code, run the copied command. Restart your client. Both options use local stdio and require Node on PATH. The Codex configuration also applies to local sessions in the ChatGPT desktop app on the same host. If you use environment-backed credentials, list the variable names in env_vars under the Codex server table. See the Codex MCP configuration guide.

1. Make a granted call and a denied call. In your client:

Use broker_explain_request for a GET to

https://api.github.com/repos/octocat/hello-world with credential github.

It answers *allowed* and names the deciding rule. Now ask the same with DELETE: *denied*, no grant. Then ask for broker_read on the GET and you get the response body with the token redacted wherever it might appear. The audit log (data/audit.jsonl) now holds the who, what and outcome, never the content.

1. Pause and resume. Press Pause all access in the page header and type PAUSE. The agent's next call is refused with a message not to retry. Press Resume all access and type RESUME. From a terminal: npm run pause -- on and npm run pause -- off.

ChatGPT web

The broker's native connection is local stdio. For a private ChatGPT integration, an eligible workspace can connect through OpenAI Secure MCP Tunnel, with the tunnel client launching the broker under a dedicated policy identity. Run the tunnel client under the OS account that owns the keys and keep the key manager on loopback. This connection needs its own workspace setup and verification. Public distribution as a local ChatGPT desktop plugin is limited to approved partners.

Why

Giving an agent an API key gives it everything the key can do, for as long as the key lives, invisibly. Most agent tasks need a fraction of that: *read these repos*, *query this endpoint*, *GET but never DELETE*. This broker turns "here is my key" into "here is a scoped, observable capability":

• Possession vs use. Agents exercise credentials; they never possess them.
• Deny-by-default. Authority is an enumerated list of named operations per credential. An absent grant is a denial, not an oversight. Deny rules always beat grants.
• Nothing widens sideways. A method, path, query parameter, body rule, or approval attached to one credential never widens any other credential.
• One decision function. The dry-run explainer and the live request path call the same evaluate(). What the broker reports and what it enforces cannot drift apart.
• Content-free audit. Who reached what, when, with what outcome, and through which lifecycle state. Never what they saw.

Tools

Policy (version 2)

Policy objects reject unknown fields at every level. Correct misspelt keys and remove unsupported metadata before upgrading; ignored fields could otherwise remove a restriction, such as a misspelt enabled or deny.

One YAML file declares credentials and per-credential operation grants:

version: 2

credentials:

• id: github-readonly kind: bearer # bearer | header | basic | query env_var: GITHUB_READONLY_TOKEN base_url: https://api.github.com

agents:

• id: researcher grants:
• credential: github-readonly operations:
• id: read-repo method: GET path: /repos/*/* # literal segments, '*', or trailing '**' response_body: true # default is metadata only deny:
• /repos/*/*/keys

A request must clear every gate: identity provisioned and enabled, credential granted, URL canonical and provably unambiguous, origin exactly the credential's origin, path inside the credential's base path, no deny match, and an operation whose method, path template, query parameter allowlist, and body rule all match. broker_explain_request reports which gate decided any outcome.

Semantics worth knowing:

• Operation paths are relative to the credential's base path. With base_url: https://api.example.com/v2, the template /weather authorises /v2/weather.
• Path matching is case-sensitive for operations and case-insensitive for deny rules, because many upstreams treat paths case-insensitively.
• Query parameters not named in query_params are denied.
• Operations without a body rule reject any request body. Body rules name allowed content types and a byte cap. Mutations must declare requires_approval explicitly, true or false.
• Responses default to metadata only. response_body: true relays the body, and only for content types in response_content_types (default application/json).
• Credentials of kind query must set high_risk: true: URLs are commonly retained by upstream and proxy telemetry, so a query-string secret has a wider blast radius than a header.

Approvals

An operation with requires_approval: true executes only when the request carries an approval_id that exists in the approval store, is bound to exactly this principal, credential, and operation, is unexpired, and is not revoked, checked at execution time, not config-load time. On stdio the store is a JSON file (config/approvals.json by default) that is re-read on every check, so editing it revokes access mid-flight:

[

{ "id": "apr-2026-08-13-01", "agent_id": "researcher", "credential_id": "github-readonly", "operation_id": "create-issue", "expires_at": "2026-08-14T00:00:00Z", "revoked": false } ]

Migrating from version 1

Version 1 policies shared one method list and path set across every credential an agent held, so authority needed for one credential widened all of them. The broker refuses v1 files. Convert with:

npm run migrate -- config/broker.yaml > config/broker-v2.yaml

The output is deliberately conservative (mutations require approval, query parameters must be enumerated) and flagged for review: it makes the old blast radius visible rather than silently preserving it.

Safety properties

• Every URL is canonicalised once; policy and the outbound request consume the same canonical value, and the outbound bytes are round-trip checked. Encoded separators, double encoding, control characters, backslashes, userinfo, non-ASCII path segments, repeated or trailing slashes, and trailing-dot segments are rejected, not guessed at.
• Secrets are injected into exactly one header or query parameter. One redactor covers response bodies, relayed headers, error chains, and audit records, across raw, Base64, base64url, percent-encoded, form-encoded, and NFC/NFD representations, including truncation boundaries.
• Raw upstream error text is never relayed to agents; they receive a stable error category and a trace id, and the redacted detail goes to the audit log.
• Redirects are refused: a redirect could point anywhere, and fetch would re-send the injected credential there.
• A credential can only be exercised against its exact origin and base path; lookalike hosts and string-prefix tricks are refused.
• Plain-http upstreams are rejected at policy load, except on loopback.
• Response headers are allowlisted; Set-Cookie and friends are dropped.
• Responses are size-capped per operation, metadata-only by default.
• Mutations are a separate, honestly-annotated tool; approval state is checked at execution time; a dispatch failure on a mutation is recorded as indeterminate, never silently retried.
• Every decision is audited through its full lifecycle without request or response content, and audit records pass through the redactor too.

Identity boundary

On stdio, BROKER_AGENT_ID is a trusted-launcher assertion: the operator starting the process vouches for which agent is connected. It is only a real boundary when the broker runs under the secure-launch profile in SECURITY.md: dedicated OS identity, owner-only