MCP servers: connect your database, browser, and GitHub to Claude Code

So far in this show you've been working inside one Claude Code session, sharpening the tools that ship in the box. You've set up your project memory file, locked down permissions, written your own slash commands, wired hooks that fire on their own, packaged a skill, and in the last episode you handed a noisy job off to a subagent so it wouldn't clog your main context. Every one of those lives inside Claude Code. Today we punch a hole in the wall and let Claude reach things you didn't build: a real browser, your Postgres database, your GitHub repos, your error tracker in production. The way you do that is the Model Context Protocol, MCP for short, and by the end of this episode you'll have wired up a server, understood exactly where the config lives, and learned the one mistake that quietly wrecks more setups than anything else.

Let me set the stakes first, because MCP is the rung where Claude Code stops being a smart thing in your terminal and starts being a thing that touches your actual systems. That's a real step up the ladder this show is climbing. It's also where you can hurt yourself, so we'll spend real time on the pitfall near the end.

What the Model Context Protocol actually is

Anthropic introduced MCP in late November of 2024 and open-sourced it the same day, with the Model Context Protocol announcement and starter kits for Python and TypeScript. The framing everyone repeats is "USB-C for AI," and it's a good one. Think about what USB-C fixed. Before it, every device had its own cable, its own connector, its own adapter you could never find. After it, one port, one cable, everything plugs into everything. MCP is trying to be that port, but for connecting AI applications to tools and data.

The problem it solves has a name: the N-by-M problem. Say you've got N different AI apps and M different systems you want them to talk to, your database, your ticket tracker, your file storage. Without a standard, somebody has to build a custom integration for every single pairing. That's N times M connectors, and most of them never get built. MCP collapses that. Each app implements the protocol once as a client, each system implements it once as a server, and now any client talks to any server. You go from N times M down to N plus M. That's the whole pitch, and it's why this caught on fast.

And it did catch on, well beyond Anthropic. OpenAI officially adopted MCP in March of 2025, across the ChatGPT desktop app and their agents tooling. Google signed on for Gemini. Microsoft shipped first-party support and baked MCP into VS Code and Copilot Studio. Editors like Cursor, Cline, Windsurf, and Zed all act as MCP clients now. Within about three months of launch there were over a thousand community-built servers, and by late 2025 the official catalog had passed roughly two thousand. If you've ever watched a standard win by being open and boring, this is that story again. The closest analogy is the Language Server Protocol, the thing that let one language server plug into every code editor instead of each editor reinventing autocomplete. Same shape, same outcome.

Here's the mental model for the pieces. There are three roles. The host is the AI app you're using, and for us that's Claude Code. Inside the host lives the client, which manages one connection per server. And then there's the server, which is the actual connector to some tool or data source. A server can run locally as a little subprocess on your machine, or it can live out on the internet as a remote endpoint. Claude Code is always the client. You're adding servers.

Now, what does a server actually give you? Three kinds of things, and it's worth keeping them straight because Claude Code surfaces each one differently. First, tools. These are actions the model can call: query a database, click a button in a browser, open a GitHub issue. Each tool has a name, a description, and a schema for its inputs. Second, resources. These are read-only data the server can hand over as context, like a database schema or the body of an issue, and in Claude Code you pull them in with an at-mention, the same way you reference a file. Third, prompts. These are reusable prompt templates the server defines, and Claude Code turns them into slash commands. Tools are the part you'll use most, but the other two matter, and we'll come back to how you actually reach them.

The transports, and which one you want

A server has to talk to Claude Code somehow, and there are a few different pipes for that. The docs call them transports, and you mostly care about two.

The first is stdio, which stands for standard input/output. With stdio, Claude Code launches the server as a subprocess right on your machine and talks to it over the same plumbing a command-line program uses to read input and print output. This is the one you'll reach for constantly. It's perfect for anything local: a script you wrote, a CLI tool, a database sitting on your laptop. There's no login flow because the trust is implicit, you're the one who ran it. One detail worth tucking away: when Claude Code spawns a stdio server, it hands that subprocess an environment variable pointing at your project root, the same one your hooks get. So a server can orient itself to the right directory.

