Back to Guides
/ Guides

How to Add an MCP Server to Claude Code (2026)

Aleks Koha7 min read

Claude Code is a capable coding agent with the usual stock limit: on its own it works with your local files and shell, but it can't reach a managed database, a deploy target, or a remote service. MCP (Model Context Protocol) is the standard plug that fixes that. Connect a server and Claude Code gains tools it can call while it works — query this, deploy that, run this job.

The good news for terminal people: there are no config files to hand-edit. Claude Code has proper claude mcp commands, and adding a remote server is a single line. This guide covers the command, the three scopes that decide who sees the server, how OAuth works, and what a genuinely capable server changes — using the Matagi MCP server as the example.

What MCP Gives Claude Code

An MCP server exposes tools — functions the model can call. Once connected, Claude Code discovers those tools automatically and decides when to use them based on your instructions. What you get depends on the server: a docs server helps it read, a database server lets it query, an infrastructure server lets it provision and deploy.

Servers come in two shapes. Remote (Streamable HTTP) servers live at a URL — nothing to install, nothing to keep running, and they follow you across machines. Local (STDIO) servers run as a process on your machine. For anything infrastructure-shaped, remote is the better default, and it's where Claude Code's setup is simplest.

The One Command for a Remote Server

Adding a remote MCP server is one claude mcp add with the HTTP transport. Using Matagi as the example:

claude mcp add --transport http matagi https://mcp.matagi.ai/mcp

That's the whole registration. There's no API key to create, copy, or paste into a dotfile — authentication happens over OAuth, which we'll trigger in a moment. Note the flag order: --transport (and any --scope or --env) comes before the server name.

Choosing a Scope: local, project, user

Claude Code lets you decide where the server config lives and who sees it, via --scope:

  • local (default) — available only to you, only in the current project. Good for experiments and personal tools.
  • project — shared with everyone working in the repo, written to a .mcp.json file at the project root that you commit to version control. Good for a server the whole team should have.
  • user — available to you across all your projects. Good for a server you always want on hand.

So to give your whole team the Matagi server through a committed file:

claude mcp add --scope project --transport http matagi https://mcp.matagi.ai/mcp

Because the remote config is just a name and a URL — no secrets — committing .mcp.json is safe; nobody's credentials end up in the repo.

Authenticate and Verify

For a remote server that uses OAuth, run the MCP command inside a Claude Code session:

/mcp

Select matagi and choose to authenticate. A browser window opens to a Matagi consent screen — sign in with your work email and approve access. If you're new to Matagi, a workspace is created with trial credit, so there's no separate signup. Tokens refresh automatically; you won't be asked again unless you revoke access.

Check what's connected from the terminal:

claude mcp list

You'll see matagi and its tools. From that point, Claude Code can call them. To remove a server later: claude mcp remove matagi.

Local (STDIO) Servers

Not every server is remote. A local server runs as a process on your machine and is added with a command instead of a URL:

claude mcp add my-tool -- npx -y some-mcp-package

Everything after -- is the command Claude Code launches. Local servers make sense for tools that operate on local resources, but they mean something has to be installed and kept updated. If a service is hosted, prefer its remote URL — like Matagi's — and skip the local process entirely.

Worked Example: What a Good MCP Server Adds

What you connect matters more than how. Most MCP servers make Claude Code better at reading — docs, schemas, issues. The bigger unlock is a server that lets it finish the job.

Here's the gap: Claude Code can write a complete application and then stall, because shipping it needs servers, a database, credentials, and wiring that live outside your machine. You become the DevOps intern for your own AI.

With the Matagi server connected, that last mile becomes tool calls. Ask Claude Code to "build a waitlist API with a Postgres database behind it and deploy it," and it can provision the database (isolated, per-workspace), deploy the function, register a schedule if the job recurs, and hand back a working URL. External services go through Matagi's proxy, so API keys and OAuth tokens are injected server-side and never appear in the generated code — so they never land in your repo either. Review what the agent built before pointing real traffic at it — verify, don't trust.

Troubleshooting

Server added but tools don't appear. Tool lists are fetched when the server connects; start a fresh session, then run claude mcp list to confirm it's healthy.

/mcp shows the server as unauthenticated. Select it in /mcp and run the authenticate action again; some terminals block the browser launch, and the consent URL is printed so you can open it by hand.

"Flag not recognized." --transport, --scope, and --env must come before the server name, not after the URL.

Team can't see the server you added. You probably added it at local scope. Re-add with --scope project so it's written to the committed .mcp.json.

A guide tells you to edit JSON by hand. You can, but claude mcp add writes the same config without the syntax risk. Reserve manual edits for the .mcp.json you commit for a team.

FAQs

Does adding MCP servers to Claude Code cost anything? The Claude Code side is free — MCP support is built in. Individual servers set their own pricing; Matagi starts new workspaces with trial credit.

What's the difference between Claude Code and Claude Desktop for MCP? Claude Code is the CLI and uses claude mcp add; Claude Desktop is the app and uses custom connectors. Both reach the same remote server and — with Matagi — the same workspace.

Can I use the same server in Claude Code and Cursor or Codex? Yes. That's the point of remote MCP: one endpoint works across clients, so switching editors keeps your tools and resources.

Where does the config live? Local and user scopes live in your Claude Code settings; project scope lives in a .mcp.json at the repo root that you commit.

Is it safe to give Claude Code infrastructure tools? Matagi scopes everything to your workspace, keeps credentials in a server-side proxy (never in code or model context), and logs every action with an audit trail. Keep destructive tools gated and review output — verify, don't trust.

Give Claude Code hands: connect the Matagi MCP server — claude mcp add --transport http matagi https://mcp.matagi.ai/mcp, run /mcp to sign in, and start shipping real infrastructure from the terminal.

claude code mcpclaude codemcp serversmcp setupai coding tools

Build your first AI agent free

Describe what you want done in plain English. Matagi provisions the infrastructure, wires the integrations, and deploys it.

Get started