Keep API Secrets Out of Agent Config Files

Inventory values before moving files

Start with the MCP entry someone would paste into a setup ticket. Inspect its headers, environment map, command arguments and URL. Record which fields contain reusable credentials, which contain references, and which are ordinary connection settings. A database password embedded in a connection string belongs in the credential column even when the field is called url.

Make the inventory without copying secret values: record the config path, server name, credential owner, permitted systems and replacement mechanism. Include personal overrides as well as repository files. The migration is incomplete if the shared example is clean but onboarding still asks developers to paste an upstream token into a local config.

Choose where each credential will be resolved before editing the entry. OWASP warns that environment variables can surface in logs or dumps; runtime injection reduces exposure in configuration files but still delivers the value to a process. If the requirement is to keep a database password off the agent machine entirely, changing its JSON field into an environment reference does not meet it.

Claude Code: share a reference or use MCP sign-in

Anthropic documents environment expansion in .mcp.json, including HTTP authentication headers. For a remote server accepting bearer authentication, this project configuration contains a variable name rather than a credential. The example URL is a placeholder for your approved endpoint.

{
  "mcpServers": {
    "companyTools": {
      "type": "http",
      "url": "https://tools.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${COMPANY_MCP_TOKEN}"
      }
    }
  }
}

Supply COMPANY_MCP_TOKEN through your approved launcher or secret delivery mechanism before starting the client. Do not replace the reference with a literal value to fix a connection error. Also avoid adding a working credential as a default value in the template.

For a server supporting OAuth, add its URL without a token argument and authenticate through /mcp:

claude mcp add --transport http companyTools https://tools.example.com/mcp

Choose either the project entry or the CLI registration for this connection, rather than installing duplicate definitions. The sign-in route keeps a manually pasted bearer value out of the setup command. Verify that the account and requested permissions match the intended tool access.

Codex: name the token variable in TOML

Official OpenAI documentation places MCP settings in ~/.codex/config.toml, with project configuration available in trusted projects at .codex/config.toml. For a Streamable HTTP server, bearer_token_env_var names the environment variable whose value supplies the Authorization bearer token:

[mcp_servers.companyTools]
url = "https://tools.example.com/mcp"
bearer_token_env_var = "COMPANY_MCP_TOKEN"

This is a variable name, without Claude Code's ${...} wrapper. Do not substitute the actual token into that setting or move it into a static http_headers entry. When the server supports OAuth, codex mcp login companyTools starts its sign-in flow.

Document provisioning beside the template: who can obtain the credential, which launcher supplies it and how replacement works. A teammate should be able to inspect the TOML in a review without receiving access. Keep the provisioning instructions free of example values that are actually live.

VS Code: keep prompted values outside mcp.json

For a Local harness using the VS Code configuration format, .vscode/mcp.json can define an input prompt and reference it from an HTTP header. Microsoft's configuration reference documents password as hiding typed input and says prompted values are securely stored for subsequent use.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "company-token",
      "description": "Company MCP access token",
      "password": true
    }
  ],
  "servers": {
    "companyTools": {
      "type": "http",
      "url": "https://tools.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:company-token}"
      }
    }
  }
}

This example uses the VS Code servers object. Portable Copilot configuration uses mcpServers and does not support these input variables; servers requiring interactive inputs are not forwarded to Copilot harness sessions. Confirm the harness before copying the example. A masked prompt is useful only when the client consuming the file supports it.

For onboarding, name the supported configuration destination explicitly. Asking teammates to save an unspecified mcp.json invites them to troubleshoot a format mismatch by pasting the credential into a header.

Replace exposed credentials before cleaning copies

If a populated config has already reached a repository or an unintended recipient, treat the credential as exposed. GitHub's removal guidance puts revocation or rotation first. Deleting the current file does not invalidate a token, and rewriting repository history cannot erase copies held in other people's clones.

1. Identify the issuer and revoke the exposed credential. Record its identifier and exposure window without reproducing its value.
2. Create a replacement with the permissions the agent actually needs. Provision it through the chosen runtime mechanism, leaving only its reference in the config.
3. Restart or reconnect affected clients and verify an allowed lookup using the replacement. Confirm the old credential is rejected.
4. Remove populated examples and coordinate any repository-history cleanup with maintainers. Check setup tickets and onboarding snippets for the same copied value.

For a planned migration without evidence of exposure, arrange the cutover with the credential owner so dependent clients do not unexpectedly lose access. Do not leave the previous key active indefinitely as a rollback mechanism. Write down a deadline and the test that permits revocation.

Separate the two tasks in the change record: replacing credentials and removing copies. For the wider access cleanup, use revoking an agent's access in one place.

Keep upstream secrets behind SPYN3

SPYN3 provides one MCP endpoint per workspace at https://api.spyn3.com/agent/mcp. Upstream OAuth tokens, database passwords and API tokens stay in the workspace with envelope encryption and never reach the agent, browser or logs. The agent holds a SPYN3 API key or OAuth token. An admin can limit a key to selected sources; writes require the separate call:write_tools grant. Configure one connection, issue a scoped agent credential and keep only its reference in the client config. Revoking a key takes effect on the next call.

Prove the template can travel without granting access

Review the result from a fresh checkout and a fresh client session. The acceptance question is concrete: can someone receive this configuration without receiving a working credential? Run these checks with a test account and a harmless lookup rather than production mutations.

• Inspect the artifact. Review the saved JSON or TOML and the proposed diff. They should contain the approved endpoint and references, with no populated headers, password-bearing URLs or secret defaults.
• Remove the credential. Use a session without injected credentials or saved sign-in state. Confirm protected tools cannot be used. Do not infer rejection merely because the client displays a missing-variable warning.
• Provision separately. Deliver the test credential through the documented mechanism and repeat the lookup. Inspect the actual tool result, rather than accepting a plausible generated answer as proof of access.
• Inspect diagnostics. Check startup errors, connection logs and troubleshooting exports for the test secret before sharing them. Do not ask the agent to print its environment to diagnose authentication.
• Revoke and repeat. Revoke the test credential and verify that another protected lookup fails. Keep the result with the onboarding instructions.

Review changes to endpoint URLs as carefully as changes to credential references: a clean-looking template still decides where the client sends authentication. When several agents need the same tools, continue with one scoped key per agent so sharing configuration does not become sharing identity.