The second transport you care about is HTTP, sometimes called streamable HTTP, and this is the one for remote servers out on the internet. A cloud service like GitHub or Sentry or Stripe runs the server on their side, and Claude Code connects over HTTP. This is the recommended pipe for anything cloud-based, and it's the one that supports proper authentication with OAuth. One nice touch in the config: where you'd normally write the type, Claude Code accepts the longer spec name "streamable-http" as an alias for plain "http," so when you copy a config straight out of a vendor's docs, it just works. Remote HTTP servers also reconnect on their own if the connection drops, backing off and retrying.

There are two more transports, mostly so you recognize them. SSE, server-sent events, is deprecated. The docs say it plainly: use HTTP servers instead where you can. Most servers that used to need SSE now answer on streamable HTTP at the same address, so unless a specific server demands it, don't reach for SSE on anything new. And there's WebSocket, for the rare server that needs to push events to you unprompted rather than just answering requests. You can only configure WebSocket through the config file, not the quick command, and it only does header-based auth. For almost everything, it's stdio for local and HTTP for remote. That's the decision.

Adding a server from the command line

Let's actually wire one up. The workhorse command is claude mcp add, and the shape of it trips people up, so I'm going to be precise. You type claude mcp add, then any options you want, then the name you're giving the server, then a double dash, then the command that launches the server and its arguments. The double dash is load-bearing. It's the fence between Claude's own flags and the flags meant for the server. Without it, a flag you intended for your server gets eaten by Claude Code, and you spend twenty minutes confused. Here's the other half of that rule: every option, the transport, the environment variables, the scope, the headers, all of it has to come before the server name. Options first, then name, then the double dash, then the server's own command. Burn that order in, because getting it wrong is the single most common reason a brand-new server won't start.

So a local stdio server looks like: claude mcp add, the name, double dash, then something like npx and the package. A remote HTTP server is shorter, you give it the transport flag set to http, the name, and the URL. If that remote server needs a key, you tack on a header flag with something like an Authorization bearer token.

Once you've got servers, a handful of commands manage them. claude mcp list shows everything you've configured and whether it actually connected. claude mcp get, with a server name, prints the details for one of them. claude mcp remove deletes one. There's claude mcp add-json if you'd rather paste a raw blob of JSON than assemble flags, which is handy when a vendor gives you the JSON directly. And there's a fun one, claude mcp serve, which runs Claude Code itself as a server so another MCP client can drive it. You won't need that today, but it's a nice tell for how symmetric this protocol is.

Inside a session, the command you'll live in is just slash mcp. It opens a panel listing every server, the number of tools each one exposes sitting right next to it, the connection status, and the entry point to log in to servers that use OAuth. That tool count is going to matter a lot when we get to the pitfall, so notice that it's right there in front of you.

Where the config lives: the three scopes

When you add a server, it gets written down somewhere, and Claude Code gives you three places to write it, called scopes. The difference between them is who the server is visible to, and whether it's shared.

Local scope is the default. A locally-scoped server is visible only in the current project, only to you, and it's stored in a hidden Claude config file in your home directory, filed under this specific project's path so it doesn't bleed into your other projects. Reach for local scope when the server is personal or experimental, or when it carries a credential you don't want anywhere near version control. There's a naming trap here worth flagging: this "local" config does not live in your project's settings file, the local settings file you might use for personal overrides. It lives in that home-directory config. And if you've read older docs, the names have shifted around, so trust the current behavior over your memory.

