Skip to main content
Cordon integrates with Claude Code so your AI agent can make authenticated API calls without holding real credentials.
Cordon currently works with API key authentication only. If you use Claude Code with a Claude Pro/Team subscription (OAuth login), credential injection won’t apply — Claude Code authenticates directly via OAuth, bypassing the proxy. Support for OAuth-based subscriptions is coming soon.

​
Scope

Claude Code setup defaults to project scope: cordon.toml lives in $CWD, and settings are written to $CWD/.claude/settings.local.json. This keeps credentials and proxy configuration isolated per repository and per checkout — settings.local.json is Claude Code’s gitignored-by-convention override file, so git worktrees do not inherit stale proxy env vars from a tracked settings.json. To share a single cordon configuration across all projects, use user scope: 
cordon setup claude-code --scope user
User scope writes settings to $HOME/.claude/settings.json and stores config at $XDG_CONFIG_HOME/cordon/cordon.toml. See Scopes for path details and trade-offs.

​
Automated setup

The fastest way to get started: 
cordon setup claude-code
This:
  1. Generates CA certificates (if not already present)
  2. Creates a scaffold cordon.toml
  3. Generates a combined CA bundle (system CAs + Cordon CA)
  4. Configures Claude Code’s settings file (.claude/settings.local.json for project scope, ~/.claude/settings.json for user scope) with proxy env vars (HTTPS_PROXY, HTTP_PROXY, https_proxy, http_proxy, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE)
Any existing settings file is backed up to <name>.cordon.bak before any changes are made. If setup detects cordon env vars in a project’s tracked settings.json (from a pre-fix install), they are migrated into settings.local.json automatically during the next cordon setup claude-code run. To run cordon as a background service, run cordon service install after setup (add --scope user if you set up Claude Code with --scope user).

​
Remove the setup

cordon integration disable claude-code

​
Adding routes

The cordon route, cordon start, and cordon service commands below default to project scope. If you set up Claude Code with --scope user, append --scope user to each of these commands so they target ~/.config/cordon/cordon.toml instead of ./cordon.toml.
After setup, add a route for your API provider. Example for Anthropic: 
cordon route add
If you chose keyring as the secret source, store the secret: 
cordon secret set anthropic
You can also edit cordon.toml directly — see Routes for the full format.

​
API key setup

Claude Code needs an API key env var set so it selects the API key auth path. Add a placeholder to your settings file — .claude/settings.local.json for project scope or ~/.claude/settings.json for user scope: 
{
  "env": {
    "ANTHROPIC_API_KEY": "dummy-replaced-by-cordon"
  }
}
Cordon strips this dummy key and injects the real one from your secret store at the network layer.

​
Manual setup

If you prefer manual configuration, set these env vars in Claude Code’s environment. Replace <PORT> with the port written into your cordon.toml (check listen = ...): 
export HTTPS_PROXY=http://127.0.0.1:<PORT>
export HTTP_PROXY=http://127.0.0.1:<PORT>
export https_proxy=http://127.0.0.1:<PORT>
export http_proxy=http://127.0.0.1:<PORT>
export NODE_EXTRA_CA_CERTS=./ca-cert.pem
export SSL_CERT_FILE=/path/to/combined-ca.pem
export REQUESTS_CA_BUNDLE=/path/to/combined-ca.pem
export CURL_CA_BUNDLE=/path/to/combined-ca.pem
You must create a combined CA bundle manually if not using cordon setup claude-code. Concatenate your system CA bundle with the Cordon CA cert — see Combined CA bundle below.
You can add these to Claude Code’s settings file (replace <PORT> with the port in your cordon.toml). For project scope, write to .claude/settings.local.json — Claude Code’s per-checkout, gitignored-by-convention override file — so worktrees don’t inherit stale proxy env vars. For user scope, write to ~/.claude/settings.json: 
{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:<PORT>",
    "HTTP_PROXY": "http://127.0.0.1:<PORT>",
    "https_proxy": "http://127.0.0.1:<PORT>",
    "http_proxy": "http://127.0.0.1:<PORT>",
    "NODE_EXTRA_CA_CERTS": "./ca-cert.pem",
    "SSL_CERT_FILE": "/path/to/combined-ca.pem",
    "REQUESTS_CA_BUNDLE": "/path/to/combined-ca.pem",
    "CURL_CA_BUNDLE": "/path/to/combined-ca.pem"
  }
}

