Connect Claude Code to MCP servers (GitHub and Playwright)

Claude Code can read and edit your files, but MCP servers let it reach beyond them: open a real browser, read GitHub issues, query your database. MCP (Model Context Protocol) is an open standard for plugging tools into AI apps. A tool that speaks it is an MCP server, and Claude Code is the client.

This guide explains how Claude Code's claude mcp commands work, then connects two useful servers. It assumes Claude Code is installed. If you use Cursor, see add your first MCP server to Cursor instead.

The three kinds of server

Servers connect to Claude Code in one of three ways (called transports):

Which one you need is spelled out in each server's install instructions.

The command, decoded

All servers are added with claude mcp add. The shape depends on the type.

A hosted (HTTP) server:

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

A local (stdio) server:

claude mcp add <name> -- <command> [args...]

That double dash (--) matters. Everything before it is for Claude Code (like --env or --scope); everything after it is the exact command used to start the server and is passed along untouched. Without it, flags meant for the server could be mistaken for Claude's own.

To pass a secret to a local server, add --env KEY=value (or -e) before the name:

claude mcp add --env MY_KEY=abc123 --transport stdio my-server -- npx -y some-mcp-package

One quirk from Anthropic's docs: if a server name comes directly after --env, the CLI reads it as another key-value pair and fails, so put another option, such as --transport stdio, between them as above.

Scopes: who gets the server?

Use --scope (or -s) to choose who can use a server:

A project scope server is written to a .mcp.json file that you can commit so teammates get the same setup. Claude Code asks each person to approve project servers the first time, as a safety check.

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

In this file you can use ${VAR} or ${VAR:-default} to read environment variables, so tokens stay out of the committed file.

Example 1: Playwright (a local browser)

Playwright's server from Microsoft lets Claude drive a real web browser: open your site, click around, take screenshots. It's great for checking what you've just built. It needs Node.js 18 or newer.

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

Confirm it's connected:

claude mcp list

Then start claude and try:

Open http://localhost:4321 in the browser, click through the main navigation and tell me if any page looks broken.

Claude will ask permission to use the browser tools, then report what it saw.

Example 2: GitHub

GitHub's official server lets Claude work with repositories, issues and pull requests. You'll need a personal access token (PAT): a password-like key that lets a program act on your behalf.

Make a token

1. In GitHub, open Settings, then Developer settings, then Personal access tokens.
2. Create a token. GitHub's docs suggest the repo, read:packages and read:org scopes for this server. Choose the narrowest access that does the job, and set an expiry date.
3. Copy it somewhere safe. You only see it once.

Add the hosted server

GitHub's installation guide for Claude Code (version 2.1.1 or newer) uses this form:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

Replace YOUR_GITHUB_PAT with your token. For older versions of Claude Code, GitHub documents:

claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_GITHUB_PAT"

Or run it locally with Docker

If you have Docker installed, you can run the server on your own machine instead:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Note the old npm package @modelcontextprotocol/server-github is deprecated. Use GitHub's own server.

Try it

List the open issues in my repository and suggest which three to tackle first.

Managing your servers

These commands cover everyday upkeep:

claude mcp list          # show all configured servers
claude mcp get github    # show details for one server
claude mcp remove github # remove a server

Inside a Claude Code session, type /mcp to see server status and to sign in to servers that use OAuth (a browser-based "log in with…" flow). There are also claude mcp login <name> and claude mcp logout <name>.

If you'd rather paste a full JSON definition than build a command, claude mcp add-json <name> '<json>' accepts one directly, as in the GitHub example above.

Which servers are worth adding first?

Don't install everything. Each server adds tools Claude has to consider. Start with one or two that match a job you actually do:

• Building a website? Playwright to test it, Context7 for current docs.
• Working with a team? GitHub or Linear.
• Using a database? Supabase's server, pointed at a dev project and set to read-only.

Browse the whole MCP directory.

Staying safe

MCP servers can take real actions, so treat them with care:

• Use servers from sources you trust. Official ones from the vendor or the reference servers are the safest.
• Least privilege. Create tokens with minimum permissions and expiry dates. Use read-only modes where offered.
• Don't commit secrets. Use --env or ${VAR} references rather than pasting tokens into .mcp.json.
• Dev data only. Point database servers at development copies, not production.
• Read approval prompts. Claude asks before using tools. Read what it's about to do.
• Be careful with content from the web. A fetched page can contain instructions aimed at the AI. Don't let it act on anything you didn't ask for.

Troubleshooting

claude mcp list shows the server as failed. Run the server's command directly in a terminal to see the error. Missing Node.js, Docker or uv is the usual cause.

"The server doesn't appear in my session". Start a fresh claude session after adding it. For project servers, approve it when prompted. If you rejected it by mistake, claude mcp reset-project-choices resets your decisions.

Authentication fails. For OAuth servers, run /mcp and authenticate. For token servers, check the token hasn't expired and has the right scopes.

Flags are being swallowed. For stdio servers, make sure the -- separator sits between Claude's options and the server command.

Recap

1. Hosted server: claude mcp add --transport http <name> <url>.
2. Local server: claude mcp add <name> -- <command> <args>.
3. Choose a scope: local, project (shared via .mcp.json) or user.
4. Check with claude mcp list and /mcp.
5. Keep tokens minimal and secret.