Project scope is the interesting one for teams. A project-scoped server gets written to a config file at the root of your repository, and that file is meant to be checked into git. The whole point is that your teammates clone the repo and get the exact same servers you do, no setup ritual. When you add a server with project scope, Claude Code creates or updates that file for you. This is how you say "everyone working on this codebase should have the browser server and the database server wired up." It travels with the code.

User scope is the third option: a server available across all of your projects, but private to you. It also lives in that home-directory config. Reach for it when you've got a personal utility you want everywhere, like a docs-fetching server you never want to be without.

What happens if the same server name shows up in more than one scope? Claude Code connects once and uses the highest-precedence definition, and it does not merge the fields together. The order, highest to lowest, is local, then project, then user. So a local definition wins over the shared project one, which lets you override a team server locally without touching the committed file.

Now the security beat, and this is important enough that I want you to really hear it. Because that project config file is committed to git, anyone who clones the repo would, in principle, get servers that run automatically the moment they start Claude Code. A teammate could add one. So could a malicious pull request. So Claude Code does not silently trust project-scoped servers. The first time it sees one, it asks you to approve it. Until you do, that server shows up as pending approval in the listing, and a rejected one shows as rejected. If you ever need to redecide, there's a command, claude mcp reset-project-choices, that wipes your answers so you get asked fresh. That approval prompt is not bureaucracy. It's the gate standing between a poisoned config file and arbitrary code running on your machine, and we'll see exactly why that matters when we talk about the lethal trifecta.

Real servers a web developer actually wires up

Enough abstraction. Let me walk through the servers you'd genuinely connect on a normal web app, because seeing the lineup makes the whole thing click.

Start with the browser, because it's the most fun to watch. Microsoft maintains an official Playwright MCP server, and you add it as a local stdio server pointed at the Playwright MCP package. What makes it clever is that it drives a real browser using structured accessibility snapshots instead of screenshots by default, so it reads the page the way a screen reader would, which is fast and deterministic rather than squinting at pixels. It exposes tools to navigate, click, type, fill out forms, take a screenshot when you do want one, read the console, and inspect network requests. So you can say "check that the login flow works with this test account," or "screenshot the checkout page at mobile width," and Claude actually drives the browser and reports back. For anyone shipping a Next.js app on Vercel, this is the moment Claude Code stops guessing about your UI and starts looking at it.

Next, your database. The docs use a server called dbhub, which speaks to Postgres and other databases over a standard connection string, and you add it as a local stdio server with that connection string passed in. Notice one deliberate detail in their example: the connection string uses a read-only user. That is not an accident, and you should copy the habit. A database server wired to write credentials, handed to a model that's improvising, is how you end up explaining to your team why the orders table is empty. If you're on Supabase or Neon, which fits this show's default stack, there are dedicated servers too. The Supabase one takes an access token and your project URL, and it offers a read-only flag and project scoping so you can fence off the blast radius. Wire it up and you can ask "what's our revenue this month" or "show me the schema for the orders table" and get a real answer from your real data.

Then GitHub, and this one's a good example of a remote server. GitHub runs an official MCP server at a hosted endpoint, and you add it with the HTTP transport pointed at that URL. For auth you've got two choices: a fine-grained personal access token passed as a header, scoped down to just the repos you mean, or the OAuth login flow. Once it's connected, you can say "review pull request four fifty-six and suggest improvements," or "open an issue for the bug we just found," and it acts on your actual repo. Hold onto the GitHub example, though, because it's also going to be our cautionary tale in a few minutes. It exposes a lot of tools.

Sentry rounds out the production picture. Sentry's remote server uses OAuth, so you add it with the HTTP transport and then run slash mcp inside the session to do the browser login. After that you can ask "what are the most common errors in the last twenty-four hours," or "which deploy introduced these new errors," and close the loop from code to production incident without leaving your terminal.

