---

name: mcp-client-config description: Use when connecting an MCP server to a client (Claude Code, an IDE, or a custom agent), choosing a transport, scoping the server, passing credentials safely, and debugging a server that shows up disconnected.

MCP Client Configuration

When to trigger

Adding an MCP server to a client's config, deciding local vs project vs user scope, or fixing a server that registers but never connects.

Pick the transport

• stdio: the client launches the server as a subprocess and speaks JSON-RPC over stdin/stdout. Best for local tools you run yourself. Fastest to set up.
• HTTP (streamable): the server runs as a service and the client connects over a URL. Best for shared or remote servers and anything you do not want every user to install.

Minimal stdio registration

{
  "mcpServers": {
    "orders": {
      "command": "node",
      "args": ["./servers/orders/dist/index.js"],
      "env": { "DATABASE_URL": "postgres://..." }
    }
  }
}

Pass secrets through env, never in args. Arguments show up in process listings and shell history; environment variables do not.

Scope deliberately

• Project scope (checked-in config) shares the server with everyone on the repo. Use it for servers the whole team needs, and reference secrets by env var name, not literal value.
• User or local scope keeps a server private to your machine. Use it for anything with a personal credential.

Debugging a server that will not connect

1. Run the exact command plus args yourself in a terminal. If it does not start standalone, the client cannot start it either.
2. Check for stray stdout: on a stdio server, any non-protocol write to stdout (a console.log, a banner) corrupts the JSON-RPC stream and the client reports it disconnected. All logging goes to stderr.
3. Confirm the runtime and path. A relative args path resolves against the client's working directory, not the config file. Prefer an absolute path or a documented cwd.

Pitfalls

• A secret in args leaks into process listings. Use env.
• Committing a project-scope config with a literal API key ships the key to the repo. Reference an env var and document it.
• A server that logs to stdout looks broken to the client for a reason that never appears in its own logs. Route logging to stderr.