secret-scratch
Enables pushing stored secrets to GitHub Actions via secret_pipe, such as piping an env-file value to gh secret set without exposing it to the agent.
Supports running the secret-scratch ACP middleware inside JetBrains hosts, blocking access to held files and scrubbing secrets from ACP session updates.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
secret-scratch
Securely send secrets to your AI agent with $$value without the LLM, transcript, or logs ever seeing them.

You type: Put $$sk_live_9876543210 into .env.local as STRIPE_KEY, then push it to GitHub Actions.
Agent sees: Put †m1.1 into .env.local as STRIPE_KEY, then push it to GitHub Actions.
Agent calls: secret_scratch(action: "env", ref: "†m1.1", path: ".env.local", key: "STRIPE_KEY")
secret_pipe(envFile: ".env.local", key: "STRIPE_KEY", command: "gh secret set STRIPE_KEY")
Agent gets: { ok: true, exitCode: 0 }
Agent tries: cat .env.local -> BLOCKED (.env.local is held by secret-scratch)Zero runtime dependencies. Works with Node.js 20+ and Bun 1.4+. Ships three ways to integrate:
Drop-in Agent Client Protocol (ACP) middleware proxy (
secret-scratch -- <acp-agent-command>) wrapping Claude ACP, Codex ACP, Gemini CLI ACP, or any ACP agent inside hosts such as Zed and JetBrains.Stdio MCP server (
secret-scratch mcp) exposingsecret_scratchandsecret_pipe.TypeScript library (
@inixiative/secret-scratch) for custom harnesses and agent runtimes.
Why
Pasting an API key or private key into a coding agent chat sends the secret to the model provider, writes it into session transcripts, and leaves it in tool logs and crash dumps.
secret-scratch intercepts secrets before they reach the model:
Lift before inference. Any word prefixed with
$$(plus common shaped tokens such assk-...,ghp_...,AKIA...,AIza..., and PEM private keys if you forget the prefix) is moved into a0600per-thread scratch pad file in~/.secret-scratch/(0700) and replaced with an opaque reference like†m1.1.Use by reference. The agent receives two MCP tools:
secret_scratch(list,env,write,consume) andsecret_pipe(pipes a secret to a shell command'sstdin, discardsstdoutandstderr, returns onlyexitCode).Block access to held files. Every file written by
secret_scratchis recorded inheld-files.json. ACP permission requests, filesystem calls, and terminal calls targeting a held file, a.privatepath, or the scratch pad directory are denied at the proxy boundary.Scrub outgoing updates. Held values (6+ characters) are scrubbed from outgoing
session/updateframes back into their†reference as defense in depth.
Related MCP server: Keiko
Quick start (ACP proxy)
Wrap any ACP agent command with npx @inixiative/secret-scratch --:
npx -y @inixiative/secret-scratch -- <your-acp-agent-command> [args...]Or install globally:
npm install -g @inixiative/secret-scratch
secret-scratch -- <your-acp-agent-command> [args...]Example: Zed (settings.json)
{
"agent_servers": {
"Claude Code (secret-scratch)": {
"command": "npx",
"args": ["-y", "@inixiative/secret-scratch", "--", "claude-agent-acp"]
},
"Codex (secret-scratch)": {
"command": "npx",
"args": ["-y", "@inixiative/secret-scratch", "--", "codex-acp"]
},
"Gemini CLI (secret-scratch)": {
"command": "npx",
"args": ["-y", "@inixiative/secret-scratch", "--", "gemini", "--experimental-acp"]
}
}
}When a session starts, the proxy:
Injects the
secret-scratchstdio MCP server intosession/new,session/load,session/resume, andsession/fork(preserving all other MCP servers).Lifts
$$valuemarkers and recognised secret shapes onsession/promptbefore forwarding to the agent, attaching usage guidance on the first turn that carries a secret.Rejects
session/request_permission,fs/read_text_file,fs/write_text_file, andterminal/createcalls targeting held files,.privatepaths, or~/.secret-scratch.Scrubs held values out of
session/updatenotifications.
CLI flags
secret-scratch [options] -- <acp-agent-command> [args...]
secret-scratch mcp --dir <path> --thread <id> [--cwd <path>]
secret-scratch list [--dir <path>] [--thread <id>]
secret-scratch clear <thread> [--dir <path>]
Options:
--dir <path> Scratch pad directory (default: ~/.secret-scratch)
--private <glob> Extra private path glob to block (repeatable)
--no-lift-shaped Only lift explicit $$value markers
--no-scrub Disable scrubbing held values from session/updateLibrary usage
import {
SecretScratchPad,
SHAPED_SECRET_PATTERNS,
privatePathGate,
scratchTarget,
} from '@inixiative/secret-scratch';
const pad = new SecretScratchPad('~/.secret-scratch');
// 1. Lift before sending to the LLM
const { text, refs } = pad.lift(
'Set STRIPE_KEY to $$sk_live_example1234567890 in .env.local',
{ thread: 'thread_1', message: 'm1' },
{ patterns: SHAPED_SECRET_PATTERNS },
);
// text === 'Set STRIPE_KEY to †m1.1 in .env.local'
// 2. Write safely inside cwd (rejects .., symlink escapes, .git, .claude, .ssh)
const target = scratchTarget(process.cwd(), '.env.local');
pad.env({ ref: refs[0]! }, 'thread_1', target, 'STRIPE_KEY', { consume: true });
// 3. Pipe straight to a CLI without returning stdout/stderr
const { exitCode } = await pad.pipe(
{ envFile: target, key: 'STRIPE_KEY' },
'thread_1',
'gh secret set STRIPE_KEY',
);
// 4. Gate agent file/shell tools
const gate = privatePathGate({
scratchDir: pad.dir,
heldFiles: pad.heldFiles(),
});
gate({ toolName: 'Bash', toolInput: { command: 'cat .env.local' } });
// { behavior: 'deny', message: '.env.local is private: ...' }See docs/VERBS.md for the complete public API table.
Security model and boundaries
Prevents accidental exposure to the LLM, agent transcripts, and tool output. Secrets lifted at the prompt boundary never enter model context, prompt caches, or downstream agent session transcripts.
secret_pipediscardsstdoutandstderrand kills the whole process group on timeout.On-disk storage is
0600plaintext in a0700directory. Scratch pads live at~/.secret-scratch/<thread>.paduntil consumed or cleared (secret-scratch clear <thread>). They protect against LLM and transcript leakage, not against another process running as your OS user.Shell gating and
secret_pipedefend against accidental leaks, not a hostile sandbox. If a downstream agent runs shell commands directly inside its own process without asking the ACP host viasession/request_permissionorterminal/create, the ACP proxy cannot intercept those local subprocess calls. Likewise, an adversarial model that can pass arbitrary shell commands tosecret_pipecould write stdin to an untracked file or encode bytes in the exit code. For enforcement against an untrusted model, pairsecret-scratchwith an OS sandbox or a harness that routes all tool calls throughprivatePathGateand restricts allowed pipe commands.Single-word marker.
$$valuelifts up to the next whitespace. Multi-line secrets (such as PEM private keys) are lifted by shape automatically; arbitrary multi-line secrets should be passed by file or env key rather than$$.
Origin
Extracted from Foundry, a source-available (BSL 1.1) local agent harness built by inixiative.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Secrets for developers and agents—secure context and workflows without exposing secret values.
A secret store for AI agents: the agent never sees the plaintext.
One-time, end-to-end encrypted secrets for agents. 0.005 USDC per secret via x402.
Encrypted secret store and rotation for autonomous agent credentials
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables secure credential storage for AI agents by encrypting secrets and providing agent-invisible references, ensuring sensitive data never leaks to the model.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to securely use secrets by running commands with environment-injected credentials and sanitizing output to prevent leakage.1-
- AlicenseCqualityCmaintenanceEnables AI agents to securely store and manage encrypted secrets locally while using them indirectly through environment-variable injection or file writes, so plaintext values never enter the agent's context.8MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to securely inject API keys and secrets into environment files, configs, or commands without the agent ever seeing the secret values.MIT