How to Set Up an MCP Server (Any Coding Agent)

Steps

1. 01

   Pick the transport: stdio, HTTP, or SSE

   Every MCP server uses one of three transports. stdio launches a local process and talks over stdin/stdout — this is most npm-packaged servers. HTTP connects to a hosted endpoint over request/response. SSE (Server-Sent Events) connects to a hosted endpoint that streams events. Use stdio for local tools; use HTTP or SSE for hosted services. Check the server's own docs for which it supports.

   # stdio  -> local process (e.g. npx a-package)
   # http   -> remote URL, request/response
   # sse    -> remote URL, streamed events

2. 02

   Add a server in Claude Code

   Claude Code uses claude mcp add. Pass a stdio command after --, or use --transport http/sse with a URL. Inject secrets with -e KEY=value (stdio) or --header (remote). Claude Code has three scopes via -s: local (default, this project, private), user (all sessions), and project (written to .mcp.json, shared with the repo and approved per-developer).

   # stdio (local), default 'local' scope
   claude mcp add my-server -- npx my-mcp-server
   
   # stdio with an env var, available in every session
   claude mcp add -s user my-server -e API_KEY=xxx -- npx my-mcp-server
   
   # remote HTTP with a bearer token
   claude mcp add --transport http my-server https://example.com/mcp --header "Authorization: Bearer <token>"
   
   # manage
   claude mcp list && claude mcp get my-server

3. 03

   Add a server in OpenCode

   OpenCode uses opencode mcp add with a name. Pass --url for a remote server, --header for HTTP headers, or --env for a local server's environment variables. For OAuth-based servers (e.g. GitHub), run opencode mcp auth <name> after adding; opencode mcp debug <name> helps when auth succeeds but tools do not appear.

   # remote HTTP server with an auth header
   opencode mcp add github --url https://mcp.example.com/github --header Authorization="Bearer <token>"
   
   # local server with an env var
   opencode mcp add my-server --env API_KEY=your_key_here
   
   # verify / authenticate
   opencode mcp list
   opencode mcp auth github

4. 04

   Add a server in Codex CLI

   Codex CLI uses codex mcp add: a stdio command after --, or --url for a streamable HTTP server. Servers are written to ~/.codex/config.toml (command + args keys; env in a nested table). For OAuth servers use codex mcp login <name>; for token servers pass --env or --bearer-token-env-var. Run codex doctor if a server stops appearing.

   # stdio server
   codex mcp add context7 -- npx -y @upstash/context7-mcp
   
   # remote HTTP server with a token env var
   codex mcp add github --url https://api.githubcopilot.com/mcp --bearer-token-env-var GITHUB_PAT
   
   # manage
   codex mcp list && codex mcp get context7

5. 05

   Verify the server is connected

   After adding, confirm the agent can see the server's tools. In Claude Code, run /mcp inside the session (or claude mcp list from the shell). In OpenCode, run opencode mcp list. In Codex CLI, run codex mcp list and codex doctor. Then ask the agent what tools it has, or give it a task that uses the new server.

   # Claude Code (inside the session)
   /mcp
   
   # OpenCode / Codex (shell)
   opencode mcp list
   codex mcp list

6. 06

   Keep secrets out of config, and avoid tool bloat

   Never hard-code API keys in shared config (.mcp.json, config.toml). Reference environment variable names instead and set the values in your shell or a gitignored .env. And connect only the 2-3 servers you actually need: practitioners report that more than 5-7 connected servers floods the tool list and degrades the agent's tool selection. Remove servers you are not using.

   # remove a server you are not using
   claude mcp remove my-server
   opencode mcp logout github   # clears OAuth creds (OpenCode)
   codex mcp remove github

Troubleshooting

The server command is 'not found' when the agent starts it

stdio servers must be resolvable on the PATH the agent sees at startup, which can differ from your interactive shell. Use npx <package> so it resolves at runtime, or install the package globally and confirm with npm list -g. Add the npm global bin to your PATH in your shell profile and restart the agent.

Tools from the server never appear

Check the server registered (claude mcp list / opencode mcp list / codex mcp list). For project-scope servers in Claude Code's .mcp.json, approve them when prompted (or run claude mcp reset-project-choices). For OAuth servers, complete opencode mcp auth <name> or codex mcp login <name>. Confirm the server process starts on its own outside the agent.

A remote (HTTP/SSE) server returns 401

Verify the token and header format. Many servers require the header to be exactly Authorization: Bearer <token>. Inspect what you stored (claude mcp get <name> / codex mcp get <name>), regenerate the token if it expired, and re-add. Confirm the exact header the server expects in its own docs.

The agent gets worse after you add several servers

This is tool bloat: connecting more than ~5-7 servers overflows the tool list the model can reason about, causing wrong or ignored tool calls. Keep 2-3 servers active for a given task and remove the rest (claude mcp remove / codex mcp remove). Re-add them when you actually need them.