Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Connect an AI agent through MCP

bouncer-mcp lets an AI agent ask a person for access to a secret, wait for the decision, and then use the secret. It speaks the Model Context Protocol (MCP) over standard input and output, so any MCP client can start it.

A requester key can't sign an approval. bouncer-mcp has no tool to approve, deny, pair or change policy. Its tools can make and cancel requests, revoke the agent's own grants, and save values once a save is approved, where policy allows it.

Give the agent its own requester of kind agent. Never give it your own key: a human requester's key can get access to a personal credential set to Always approved without anyone approving on a device (Approvals and access duration).

Before you start

  • bouncer-mcp installed on the agent's machine (Install the CLI). Install bouncer beside it too, so the agent can deliver a secret to a command without fetching it through get_secret. The command must keep the value out of its output and logs.
  • A requester of kind agent, made for this agent, and its key in a private file (Set up a requester). Use a separate file, for example ~/.config/bouncer/agent-key, so it isn't confused with your own key.

bouncer-mcp only runs with an agent's key. At start-up it asks the server who the key belongs to, and stops if it's a person's or a host's. That keeps the approver's label honest: the app shows "Your own agent", not "Self-approval", and the agent can't use grants you got for yourself.

1. Check the settings

BOUNCER_URL=https://bouncer.example.com BOUNCER_KEY_FILE=~/.config/bouncer/agent-key bouncer-mcp --check

Run this yourself, in a terminal. It prints for you, not for the agent. Expected result (with the address and paths changed):

Bouncer server: https://bouncer.example.com
Instance:       Example home (example-home)
Requester:      build-agent (rqr_01jbx1q3s5t7v9w1x3y5z7a9b1), an AI agent, owned by alice
Key file:       /home/alice/.config/bouncer/agent-key
Run with:       BOUNCER_URL=https://bouncer.example.com BOUNCER_KEY_FILE=/home/alice/.config/bouncer/agent-key /home/alice/.local/bin/bouncer exec <resource> -- <command>
The settings work. Agents using this server can ask for access; a human approves each request on their phone.

The Run with line is always printed. When bouncer-mcp finds the bouncer command beside it or on your PATH, it shows the command as above. Otherwise it says no bouncer CLI was found, so the agent can only read values with get_secret; install bouncer so the agent can use exec instead (Keep values out of the conversation).

With a host's key instead, it exits 7 and says how to make an agent requester.

2. Register it with your client

Claude Code:

claude mcp add bouncer \
  --env BOUNCER_URL=https://bouncer.example.com \
  --env BOUNCER_KEY_FILE="$HOME/.config/bouncer/agent-key" \
  -- "$HOME/.local/bin/bouncer-mcp"

Check it's registered and starts:

claude mcp list

Expected result: a bouncer line that says it's connected. If it says it failed, run the --check command from step 1 with the same settings.

Clients that read a JSON config (Claude Desktop, or a project's .mcp.json). JSON doesn't expand $HOME or ~, so write your own home folder in full where this example has /home/alice:

{
  "mcpServers": {
    "bouncer": {
      "command": "/home/alice/.local/bin/bouncer-mcp",
      "env": {
        "BOUNCER_URL": "https://bouncer.example.com",
        "BOUNCER_KEY_FILE": "/home/alice/.config/bouncer/agent-key"
      }
    }
  }
}

Restart the client, then check that its list of MCP servers or tools shows bouncer.

Only the key file's path goes in the client's settings. bouncer-mcp never reads the key from an environment variable, because MCP clients store those in their settings files, and a project's .mcp.json may be committed.

VariableMeaning
BOUNCER_URLThe Bouncer server's address. HTTPS, or plain HTTP to this machine only
BOUNCER_KEY_FILERequired. The agent's key file. It must be private (chmod 600)
BOUNCER_CA_FILEOptional. Extra CA certificates (PEM) for Bouncer and OpenBao

The tools

ToolArgumentsWhat it does
list_resourcesnoneLists what this agent may ask for, with each resource's durations, decision time and token lifetime
request_accessresource, duration, reasonFiles a request and returns at once with its ID, status (pending) and deadline. If the agent already has a pending request or an active grant (with at least 2 minutes left) for the resource, it returns that instead of asking again
get_request_statusrequest_idOne request, without waiting
wait_for_decisionrequest_id, optional timeout_secondsWaits for the decision, 55 seconds by default and at most 120. If it's still pending, the agent calls it again
get_secretresourceFor an active grant, fetches a short-lived token, reads the secret and returns its field values. Never returns the token
list_grantsoptional include_endedThe agent's grants
revoke_grantgrant_idEnds one of the agent's grants now
cancel_requestrequest_idWithdraws a pending request
request_storeresource, fields, reasonAsks permission to save new values into a resource that allows writes. Field names only
save_secretrequest_id, valuesAfter approval, saves the values once

The usual flow is list_resources, request_access, wait_for_decision (repeated while pending), then either get_secret or the bouncer exec command the result suggests, and revoke_grant when done. The server gives the client this flow in its MCP instructions.

The approver sees the request as coming from the agent's requester, with the MCP client's name (for example claude-code via bouncer-mcp) and the machine's name, both labelled as reported by the requester.

Keep values out of the conversation

get_secret gives the values to the model. From then on they are in the conversation, and may be in the client's logs and the model provider's records. Revoking the grant doesn't take a value back; only rotating the secret does. Every get_secret result says so.

When the task only needs to run something with the secret, use the bouncer exec command that wait_for_decision suggests, when bouncer is installed beside bouncer-mcp. (--check shows the same command for the operator.) This avoids returning the value as an MCP tool result, but the child command can still print, log, save or send it. Its standard output and standard error may enter the conversation and the client's logs. Choose a command whose output you have checked with fake data; don't use env, shell tracing or a command that echoes credentials. Only give an agent access to secrets you'd be willing to rotate.

Logs

bouncer-mcp logs to standard error, one line per tool call: the tool's name, and for a refusal the first line of its message. It never logs arguments, values, tokens or the key.

How this was checked

The --check output, tool list and arguments are checked against mcp/src/main.rs and mcp/src/tools.rs. A historical 0.5.0 run has no retained transcript in this manual's evidence. The tools were not driven from a real MCP client for this page; the project's mcp/tests drive the real binary over standard input and output.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).