Connecting MCP Servers to Claude Code

Adding servers

bash

# Remote server over HTTP (most hosted services)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote server with an auth header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

# Local stdio server: everything after -- is the command that launches it
claude mcp add --transport stdio --env AIRTABLE_API_KEY=$KEY airtable -- npx -y airtable-mcp-server

The pattern is claude mcp add [options] <name> <url> for remote servers, and claude mcp add [options] <name> -- <command> [args] for local ones.

Scopes: who gets the server?

Scope	Flag	Stored in	Shared?
local (default)	`--scope local`	`~/.claude.json`, this project only	No
project	`--scope project`	`.mcp.json` in the repo root	Yes, via git
user	`--scope user`	`~/.claude.json`, all your projects	No

Use project scope for servers the whole team needs. It writes .mcp.json:

.mcp.json

{
  "mcpServers": {
    "sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" },
    "db": {
      "command": "npx",
      "args": ["-y", "@example/postgres-mcp"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

${VAR} expands from each developer's environment, so secrets stay out of git. ${VAR:-default} supplies a fallback. For safety, Claude Code asks each person to approve project-scoped servers before they're used.

Never commit secrets in .mcp.json

Use ${ENV_VAR} references for tokens and keys. The file is shared, but the values come from each developer's own environment.

Authentication

Many hosted servers use OAuth. After adding one, run /mcp in a session, select the server and sign in through your browser. From the shell, claude mcp login <name> does the same, and claude mcp logout <name> revokes it.

Managing servers

bash

claude mcp list          # all servers with status: ✔ Connected, ! Needs authentication…
claude mcp get sentry    # details for one server
claude mcp remove sentry

Inside a session, /mcp shows status, tool counts and authentication, and lets you reconnect, enable or disable servers. /context all shows how much context each server's tools use.

▶Watch it runUsing a connected server

Using a connected server

⌨Type the command+15 XP

Add a remote HTTP server named "notion" at https://mcp.notion.com/mcp

Check your understanding

?Lesson quiz10 XP per correct answer · +25 for a perfect score

QUESTION 1 OF 4

Which scope shares a server with your team through git?

Why: Project scope writes .mcp.json in the repo root.

QUESTION 2 OF 4

How should tokens appear in a committed .mcp.json?

Why: Environment variable expansion keeps secrets out of version control.

QUESTION 3 OF 4

In claude mcp add ... airtable -- npx -y airtable-mcp-server, what does -- separate?

Why: Everything after -- is passed unchanged as the server's command.

QUESTION 4 OF 4

Which in-session command shows MCP server status and handles OAuth sign-in?

Why: /mcp manages servers, including authentication.

0 / 4 correct

Connecting MCP Servers to Claude Code

🎯 By the end of this lesson you'll be able to

Adding servers

Scopes: who gets the server?

Authentication

Managing servers

Check your understanding

Unlock lesson 27 and the next 13

Key takeaways

Nice work. Lesson 27 done?