fix(runner): keep Claude MCP bearer tokens out of process arguments (#22206)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - The runner starts Claude through ACPX and the Claude ACP agent.
> - The runner gives Claude HTTP MCP servers: the task tool bridge and hosted connectors. Each server has a bearer token.
> - The Claude Agent SDK writes these servers, with their headers, into the inline `--mcp-config` argument of the Claude CLI.
> - Thus a `ps aux` or `ps -ef` command in the sandbox shows the bearer tokens. Tool logs then keep the tokens.
> - This pull request sends a `${VAR}` reference in the header. The token goes into the launch environment of the agent.
> - The benefit is that process lists do not show MCP bearer tokens.

## Linked Issues or Issue Description

**What happened?**
An agent ran `ps aux` in its sandbox. The output showed the Claude CLI process with an `--mcp-config` argument. That argument had an `Authorization: Bearer <token>` header for each HTTP MCP server. The tool log kept the full output.

**What did you expect to happen?**
Process arguments must not contain credentials. A process list must not show MCP bearer tokens.

**Steps to reproduce**
1. Start a Claude agent on the runner with the task tool bridge or a hosted connector.
2. In the agent, run `ps -ef`.
3. Look at the Claude CLI line. The `--mcp-config` JSON contains `"Authorization":"Bearer ..."`.

**Root cause**
`openQualifiedAcpxRuntime` sent the literal `Bearer <token>` header in the ACP `mcpServers` list. The Claude ACP agent gives this list to the Claude Agent SDK. The SDK always serializes it into `--mcp-config <json>` on the CLI command line.

## What Changed

- For the Claude ACPX profile, each HTTP MCP header now has the value `Bearer ${PAPERCLIP_ACPX_MCP_BEARER_<n>}`.
- The runner puts each token in the Claude launch environment under the same name. Claude Code expands `${VAR}` in `--mcp-config` when it connects to the server.
- Other ACPX agents keep the literal header. Their CLIs do not have a known `${VAR}` expansion.
- Added a regression test. Updated one exact launch-environment assertion for the new variable.

## Verification

- Failing before the fix: `npx vitest run src/drivers/acpx/acpx-runtime-adapter.test.ts -t "MCP bearer tokens out of the CLI argv"` (in `packages/paperclip-runner`). It failed with `expected '[{"type":"http","name":"paperclip",…' not to contain 'bridge-secret'`. The projected header had the literal synthetic token.
- Passing after the fix: `npx vitest run src/drivers/acpx/acpx-runtime-adapter` — 7 files, 136 tests passed.
- Manual check of the expansion: I ran the pinned Claude CLI (agent SDK 0.3.286) with `--mcp-config` and a header `Bearer ${SYNTH_MCP_BEARER}` against a local HTTP server. The server got the expanded synthetic value.
- `tsc --noEmit -p packages/paperclip-runner`: no new errors. The only errors are in `src/eval/workflow-harness.ts` and occur on `master` too, because my local install did not include the eval kernel package.
- The full `src/drivers/acpx/` folder has other failures in this sandbox (`EACCES` on `/proc/self/fd` spawn, directory fsync). The same failures occur on `master` without this change.

## Risks

- Medium-low risk. If a future Claude CLI stops the `${VAR}` expansion in `--mcp-config`, MCP calls fail authentication. They do not leak the token. The regression test pins the header shape.
- The token is now in the Claude process environment. Only the same user can read `/proc/<pid>/environ`. Other credentials are already in this environment. Shell tools that Claude starts also inherit the environment, so `env` output can still show the token. Log redaction must continue to cover bearer values.
- Tokens that already appeared in logs are not revoked by this change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code execution.

## Checklist

- [x] I have included a thinking path that traces from project context to this change
- [x] I have specified the model used (with version and capability details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before requesting merge

Related: #13572 removes bearer tokens from curl arguments in the agent helper scripts. This pull request covers the Claude CLI MCP configuration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)



Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-18 15:58:46 -06:00
1 parent bb258a5429
commit d668eeb660
2 files changed
+52 -2

No files matched your search

@@ -1118,10 +1118,49 @@ describe("Codex ACPX runtime adapter", () => {
expect(spawnedAgentEnvironment(runtimeOptions, options.command)).toEqual({
PAPERCLIP_ACPX_ISOLATED_CONTEXT: "1",
PAPERCLIP_ACPX_TASK_TOOL_BRIDGE_URL: binding === "runner-owned" ? "http://127.0.0.1:3210/mcp" : "",
...(binding === "absent" ? {} : { PAPERCLIP_ACPX_MCP_BEARER_0: "bridge-secret" }),
});
},
);
it("keeps Claude MCP bearer tokens out of the CLI argv and in the launch environment", async () => {
const options = openOptions(fakeCommand());
options.profile = resolveQualifiedAcpxProfile("claude", "claude-sonnet-5");
options.mcpServers = [
{ name: "desktop", command: "/bin/desktop-mcp", args: ["mcp"], env: { HOME: "/runtime/home" }, runnerOwned: false },
{ name: "paperclip", url: "http://127.0.0.1:3210/mcp", bearerToken: "bridge-secret", runnerOwned: true },
{ name: "connector", url: "https://connector.invalid/mcp", bearerToken: "connector-secret", runnerOwned: false },
];
let runtimeOptions: AcpRuntimeOptions | undefined;
await openQualifiedAcpxRuntime(options, {
createRegistry: () => registry(),
createStore: () => store(),
createRuntime: (created) => {
runtimeOptions = created;
return fakeRuntime();
},
});
const projected = JSON.stringify(runtimeOptions?.mcpServers);
expect(projected).not.toContain("bridge-secret");
expect(projected).not.toContain("connector-secret");
expect(runtimeOptions?.mcpServers).toEqual([
{ name: "desktop", command: "/bin/desktop-mcp", args: ["mcp"], env: [{ name: "HOME", value: "/runtime/home" }] },
{
type: "http", name: "paperclip", url: "http://127.0.0.1:3210/mcp",
headers: [{ name: "Authorization", value: "Bearer ${PAPERCLIP_ACPX_MCP_BEARER_1}" }],
},
{
type: "http", name: "connector", url: "https://connector.invalid/mcp",
headers: [{ name: "Authorization", value: "Bearer ${PAPERCLIP_ACPX_MCP_BEARER_2}" }],
},
]);
expect(spawnedAgentEnvironment(runtimeOptions, options.command)).toMatchObject({
PAPERCLIP_ACPX_MCP_BEARER_1: "bridge-secret",
PAPERCLIP_ACPX_MCP_BEARER_2: "connector-secret",
});
expect(spawnedAgentEnvironment(runtimeOptions, options.command)).not.toHaveProperty("PAPERCLIP_ACPX_MCP_BEARER_0");
});
it("launches only through the verified command lease", async () => {
const runtime = fakeRuntime();
const command = fakeCommand();
@@ -428,6 +428,16 @@ export async function openQualifiedAcpxRuntime(
? createAntigravityAdmission(options.systemInstructions, options.profile.reportedModelId)
: null;
const contextAdmission = instructionAdmission ?? antigravityAdmission;
const mcpBearerVariable = (index: number): string | undefined =>
options.profile.agent === "claude" ? `PAPERCLIP_ACPX_MCP_BEARER_${index}` : undefined;
const mcpBearerEnvironment = Object.fromEntries(options.mcpServers.flatMap((server, index) => {
const name = mcpBearerVariable(index);
return name && "url" in server ? [[name, server.bearerToken]] : [];
}));
const mcpBearerCredential = (index: number, bearerToken: string): string => {
const name = mcpBearerVariable(index);
return name ? `\${${name}}` : bearerToken;
};
// The agent's complete launch environment. ACPX's own environment handling
// (credential checks, ACP terminals) keeps reading this process's environment.
const agentEnvironment = (): Record<string, string> => ({
@@ -444,6 +454,7 @@ export async function openQualifiedAcpxRuntime(
PAPERCLIP_ACPX_TASK_TOOL_BRIDGE_URL: options.mcpServers.find(
(server): server is Extract<typeof server, { url: string }> => "url" in server && server.runnerOwned && server.name === "paperclip",
)?.url ?? "",
...mcpBearerEnvironment,
}
: {}),
});
@@ -515,7 +526,7 @@ export async function openQualifiedAcpxRuntime(
? [...options.permissionPolicy.escalate]
: undefined,
},
mcpServers: options.mcpServers.map((server) => "command" in server ? {
mcpServers: options.mcpServers.map((server, index) => "command" in server ? {
name: server.name, command: server.command, args: server.args,
env: Object.entries(server.env).map(([name, value]) => ({ name, value })),
} : ({
@@ -523,7 +534,7 @@ export async function openQualifiedAcpxRuntime(
name: server.name,
url: server.url,
headers: [
{ name: "Authorization", value: `Bearer ${server.bearerToken}` },
{ name: "Authorization", value: `Bearer ${mcpBearerCredential(index, server.bearerToken)}` },
],
})),
onPermissionRequest: async (request, context) => {