A couple more worth knowing. There's a docs server from Upstash called Context7 that fetches current, version-specific documentation for libraries at the moment you ask, instead of leaning on whatever your model learned in training. Given how fast all of this moves, that's a genuinely useful antidote, and since you want it everywhere, it's a natural fit for user scope. And there's a reference filesystem server that scopes file access to directories you name, though honestly Claude Code already reads and writes files natively, so you rarely need it. Beyond those, the same add command connects Notion, Stripe, Linear, Slack, Jira, and the rest. Anthropic keeps a reviewed connector directory of remote servers, with a standing warning attached: verify you trust each server before you connect it. We'll honor that warning shortly.

Authentication and keeping secrets out of git

Let's talk about how these servers prove who you are, because it's the part people fumble. For remote servers, the clean path is OAuth. You add the server, run slash mcp, and follow a browser login. Claude Code knows a server wants authentication when it answers a request with an unauthorized or forbidden status, or points at its own auth server through a standard header, and it discovers the login flow from there. Your tokens get stored securely in the system keychain and refreshed automatically, and that same slash mcp panel has a "clear authentication" option to revoke them. One gotcha: if you hand-set an Authorization header and the server rejects it, Claude reports the connection as failed. It does not quietly fall back to OAuth. So if you meant to use OAuth, don't also set the header.

For servers that just want a static API key, the header flag is your tool, and you pass something like an Authorization bearer line or a custom key header. But now you've got a secret sitting in a config file, and if that's the committed project file, you've got a problem. The answer is environment variable expansion. In the config, instead of pasting the actual key, you write a placeholder that points at an environment variable, and Claude Code substitutes the real value at load time. You can even give a default, so the placeholder resolves to a fallback when the variable isn't set. This works in the command, the arguments, the URL, and the headers. So the pattern for a team is: commit the structure of the config, with placeholders where the secrets go, and let each developer supply the actual values through their own environment. The repo stays clean, everyone still connects. One sharp edge: if a required variable has no value and no default, Claude Code fails to parse the config entirely, so it's all or nothing on that one.

There's more machinery for the hard cases, pre-registered OAuth client credentials for servers that don't support automatic registration, the ability to pin down exactly which OAuth scopes you're granting so a security team can keep the permissions narrow, and even a helper command that generates fresh headers on every connection for things like short-lived internal tokens. You don't need any of that on day one. Just know it's there when you hit a corporate SSO wall.

Using MCP tools once they're connected

So a server's connected. How do you actually reach into it? Mostly you just talk, and Claude picks the tool. But it helps to know how the pieces surface.

The tools themselves show up with a distinct naming scheme. It's the letters m-c-p, then the server name, then the tool name, all joined by double underscores. So a GitHub tool to list issues reads as mcp, github, list_issues, stitched together with those double underscores. You'll see these names in permission prompts and in your settings, and the pattern lets you allow or deny a whole server at once with a wildcard. Quick heads-up: a couple of other Anthropic surfaces use a colon-separated form for the same idea, so if you're copying between the Agent SDK and the CLI, double-check the exact punctuation rather than assuming.

Resources, the read-only data a server offers, come in through at-mentions. Type the at sign and Claude Code autocompletes resources from every connected server right alongside your files. So you can write "analyze at-github issue one twenty-three and suggest a fix," and it fetches that issue's contents and attaches them. It's the same muscle memory as referencing a file, which is the point.

Prompts, those server-defined templates, show up as slash commands under the server's namespace. You type slash, and the server's prompts appear, and you can pass arguments after them just like any command. It's a tidy way for a server author to ship a canned workflow you trigger by name.

Two operational details matter. First, permissions. MCP tools obey the exact same permission system you set up a few episodes back. You can allow or deny them by their full name in your settings, or wildcard an entire server, and the slash permissions command reviews what you've granted. Treat a new server's tools the way you'd treat any new capability: don't auto-allow the whole thing. Second, output size. MCP tools can return a lot of text, and Claude Code warns you when one returns more than about ten thousand tokens. There's an environment variable to raise the ceiling, with a default cap around twenty-five thousand tokens. Keep those two numbers straight, ten thousand is the warning, twenty-five thousand is the default ceiling, because a chatty tool can blow through your context if you're not watching.

