MCP configuration

Configure MCP for Coding Agents

Configure MCP servers safely for Codex, Claude Code, and Cursor by choosing stdio or HTTP, scoping credentials, limiting tools, and verifying connections.

Last verifiedAugust 13, 2026

Quick answer

Use stdio for a local process and Streamable HTTP for a remote server. Add one server at a time, pass secrets through environment variables rather than committed values, start with read-only tools or prompted writes, and verify both connection status and the expected tool list before trusting it with real data.

Choose the right scope

ChoiceUse it forAvoid it for

stdio

A local executable or package launched as a child process.

A hosted service that should be shared by remote clients.

Streamable HTTP

A remote service addressed by URL with OAuth or token authentication.

Wrapping a local command in an unnecessary network service.

User scope

A trusted personal server useful across repositories.

Project-specific configuration teammates must reproduce.

Project scope

A reviewed server definition tied to one trusted repository.

Committed credentials or private machine paths.

Configuration 1

Choose transport before copying configuration

The transport determines whether the client launches a process or connects to an address.

For stdio, verify the executable, arguments, working directory, environment, and startup behavior independently.
For HTTP, verify the exact URL, TLS, DNS, proxy behavior, authentication method, and service availability.
Do not treat an OAuth error as a stdio startup error or the reverse.

Configuration 2

Configure and inspect MCP in Codex

Codex stores personal MCP configuration in `~/.codex/config.toml` and supports trusted project scope in `.codex/config.toml`.

Use `codex mcp login <name>` for a configured OAuth server.
Use `/mcp` inside the TUI to inspect active servers.
Prefer `env_vars` or an environment-backed token setting over literal credentials.

Add and inspect a stdio server

codex mcp add docs -- npx -y example-mcp-package
codex mcp list
codex mcp get docs --json

config.toml with prompted writes

[mcp_servers.docs]
command = "npx"
args = ["-y", "example-mcp-package"]
enabled_tools = ["search", "read"]
default_tools_approval_mode = "writes"
startup_timeout_sec = 20

Important: Codex CLI, IDE extension, and ChatGPT desktop app share MCP configuration for the same Codex host.

Configuration 3

Limit credentials and tool authority

An MCP connection can expose data and actions beyond the repository. Tool visibility and approval policy are part of configuration, not an afterthought.

Never commit bearer tokens, API keys, cookies, or private credentials.
Allow-list only the tools needed for the workflow.
Prompt for writes or require approval per sensitive tool.
Test with non-production data and a read-only action first.
Treat server instructions as guidance, not a substitute for client-side permissions.

Configuration 4

Verify status, tools, and one safe operation

A connected label is insufficient if the server exposes zero tools or the wrong capabilities.

Confirm the resolved server name, transport, command or URL, and auth state.
Check that the expected tools appear and unexpected write tools do not.
Run one read-only operation, inspect its returned data, then decide whether to enable writes.

Codex checks

codex mcp list --json
codex mcp get <name> --json

Claude Code checks

/mcp
# If connected with zero tools:
claude --debug=mcp

Validation checklist

Run the server command independently when using stdio.
List the client-resolved configuration and redact it before sharing logs.
Confirm a non-zero expected tool list.
Exercise one read-only tool with non-sensitive data.
Verify write-capable tools prompt or follow the intended approval policy.
Restart the client after configuration changes when its documentation requires it.

Common configuration mistakes

Server works only from one directory

Use an explicit working directory or absolute local script paths.

Server starts without credentials

Pass environment variables in the server configuration and verify the client forwards them.

Connected with zero tools

Reconnect and inspect server stderr or client debug logs.

Every server tool is automatically available

Use tool allow-lists and prompt or approve policies for writes.

Related paths

All configuration guides

Official sources

Loading order, configuration formats, and commands were checked on August 13, 2026. Recheck official documentation before enforcing a configuration across a team.