How to add an MCP server to Claude Code

TL;DR. Updated August 2026. Run claude mcp add --transport http {name} {url} from any terminal; for a server that wants a token, append --header "Authorization: Bearer {token}". Claude Code registers the MCP server immediately, no restart needed. Verify with claude mcp list. For Hatchable the command is claude mcp add --transport http hatchable https://hatchable.com/mcp; sign-in happens in a browser tab (OAuth, no token to manage).

What is an MCP server?

An MCP server (Model Context Protocol) is an external tool that Claude Code can call: search a database, deploy an app, query an API. MCP is the open protocol Anthropic uses to let Claude Code talk to tools without custom integrations for each one. Any service that speaks MCP is pluggable.

Hatchable's /mcp endpoint exposes tools for creating projects, deploying code, running queries against the project database, and more, all of it available to Claude Code once you register the server.

Before you start

• Claude Code installed. If you don't have it yet: npm install -g @anthropic-ai/claude-code then claude login to connect your Anthropic account.
• A bearer token, if the server uses token auth. Hatchable doesn't need one: the first connection opens a browser tab on hatchable.com to sign in, and approving creates your free account (no card). Some other servers hand you a token to pass in a header; the command for that is below.

Add the server

1. Run claude mcp add with the server URL

   Claude Code accepts MCP servers on the HTTP transport with a single command. For Hatchable:

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

   On first use Claude Code opens an OAuth tab to sign you in (on recent versions you can also run claude mcp login hatchable to do it right away). For a provider that issues a static token instead, the format is the same plus a header:

   claude mcp add --transport http example https://mcp.example.com/mcp \
     --header "Authorization: Bearer YOUR_TOKEN"

2. Verify it registered

   claude mcp list

   You should see hatchable (or whatever name you gave it) in the output, listed as connected. If it's missing, the add step returned an error you'll want to scroll back and read.

3. Try it from inside a Claude Code session

   Open any Claude Code session and ask a question that requires the server. For Hatchable, try:

   claude "Create a new Hatchable project called hello-world and deploy a page that says hi."

   Claude Code will call the MCP server's tools in response. First time through it will ask for permission to invoke each tool; accept, or add --allowedTools to your shell alias if you trust the server.

The transport, header and scope flags

The one-liner above has three flags that do all the work. Checked against Anthropic's Claude Code documentation and the CLI's own --help as of August 2026 (Claude Code 2.1.x); if your build is much older, run claude mcp add --help and compare.

--transport http

Claude Code defaults to stdio, a local server it launches as a subprocess. Any server you reach by URL needs --transport http (short form -t http), which is the Streamable HTTP transport in MCP terms; --transport sse is the older Server-Sent Events transport and only worth using if a server offers nothing else. If you configure servers by JSON instead (.mcp.json or claude mcp add-json), the type field accepts streamable-http as an alias for http, so configs copied from a server's docs work unchanged.

--header "Authorization: Bearer ..."

For servers that authenticate with a static token, pass it as a header (short form -H, repeatable for several headers):

claude mcp add --transport http example https://mcp.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Two things to know. Claude Code saves the config without checking the token, so a typo only shows up later as Failed to connect with a 401. And if a server supports OAuth, leave the header off: a configured Authorization header that the server rejects is reported as a failure, not a fall-through to the OAuth flow. Hatchable is OAuth, so no header.

--scope local | project | user

So "global MCP" in Claude Code is --scope user (short form -s user). Project-scoped servers prompt each teammate for approval the first time Claude Code sees them in .mcp.json, which is the right default for anything checked into a repo. When the same name exists at more than one scope, local wins over project, which wins over user. Some worked examples:

# token-based server, available in every project
claude mcp add --transport http --scope user example https://mcp.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# OAuth server (Hatchable), shared with the team via .mcp.json
claude mcp add --transport http --scope project hatchable https://hatchable.com/mcp

claude mcp list                 # every server with its health status
claude mcp get hatchable        # one server, with the failure detail if any
claude mcp remove hatchable     # add --scope if it exists at more than one

Inside a session, /mcp shows the same list, lets you toggle a server off without deleting it, and runs the OAuth sign-in for servers that need it. See also the Hatchable how-to for Claude Code and, for the protocol itself, what MCP is.

Removing or updating a server

Remove with claude mcp remove {name}. To update (for example, to rotate a token), remove and re-add: current versions refuse to add a name that already exists at the same scope, so claude mcp remove comes first.

Troubleshooting

Claude Code says "MCP server failed to connect"

Most often this is a transport mismatch. Make sure you passed --transport http for Hatchable; without it, Claude Code tries the default (stdio) and can't find a local binary to launch. Other common causes:

• Token expired or revoked (token-based servers). Remove the server and re-add it with a fresh token. For an OAuth server such as Hatchable, re-authenticate with claude mcp login hatchable or from the /mcp panel inside a session; the sign-in page is hatchable.com.
• Typo in the URL. The endpoint is https://hatchable.com/mcp, not /mcp/ with a trailing slash.
• Behind a corporate proxy. Claude Code honors the standard HTTPS_PROXY env var; if your workplace uses a TLS-inspecting proxy, add it before running claude mcp add.

The server is listed but tools aren't showing up

Run claude mcp list, then claude mcp get hatchable (or whatever you named it) for the detail. A server that shows Failed to connect usually reports a 401 (bad token) or 404 (wrong URL) on its Issue: line; Needs authentication means the OAuth sign-in hasn't happened yet, so run claude mcp login for it or open /mcp in a session. If the URL was wrong, remove the server and re-add it with the correct value.

I want Claude Code to auto-approve tools

Pass --allowedTools mcp__hatchable__* to claude when launching, or add it to a .claude/settings.json in the project. Only do this for servers you fully trust; the whole point of the prompt is to give you a chance to refuse.