The pitfall: tool-surface bloat

Here's the mistake. It's the reason this episode exists, and almost everyone makes it.

MCP feels free. You find a server, you add it, you find another, you add it, and pretty soon you've got eight servers connected because why not. The problem is that historically, every connected server poured all of its tool definitions into the context window of every single message. Not the tools you use. All of them. The full name, the description, the input schema, every field, every enum value. Before the model has read your first sentence, a chunk of its working memory is already spent on a menu of tools it mostly won't touch.

The numbers are worse than you'd guess. A single tool definition runs somewhere between roughly five hundred and fourteen hundred tokens. GitHub's official server, the one I told you to hold onto, weighs in around seventeen thousand six hundred tokens of definitions all by itself. One measured case had three servers eating a hundred and forty-three thousand tokens out of a two-hundred-thousand-token window, so seventy-two percent of the context was gone before the agent did anything. Another had forty-three tool definitions, around fifty-five thousand tokens, to use one or two of them.

And it's not just wasted space, which would be bad enough. The model gets worse at its job. In testing, tool-selection accuracy collapsed from around forty-three percent down to under fourteen percent once the tool set got bloated. Read that again: with too many tools on the menu, the model picks the wrong one roughly seven times out of eight. Throw in name collisions, two different servers each offering a "search" or a "create issue," and the confusion compounds.

So how do you know it's happening to you? The slash context command shows MCP tools eating a big slice before you've done anything. The model reaches for the wrong tool, or a tool from a server you didn't mean. Sessions feel sluggish and Claude seems to forget earlier context faster, because the window's under pressure. And that slash mcp panel shows servers with tool counts in the double digits that you never actually call.

The fixes start simple. Only connect what you need, and resist the "just in case" server. Scope servers to the project that uses them instead of loading them into every session through user scope. Disable or remove the ones you've stopped using. Prefer a narrow server over a kitchen-sink one, and use a server's own scoping flags, the read-only mode, the project limit, to shrink its footprint.

But the real fix is newer and it's mostly automatic. Claude Code now defers MCP tool definitions. Instead of dumping every schema in up front, it loads only the tool names at the start, and pulls the full definition on demand, when Claude actually goes looking for a tool to use. Anthropic moved this, along with a related feature for calling tools programmatically, to general availability in February of 2026, and reported something like an eighty-five percent cut in token usage, with roughly a hundred and ninety thousand tokens of context preserved in their tests. There's an environment variable that controls the behavior if you want to tune it, including a mode that loads tools up front only when they'd fit inside a small slice of the window and defers them otherwise. And if there's a handful of tools you genuinely use every single turn, you can mark a server to always load those, so they skip the deferral, though every always-loaded tool costs context, so use that sparingly. The headline is: adding another server doesn't punish you the way it used to. But the discipline still matters, because the deferred design works best when server authors keep their descriptions tight, and not all of them do.

The other half of the pitfall: security

Tool bloat costs you tokens and accuracy. The security side can cost you your data, and it deserves equal time.

An MCP server, especially a stdio one you launch with a package runner, is arbitrary code. A remote one is an arbitrary endpoint you've just handed tool access and maybe a credential. When you run that quick add command against some package, you're running whatever's published under that name. So vet the source. This is exactly what that project-scope approval prompt is defending: a committed config file could otherwise add a server that runs the instant a teammate clones and starts Claude Code.

The sharper danger is prompt injection through untrusted content, and the cleanest way to understand it is a framing from security researcher Simon Willison called the lethal trifecta. The idea: you're exposed when an agent has all three of these at once. One, access to your private data. Two, exposure to untrusted content, meaning any text an attacker could control. And three, the ability to communicate outward, to send something somewhere. Any tool that reads attacker-controllable text counts as untrusted content. As Willison puts it, an attacker can literally email your model and tell it what to do. And MCP makes this trap easier to stumble into precisely because it encourages mixing and matching tools from different sources, so you can assemble all three legs of the trifecta without noticing.

