.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Out of the box, Claude Code can read files, run shell commands and search your repo. Everything beyond that arrives through MCP (Model Context Protocol), an open standard that lets the agent talk to issue trackers, databases, monitoring tools and pretty much anything with an API. The moment you catch yourself pasting a Sentry stack trace or a Jira ticket into the terminal, that's the signal to wire up a server instead and let Claude query the thing directly.
I set all of this up on an Ubuntu 24.04 box running the current 2.1 line of the CLI, and every command below comes straight from the official MCP documentation. There are three transports and three scopes, and most confusion with Claude Code MCP configuration comes from mixing up which of each you want. Let's take them in order.
Add a remote HTTP server
HTTP is the recommended transport for anything cloud-hosted and it's the one vendors publish endpoints for. The syntax:
claude mcp add --transport http <name> <url>
# real example: Notion
claude mcp add --transport http notion https://mcp.notion.com/mcpServers with token auth take a --header flag. GitHub's remote MCP server works this way with a fine-grained personal access token:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"One thing that trips people up: claude mcp add saves the config without validating credentials, so a typo in the token still prints a friendly "Added" line. The failure only shows up when the server tries to connect. Run claude mcp list afterwards and check for ✔ Connected next to the new entry rather than trusting the add command's output.
Servers using OAuth instead of tokens (Sentry is the standard example, at https://mcp.sentry.dev/mcp) get added the same way with no header, then you run /mcp inside a session and complete the browser sign-in from there. On a headless server, claude mcp login <name> --no-browser prints the authorization URL so you can finish the flow from your laptop, a pattern that will feel familiar if you've done the same dance with /login while setting up Claude Code on a VPS.
Add a local stdio server
Stdio servers run as processes on your machine, which suits tools needing filesystem or database access. The shape of the command matters here:
claude mcp add [options] <name> -- <command> [args...]
# real example: Airtable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-serverThe double dash is load-bearing. Everything before -- is parsed as Claude's own options and everything after is the command that launches the server, untouched. Skip it and Claude Code tries to interpret the server's flags as its own, which fails in confusing ways. There's a second, sneakier gotcha documented in the same section: if the server name directly follows an --env KEY=value pair, the CLI reads the name as another key-value pair and rejects it, so keep at least one other option between --env and the name, as the Airtable example does.
A practical database example, using the DBHub server against Postgres:
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:[email protected]:5432/analytics"Note the read-only database user in that connection string. Claude generates and runs SQL on its own judgment once this server is connected, and I'd rather the blast radius of a bad query be zero. Give the agent the narrowest credentials that still do the job. If you'd rather practice the stdio pattern on something that carries no credentials at all, the reasoning server covered in the sequential thinking MCP guide is the safest first add.
For completeness: there's also an SSE transport (claude mcp add --transport sse <name> <url>) for services that only expose a Server-Sent Events endpoint. The docs mark it deprecated in favor of HTTP, so reach for it only when the vendor gives you no choice.
Add Supabase, Stripe and other vendor MCP servers
Every vendor integration follows one of the two patterns above. If the vendor's docs give you a URL, it's an HTTP server; the official docs use Stripe's https://mcp.stripe.com and HubSpot's https://mcp.hubspot.com/anthropic as examples. If the docs give you an npx or binary command, it's stdio and the whole command goes after --. Anthropic's connector directory lists reviewed remote servers, all addable with the same claude mcp add pattern.
Add the Supabase MCP server to Claude Code
Supabase is the vendor question I get most, so here's the worked example. Their server is hosted HTTP at mcp.supabase.com, and the command their MCP documentation gives for Claude Code is:
claude mcp add --scope project --transport http supabase \
"https://mcp.supabase.com/mcp?features=docs%2Caccount%2Cdatabase%2Cdebugging%2Cdevelopment%2Cfunctions%2Cbranching"No access token in the command: run /mcp in your next session and the server walks you through a browser OAuth login. Two query parameters are worth setting deliberately. project_ref=YOUR_PROJECT_ID pins the server to one project and switches off the account-level tools, and read_only=true makes it query Postgres as a read-only user. On anything with production data I set both; the same narrow-credentials logic as the DBHub example applies, just enforced by Supabase's side instead of your connection string. Personal access tokens exist too but they're for CI, and copying one out of an old blog post is exactly the stale-setup trap these hosted servers were built to end.
Scopes: Local, project and user
Every server lands in one of three scopes, picked with --scope (or -s).
Local is the default: the server exists only for you, only in the current project, stored under that project's path in ~/.claude.json. Right for experiments and for servers carrying credentials nobody else should inherit.
Project scope writes a .mcp.json file at the repo root, meant to be committed. Everyone who clones the repo gets the same servers:
claude mcp add --transport http shared-server --scope project https://example.com/mcpWhich produces:
{
"mcpServers": {
"shared-server": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}Claude Code prompts each user for approval before activating servers from a checked-in .mcp.json, a sensible guard given that a malicious commit could otherwise hand the agent new tools silently. claude mcp reset-project-choices clears those approval decisions if you need to re-review.
User scope (--scope user) makes a server available in all your projects. My GitHub server lives here, since I want it everywhere and my token in exactly one place.
Environment variables in .mcp.json
The obvious problem with committing .mcp.json: API keys don't belong in git. Claude Code solves this with variable expansion. The file supports ${VAR} and ${VAR:-default} in the command, args, env, url and headers fields:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}Each developer exports API_KEY in their own shell profile and the committed file stays secret-free. If a referenced variable is unset with no default, the config still loads and claude mcp list shows a missing-variable warning for that server, with the literal ${VAR} text passed through unexpanded. Worth knowing, because an unexpanded variable in a URL produces a connection failure that looks nothing like the config mistake it came from.
Manage servers with /mcp and the CLI
Day to day management is four commands:
claude mcp list # all servers with connection status
claude mcp get github # detail for one server
claude mcp remove github # delete a server
/mcp # in-session panelThe /mcp panel is the one I use most. It shows each server's status and tool count, handles OAuth sign-ins and lets you toggle a server off without deleting its config, which beats removing and re-adding when you want a quieter session. Status lines on failed servers include the HTTP status the server returned, so a 401 (bad token) reads differently from a 404 (wrong URL).
Security judgment for MCP servers
My position: an MCP server is an execution surface, and that changes how careful I am with it. Each one you add extends what the agent can see and do, and a server fetching external content (web pages, tickets, emails) can carry prompt-injection payloads into your session. The official docs warn about exactly this. So I treat third-party servers like dependencies: check who publishes them, prefer official vendor servers over community rewrites, read the source of small stdio ones before running them and give each the narrowest credentials available. Read-only tokens, single-project scopes, a database user without write grants.
Project-scoped servers deserve extra thought since .mcp.json ships to everyone who clones the repo. In a team setting I'd hold review on that file to the same standard as CI config changes. And pairing risky servers with Claude Code hooks works well, because a PreToolUse hook can block specific MCP tool calls with a mcp__servername__.* matcher, deterministically, no matter what the session context says.
If you want to go a level deeper and run your own server rather than consuming someone else's, the same protocol applies from the other side; our walkthrough of the Hermes MCP server setup covers building that with a YAML config. A small VPS suits self-hosted MCP servers well, since they idle at nearly nothing and stdio servers can run next to the agent itself; a Claude Code VPS deploys instantly on NVMe hardware with unmetered bandwidth, which is a comfortable home for an always-on agent plus its toolbelt. Once servers are connected, the interesting work starts: telling Claude to pull the failing Sentry issue, cross-reference it with the schema in Postgres and open the fix as a PR, all in one prompt, is the point of every command on this page. Give your memory setup the same care in CLAUDE.md and /init and the agent knows both your tools and your rules.
