armos-mcp

Automatic PII masking for Claude Code. Every prompt you send gets scanned for personally identifiable information — emails, phone numbers, names, addresses, SSNs — and those values are replaced with tokens before leaving your machine. The real values are restored in the response, so Claude Code works normally while your sensitive data never reaches Anthropic.

How it works

Claude Code → localhost:3939 (armos-mcp proxy)
                    ↓ PII replaced with tokens
             proxy.armos.dev (armos cloud)
                    ↓ masked request forwarded
             api.anthropic.com
                    ↓ response with tokens
             proxy.armos.dev (tokens → real values)
                    ↓ demasked response
Claude Code ← localhost:3939

Two components run as a single subprocess launched by Claude Code:

• HTTP proxy (port 3939) — intercepts API calls and handles masking/demasking
• MCP server (stdio) — exposes status and session management tools

Prerequisites

• Node.js 18+
• An armos account and API key — armos.dev
• Claude Code CLI

Setup

1. Get your armos API key

Sign up at armos.dev, create an app, and copy the API key.

2. Register the MCP with Claude Code

claude mcp add armos npx @armos/mcp \
  -e ARMOS_API_KEY=arm_live_your_key_here \
  -e ARMOS_PROXY_URL=https://proxy.armos.dev \
  -e ARMOS_FAIL_MODE=open \
  -e ARMOS_PORT=3939

Note: MCPs must be added via claude mcp add. Adding mcpServers to ~/.claude/settings.json does not work — Claude Code reads MCPs from ~/.claude.json.

3. Route Claude Code traffic through the proxy

Add this to your ~/.zshrc (or ~/.bashrc):

export ANTHROPIC_BASE_URL=http://localhost:3939

Reload your shell and restart Claude Code:

source ~/.zshrc
claude

Verify it's working

Send a prompt containing an email address:

What is the domain of the email [email protected]? Just the part after the @.

If armos is active, Claude will respond saying it sees a PII token rather than the actual email — confirming the value never reached Anthropic.

You can also check session stats at any time by running the armos_status tool from /mcp in Claude Code.

MCP tools

armos_status

Returns the current session state:

{
  "conv_id": "3f8a1c2d-...",
  "entities_masked_this_session": 4,
  "fail_mode": "open",
  "proxy_url": "https://proxy.armos.dev",
  "local_port": 3939
}

armos_clear_session

Rotates the conversation ID and resets the entity counter. Use this when starting a new sensitive conversation to ensure PII from prior turns can't be referenced in the new vault scope.

Configuration

| Environment variable | Default | Description | |---|---|---| | ARMOS_API_KEY | — | Your armos API key (required) | | ARMOS_PROXY_URL | https://proxy.armos.dev | Armos proxy endpoint | | ARMOS_FAIL_MODE | open | open passes requests through unmasked if proxy is unreachable; closed blocks them | | ARMOS_PORT | 3939 | Local proxy port |

Fail modes

open (default) — if the armos proxy is unreachable, requests are forwarded directly to Anthropic without masking. Claude Code keeps working; PII protection is silently bypassed.

closed — if the armos proxy is unreachable, requests are blocked with a 503. Use this when unmasked requests are unacceptable (e.g. compliance environments).

What gets masked

• Email addresses
• Phone numbers
• Person names
• Physical addresses
• Social Security Numbers
• Credit card numbers
• Custom entity types configured in your armos app

Building from source

npm install
npm run build

Then register the local build instead of the npm package:

claude mcp add armos node /path/to/armos-mcp/dist/index.js \
  -e ARMOS_API_KEY=arm_live_your_key_here \
  -e ARMOS_PROXY_URL=https://proxy.armos.dev \
  -e ARMOS_FAIL_MODE=open \
  -e ARMOS_PORT=3939