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, hex, 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.

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

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

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

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

This is the beginning of the README. Read the rest at the original. Read the full README ↗