​
Combined CA bundle

Claude Code can launch MCP servers and tools that use Python, curl, wget, or other non-Node runtimes. These tools use SSL_CERT_FILE, REQUESTS_CA_BUNDLE, or CURL_CA_BUNDLE to locate trusted certificates. Python’s SSL_CERT_FILE replaces the default certificate store rather than appending to it. Setting it to just the Cordon CA cert would break TLS for all non-proxied connections (the system CAs would be missing). To solve this, cordon setup claude-code generates a combined CA bundle that concatenates:
  1. Your system CA certificates (e.g., from /etc/ssl/cert.pem)
  2. The Cordon proxy CA certificate
This combined bundle is written next to the Cordon CA cert (e.g., combined-ca.pem) and SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and CURL_CA_BUNDLE all point to it.
  • SSL_CERT_FILE — used by Python’s ssl module and OpenSSL-based tools
  • REQUESTS_CA_BUNDLE — used by Python’s requests library (does not read SSL_CERT_FILE)
  • CURL_CA_BUNDLE — used by curl and libcurl-based tools
  • NODE_EXTRA_CA_CERTS — used by Node.js (appends to built-in CAs, so it points to just the Cordon CA cert, not the combined bundle)

​
Trust the CA

If tools used by Claude Code fail with certificate errors: 
tls: failed to verify certificate: x509: certificate signed by unknown authority
Add the CA to the system trust store: 
cordon trust
Node.js ignores the system trust store, so you still need NODE_EXTRA_CA_CERTS for Node-based tools (this is handled automatically by cordon setup claude-code).

​
Workflow

Once configured, the workflow is:
  1. Start cordon: cordon start (or use the background service)
  2. Start Claude Code as usual
  3. When Claude Code makes API calls to configured hosts, cordon transparently injects credentials
  4. Claude Code never sees or logs real API keys
Use cordon doctor to diagnose any setup issues. It checks config validity, cert paths, trust store status, and port availability.

​
Troubleshooting

​
Certificate errors

If tools used by Claude Code fail with certificate errors: 
tls: failed to verify certificate: x509: certificate signed by unknown authority
  1. Verify NODE_EXTRA_CA_CERTS is set in your settings file (.claude/settings.local.json for project scope, ~/.claude/settings.json for user scope) and points to an existing file
  2. For Python MCP servers, verify SSL_CERT_FILE and REQUESTS_CA_BUNDLE are set and point to the combined CA bundle (not just the Cordon CA cert)
  3. For curl/wget-based tools, verify CURL_CA_BUNDLE is set
  4. For other non-Node tools, add the CA to the system trust store: cordon trust
Node.js ignores the system trust store — it only reads NODE_EXTRA_CA_CERTS. Python’s SSL_CERT_FILE replaces the system store, so it must point to the combined bundle. Both are handled automatically by cordon setup claude-code.

​
Proxy not being picked up

Verify the env vars are in Claude Code’s settings file. Project scope writes .claude/settings.local.json; user scope writes ~/.claude/settings.json. 
# Project scope
cat .claude/settings.local.json

# User scope
cat ~/.claude/settings.json
If the vars are set but Claude Code isn’t routing through the proxy, ensure cordon is running: 
cordon status
# Replace <PORT> with the listen port from your cordon.toml
curl http://127.0.0.1:<PORT>/health

​
MCP servers not using the proxy

Node.js MCP servers need the bootstrap loader to enable proxy support. Add to your MCP server config: 
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@some/mcp-server"],
      "env": {
        "NODE_OPTIONS": "--import @codezero-io/cordon/register"
      }
    }
  }
}
Python MCP servers using requests or httpx will respect HTTPS_PROXY automatically if it’s set in the environment.

​
New routes not taking effect

Cordon loads routes at startup. If you add or change routes in cordon.toml, restart the proxy (secrets are fetched per-request and don’t require a restart): 
# If running manually
# Ctrl+C, then:
cordon start

# If running as a service
cordon service stop claude-code && cordon service start claude-code

​
401 Unauthorized errors

  1. Verify the secret is stored: cordon secret set ROUTE_NAME
  2. Check the auth type: Anthropic uses type: api_key with header_name: x-api-key, not type: bearer
  3. Check the secret source: Secrets are fetched per-request — if you changed a secret, the next request picks it up automatically