Here's the concrete version. Imagine you connect a GitHub server that can read issues on a public repo, that's untrusted content, anyone can file an issue. The same server can read your private repos, that's the private data. And it can open pull requests, that's the path outward. An attacker files an issue whose text is really a set of instructions, your agent reads it, and gets talked into copying private code into a public pull request. Three capabilities that are each fine alone, lethal together. And Willison is blunt that nobody has a reliable, hundred-percent fix for this yet, so products claiming they block ninety-five percent of attacks are, in security terms, failing.

What do you actually do about it? Least privilege, everywhere. Read-only database credentials, like that example used on purpose. Personal access tokens and OAuth scopes pinned down to the minimum. Keep your allow and deny lists tight. And the big one: don't combine private-data access, untrusted content, and an outward path in the same session unless you've really thought it through. If you're letting an agent read public issues and touch private repos, be very deliberate about whether it can also push anything out. The Claude Code security docs say it directly, servers that fetch external content expose you to prompt injection risk. That approval prompt and these scoping habits are the seatbelt. Wear it.

Where MCP sits next to the tools you already know

You've now got four ways to extend Claude Code, and it's worth a quick line on each so you reach for the right one. An MCP server connects Claude to a system you didn't build, a database, a browser, GitHub, Sentry. It's the integration boundary. A skill, which we built two episodes back, packages a procedure or some domain knowledge that lives in your repo and loads when it's relevant. A subagent, from last episode, is a one-off worker with its own context for a bounded task. And a hook is a shell command that fires deterministically on a lifecycle event, for guaranteed enforcement around the loop. The one-liner to keep: MCP adds capabilities, skills add knowledge, subagents add workers, hooks add guardrails. When you want Claude to touch a system out in the world, that's MCP. The other three don't do that.

What's moved recently, and where this is heading

A few developments worth knowing, because this area changes fast. The protocol itself has dated revisions, and the one Claude Code references brought structured tool output, a way for servers to ask you for input mid-task, and tighter binding of auth tokens to a specific server. In September of 2025 an official MCP registry launched in preview, a community catalog and API meant to be the single place to discover servers, and it grew toward a couple thousand entries. There's a packaging format, recently renamed to MCP Bundles, that wraps a local server with all its dependencies into a single one-click installer, though that's aimed at the Claude Desktop app. For Claude Code, remember, the way you share servers with your team stays the committed project config file, plus plugins, not those bundles.

And the direction of travel is interesting. Anthropic published work on code execution with MCP, where instead of loading thousands of tool definitions, the agent writes a bit of code that calls the tools it needs. Same instinct as the deferred-loading fix: the token cost of having lots of tools available is the thing everyone's racing to drive down. There's even a server capability now for pushing events into your session unprompted, so a server can ping you when a CI run finishes or an alert fires.

One last practical gotcha to save you a confusing afternoon. If you add a stdio server that launches a package pinned to "latest," it can fail to connect when you've got several Claude Code sessions starting at once, because each startup forces a fresh lookup against the package registry. Pin a real version instead of "latest" and that flakiness goes away. It's a small thing, and it's exactly the kind of small thing that makes you think MCP is broken when it isn't.

That's the rung. You can connect a server, you know the three scopes and which file gets committed, you know the double-dash rule that makes the add command behave, and you know that the failure mode isn't usually a broken server, it's ten servers you didn't need flooding the context and dulling the model, or three capabilities that combine into something an attacker can pull. Connect what the job needs, scope it tight, keep the credentials least-privilege, and let the deferred loading do its work. Next time we'll take what you can now reach and start managing the thing all of this consumes, the context window itself.