Lesson 2

Adding Your First MCP Servers (GitHub, Notion, Supabase)

From Concept to Connected

Last lesson was the why. This one is the how. By the end you'll have a real tool plugged into Claude Code and you'll know how to verify it's working.

The whole flow has four steps, every time:

Find the server you want.
Add it with the claude mcp add command.
Authenticate — prove to the tool that you're allowed in.
Verify it connected with claude mcp list.

Let's walk through each.

Step 1: Finding a Server

Most popular tools either publish their own MCP server or have a well-known community one. The two formats you'll meet:

Remote (HTTP) servers — hosted by the tool's makers. You connect to a URL. Nothing to install. This is the modern, recommended kind, and it usually logs you in through your browser. GitHub and many others work this way.
Local (stdio) servers — a small program that runs on your machine. Claude starts it as a background process. These are launched with a command like npx ....

When you're choosing a server, prefer the official one from the tool's own docs. Anyone can publish an MCP server, and you're about to give it access to your account — so trust matters. (More on that in Lesson 4.)

A note on Claude.ai connectors: if you sign in to Claude Code with a Claude.ai account, some connectors (like Google Drive, Gmail, Notion, Supabase, Vercel) may already be available without any setup. Run /mcp inside a session to see what's there before adding anything manually.

Step 2: The `claude mcp add` Command

This is the workhorse command. You run it in your terminal (not inside a Claude session). Its shape changes slightly depending on the server type.

Adding a remote (HTTP) server

Use the --transport http flag and give the server a name plus its URL:

claude mcp add --transport http <name> <url>

For example, GitHub's MCP server. It needs a GitHub access token, which you pass as a header:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_TOKEN"

(You generate that token in GitHub under Settings → Developer settings → Personal access tokens. Give it only the permissions you need.)

Some remote servers don't need a token in the command at all — they log you in through your browser instead. For those, you add the bare URL and authenticate afterward:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Adding a local (stdio) server

Local servers are the default, so you don't need a --transport flag. The key detail is the -- separator: everything after the -- is the command that launches the server.

claude mcp add <name> -- <command-to-run-the-server>

For example, a browser-automation server:

claude mcp add playwright -- npx -y @playwright/mcp@latest

The -- matters. Without it, Claude tries to read the server's own flags as if they were its flags, and it breaks. When in doubt, put -- before the launch command.

If a local server needs a secret (like an API key), pass it with --env:

claude mcp add --env SOME_API_KEY=your_key_here myserver -- npx -y some-mcp-server

Don't have the exact command for a tool memorized? You shouldn't — copy it from that tool's official MCP docs. The flags above (--transport, --header, --env, --scope, --) are the real ones; the server name and URL/command come from the tool.

Step 3: Config Scopes — Who Gets This Server?

When you add a server, you choose where the configuration lives with the --scope flag. This decides who can use it.

Scope	Flag	Lives in	Who can use it
Local (default)	`--scope local`	Your personal config	Just you, just this one project
Project	`--scope project`	`.mcp.json` in the repo	Everyone who clones the repo
User	`--scope user`	Your personal config	Just you, across all your projects

How to choose:

Local is the safe default for experimenting. It's private to you and scoped to the current project.
User is for tools you want everywhere — say, you always want GitHub available no matter which project you're in.
Project is for tools the whole team needs. It writes to a file called .mcp.json that gets committed to the repo, so anyone who clones it gets the same connection.

Example — make GitHub available across all your own projects:

claude mcp add --scope user --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_TOKEN"

A Closer Look at `.mcp.json`

When you use --scope project, Claude writes a file like this to your repo root:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

This is human-readable, and because it's checked into git, your teammates get the exact same setup automatically.

One critical rule: never put real secrets (tokens, passwords) directly in .mcp.json — it's committed to the repo, where everyone can see them. Instead, reference an environment variable so each person supplies their own:

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

The ${GITHUB_TOKEN} is filled in from each person's own environment. We'll come back to secrets handling in Lesson 4.

Step 4: Authenticating

Adding a server isn't the same as being logged in. There are two common ways a server authenticates you:

Token in the command — like the GitHub example above, where you pasted a personal access token into the --header. Once it's added, you're authenticated.
Browser login (OAuth) — for servers that sign you in through their website. After adding, start a Claude session and run:
```
/mcp
```
This opens an interactive panel listing your servers. Pick the one that says it needs authentication, choose Authenticate, and a browser window opens for you to log in. When you're done, Claude stores the login securely (in your operating system's keychain, not in a plain file).

The /mcp panel is also where you go any time a server shows a connection problem — it explains what's wrong.

Step 5: Verifying It Worked

Back in your terminal, run:

claude mcp list

You'll see each server with a connection status. A healthy one looks like:

github  -  Connected

If something's off, you might see "Needs authentication" (run /mcp and log in) or "Failed to connect" (check the URL, your token, or your internet). To see full details for one server:

claude mcp get github

And to remove one you no longer want:

claude mcp remove github

Your First Connection: A Suggested Path

If you want one win right now, start with GitHub — it's the most useful for what you've been building:

Create a GitHub personal access token in GitHub's settings (give it minimal permissions).
Run the claude mcp add --transport http github ... command above with your token.
Run claude mcp list and confirm it says Connected.
Start a session and ask: "List the open issues on my [repo-name] repository."

If Claude comes back with your real issues, you've crossed the line from "Claude in a box" to "Claude connected to your world."

Summary

The flow is always: find → add → authenticate → verify.
Add servers with claude mcp add. Remote servers use --transport http <name> <url>; local servers use <name> -- <launch command> (the -- separator is required).
Scopes decide who gets the server: local (you, this project), user (you, all projects), project (everyone via a committed .mcp.json).
Authenticate either with a token in the command or by running /mcp and logging in through the browser.
Verify with claude mcp list; inspect with claude mcp get <name>; remove with claude mcp remove <name>.
Never commit real secrets to .mcp.json — reference an environment variable instead.