MCP lives in my terminal now

Most of my MCP usage is not in a chat window — it is in Claude Code, where the servers I add become tools the agent can use while it works in my repo. Here is the workflow I have settled on after a year of living in it.

Adding a server: mind the dashes

The command is claude mcp add, and it handles both remote and local servers. A remote, OAuth-backed server is one line:

claude mcp add --transport http notion https://mcp.notion.com/mcp

For a local stdio server there is one piece of syntax everyone trips on: a bare -- separates Claude's own flags from the command that launches the server. Everything after -- is the server's command line:

claude mcp add --env API_KEY=sk-xxx --transport stdio my-server -- uvx my-mcp-server

Forget the -- and Claude tries to parse the server's flags as its own. It is the single most common mistake.

Scopes decide who sees the server

Every server is added at a scope, and the distinction matters more than it looks:

local (the default) — just you, just this project, stored in ~/.claude.json.
project — shared with the team via a .mcp.json file committed in the repo root.
user — available across all your projects.

The one I reach for most is project. Committing .mcp.json means a teammate clones the repo, runs Claude Code, and has the exact servers I do — no setup doc to drift out of date.

Keep secrets out of the committed file

A committed .mcp.json must not contain API keys. Claude Code expands environment variables inside it, so I reference them instead of pasting them:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

The ${VAR} and ${VAR:-default} syntax works in command, args, env, url, and headers. The file is safe to commit; the secret stays in my shell.

Using what you have wired up

Inside a session, /mcp opens a panel of every connected server, its tool count, and — for remote servers — a button to run the OAuth flow. Two features I use constantly:

Resources with @. Typing @github:issue://123 fetches that issue and attaches it to the conversation; @ autocompletes across every server.
Prompts as slash commands. A server's prompts appear as /mcp__github__pr_review, ready to invoke with arguments.

The settings nobody mentions

When a tool returns a lot — a big file listing, a verbose API response — Claude Code truncates it at MAX_MCP_OUTPUT_TOKENS, which defaults to 25,000. If a server's output keeps getting cut off, raise it. And when a slow server times out, MCP_TIMEOUT (startup) and MCP_TOOL_TIMEOUT (per call) are the knobs. Those three environment variables have saved me more debugging time than anything else.