Add MCP Server

Scope

Treat $ARGUMENTS as the MCP server to add: a name plus a launch command (for local stdio) or a URL (for remote Streamable HTTP), or a description of the capability you want. Restate in one sentence which server you're adding, by which transport, and at which scope before changing anything.

Goal: connect the server correctly and safely — right transport, right scope, secrets via environment variables (never inline), provenance vetted for third-party servers — and verify it actually connected before declaring success.

Step 1 — Detect how this project configures MCP

Look for existing MCP configuration: a checked-in .mcp.json (project scope), per-user config, or claude mcp usage. Match what's already there rather than introducing a second mechanism. Confirm whether the server should be local to this project, shared via a committed .mcp.json, or available across all the user's projects.

Step 2 — Choose the transport

Pick stdio for a local, single-user server the client launches as a child process; pick Streamable HTTP (with a URL) for a remote or shared server. State which and why — the transport determines whether auth is your concern (it is, for HTTP).

Step 3 — Choose the scope

Map the need to a scope: local/per-project for a personal addition, project (committed .mcp.json) for something the whole team should get, or user for a server you want everywhere. Note that a project-scoped server prompts each teammate to approve it before its tools activate.

Step 4 — Wire secrets through the environment

If the server needs tokens or keys, pass them via environment variables (e.g. --env GITHUB_TOKEN=... sourced from the environment), never hard-coded into a committed config. Confirm no secret is about to be written into .mcp.json or the repo.

Step 5 — Register it

Produce the exact registration command, options before the server name. For example:

# local stdio server
claude mcp add weather -- node ./weather-server/index.js
 
# remote Streamable HTTP server
claude mcp add --transport http --scope project linear https://mcp.linear.app/mcp

Step 6 — Verify the connection

Confirm the server actually connected and exposes what you expect: run claude mcp list (and /mcp inside a session) to check status and tools, or connect with the MCP Inspector to list and call a tool directly. A server that's "added" but not connected — or that exposes no usable tools — is not done.