Secret Handling For MCP Servers And Agent Tools

TL;DR

MCP servers and Agent SDK tools are secret touchpoints: credentials arrive through environment variables, HTTP headers, OAuth flows, and handler code. Keep committed configs free of raw secrets, pin OAuth scopes, prefer local scope for personal tokens, and assume tool arguments and results will reach the model unless you redact them first.

Prerequisites & Requirements

• {"task": "Credential inventory", "description": "Every MCP server and custom tool lists which secrets it reads, stores, or forwards"}
• {"task": "Config review", "description": ".mcp.json, plugin MCP entries, and SDK mcpServers blocks are scanned for hardcoded tokens"}
• {"task": "Scope policy", "description": "OAuth scopes and API tokens are narrowed to the minimum tools each workflow needs"}
• {"task": "Rotation path", "description": "Owners know how to revoke OAuth tokens, rotate env vars, and remove servers"}
• {"task": "Redaction rules", "description": "Prompts and tool outputs forbid pasting live secrets into issues, PRs, or logs"}

Core Concepts Explained

Three secret paths in MCP configs

Claude Code MCP documentation describes credentials flowing through:

1. Stdio env blocks and --env flags — values are injected into the server process environment.
2. HTTP headers and Bearer tokens — often expanded from ${VAR} in .mcp.json.
3. OAuth tokens — obtained via /mcp, stored in the system keychain (macOS) or a credentials file, and refreshed automatically.

Each path needs different rotation and sharing rules.

Env expansion keeps secrets out of git

.mcp.json supports ${VAR} and ${VAR:-default} in command, args, env, url, and headers. Teams can commit structure while developers export secrets locally. If a required variable has no default and is unset, Claude Code fails to parse the config—an intentional fail-closed behavior.

Local scope isolates personal credentials

Local-scoped servers live in ~/.claude.json under the project path and do not sync to teammates. Use local scope for experimental servers or credentials that must not enter version control, while project scope carries shared non-secret structure.

OAuth scopes are a supported least-privilege pin

MCP documentation describes oauth.scopes as a space-separated string that pins requested scopes when the authorization server advertises more than you want to grant. Widen scopes only when a tool returns insufficient_scope.

Agent SDK tools multiply context exposure

Custom Agent SDK tools document that descriptions, validated arguments, and handler content arrays are visible to the model each turn. Secrets placed in schemas, descriptions, or sample tool results become session data—not just env vars on disk.

Step-by-Step Implementation Guide

1. Inventory servers and tools. List each MCP server transport, each custom SDK tool, and every secret name (API keys, PATs, OAuth clients, DB URLs).

2. Replace committed secrets with placeholders. Move raw values to env vars or secret stores; reference them with ${VAR} in .mcp.json headers and env blocks.

3. Choose scope deliberately. Put shared structure in project .mcp.json; keep personal tokens in local scope or user settings.

4. Pin OAuth scopes. Add oauth.scopes for remote servers that need only a subset of advertised permissions.

5. Validate Agent SDK handlers. Ensure handlers read secrets from process env or secure stores—not from prompts—and return redacted errors via isError.

6. Test in a sandbox profile. Connect servers with synthetic credentials before granting production access.

7. Document rotation. Record which store holds each secret, who rotates it, and how to revoke OAuth via /mcp Clear authentication.

8. Audit transcripts and exports. Scan session logs and MCP tool output for accidental secret paste before sharing externally.

Configuration Patterns

HTTP header from environment (committed template)

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Export API_KEY locally; never commit the value.

Stdio server with scoped env

claude mcp add --env AIRTABLE_API_KEY --transport stdio airtable -- \
  npx -y airtable-mcp-server

Place --env before the server name per CLI rules; pass secrets only from your shell or secret store.

OAuth scope pin

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

Agent SDK Tool Rules

• Read credentials inside handlers from environment variables or your vault SDK.
• Keep tool descriptions operational, not credential-bearing.
• Return { isError: true, content: [...] } with redacted messages instead of echoing upstream API errors that include tokens.
• Cap allowedTools to named mcp__server__tool entries rather than wildcards when tools can reach sensitive systems.

Troubleshooting

Config fails to parse at startup

Confirm every ${VAR} without a default is exported in the shell that launches Claude Code.

OAuth works locally but not for teammates

OAuth client secrets belong in keychain/credentials storage or CI secrets—not in shared .mcp.json. Each developer completes /mcp auth or uses managed CI tokens.

Tool output triggers secret scanner alerts

Redact handler responses; avoid returning full upstream JSON that includes auth headers or session cookies.

Secrets appeared in a committed file

Rotate immediately, purge from git history per your policy, and switch the config to ${VAR} expansion.

Source Verification Notes

Verified against Claude Code MCP and security documentation on 2026-06-16:

• MCP docs describe ${VAR} expansion in .mcp.json, --env for stdio servers, OAuth token storage in keychain/credentials files, and oauth.scopes pinning.
• Security docs describe secure credential storage in macOS Keychain and file permissions on other platforms, plus trust verification for new MCP servers.
• Agent SDK custom-tools docs describe tool schemas and content results entering model context and recommend isError instead of throwing on failures.

Duplicate Check

This guide complements threat-model-mcp-servers-before-installation (pre-install trust review), mcp-server-auth-least-privilege (building servers with auth boundaries), and auditing-mcp-client-configuration-before-team-rollout (config audits). Those entries do not provide a unified secret-handling workflow spanning MCP connection configs and Agent SDK custom tools. Rules in ai-assistant-secret-handling-rules target general coding assistants, not MCP/OAuth operational patterns.

References

• Claude Code MCP - https://code.claude.com/docs/en/mcp
• Claude Code security - https://code.claude.com/docs/en/security
• Agent SDK custom tools - https://code.claude.com/docs/en/agent-sdk/custom-tools