What Is MCP (Model Context Protocol)? A Developer's Guide

MCP, the Model Context Protocol, is a standard way for an AI model to find out what tools are available to it and then call them. One integration, written once, works with any AI client that speaks the protocol.

Before it, every assistant had its own plugin format. If you wanted your product usable from three different AI tools, you wrote three integrations. MCP is the answer to that, and the reason "we support MCP" became a line on so many product pages during 2025 and 2026.

What it is not is a guarantee that the call works. That distinction is most of this post.

The three pieces

A client is the AI tool: Cursor, Claude Code, Claude Desktop, Windsurf, an agent you wrote. It connects to servers and decides which tools to put in front of the model.

A server exposes capabilities. Those come in a few kinds, and the one everybody means is tools: named operations with typed parameter schemas that the model can call. Servers can also expose resources, which are data the model can read, and prompts, which are reusable templates.

The transport is how the two talk. In practice it is either stdio, where the client starts the server as a local process and they speak over standard input and output, or HTTP for a server running somewhere else.

The useful mental model: a server publishes a menu of typed operations, the client shows that menu to the model, and the model picks from it. The parameter schemas are the important part, because they are what stop the model inventing a field name.

A concrete example

Starting a server over stdio:

swy mcp serve

Or over HTTP, bound to localhost:

swy mcp serve --transport http --port 5476

The HTTP form serves at http://127.0.0.1:5476/sse and requires a bearer token stored at ~/.swytchcode/mcp_token, which you can print or rotate:

swy mcp token
swy mcp token --rotate

Most clients are configured with one command rather than hand-written JSON. Cursor is swy init --editor=cursor, which writes ~/.cursor/mcp.json. Claude Code is swy mcp serve --claude, which registers directly. Windsurf is swy init --editor=windsurf, writing ~/.codeium/windsurf/mcp_config.json. The full list is in the MCP docs.

What changed in the 2026-07-28 revision

If your knowledge of MCP is from 2025, a lot of it is out of date. The 2026-07-28 revision was large, and the headline is that MCP became stateless.

Sessions were removed. The initialize handshake, the notifications/initialized message and the Mcp-Session-Id header are all gone. Protocol version and capabilities now travel in request metadata instead. Server-sent event resumability was removed too, which means a broken stream has to be re-issued with a new request ID rather than resumed.

That last detail has a consequence people miss, and it is the reason this matters for anyone building on MCP rather than just configuring it: if a retried request must carry a new request ID, you cannot use the request ID to detect a duplicate. Deduplication has to happen somewhere else. We worked through it in MCP went stateless, so where do idempotency keys live now, and the full changelog with migration code is in the MCP 2026-07-28 spec guide.

What MCP does not do

This is the part worth internalising, because a lot of production incidents come from assuming otherwise.

MCP standardises how a tool is described and how a call is transported. It says nothing about whether the call was a good idea, whether it worked, or what to do when it half-worked. Four things remain entirely yours.

Correct arguments. The protocol carries a parameter schema, which helps enormously. It does not check that the model's values make sense, and it does not stop a server exposing a stale schema. Models still send invented field names, which is the subject of why your AI agent calls the wrong API.

Exactly-once writes. Nothing in MCP makes a retried call idempotent. If your client retries a timed-out tool call, the provider sees two requests unless something attached the same idempotency key to both. See idempotency explained.

Authorization. A server can expose a delete_everything tool and MCP will carry it faithfully. What an agent is allowed to do with a valid connection is a policy question, and policies belong in version control rather than in a prompt: policy-as-code for AI agents.

An audit trail. The protocol does not keep one. Whatever sends the HTTP request has to write the record, including the calls that were blocked. Logging every API call an agent makes has the fields.

The short way to say it: MCP is the socket, not the appliance. We drew that line properly in MCP gateway vs execution layer.

Why tool count matters more than it sounds

One practical thing nobody tells you when you start adding servers.

Every connected server's tool definitions are loaded into the model's context before it does anything. Each definition carries a name, a description and a parameter schema. Ten servers exposing twenty tools each is two hundred definitions on every single request.

That is a permanent token cost, and it also degrades accuracy, because the more similar-sounding tools the model can see, the more often it picks the wrong one.

So a server that exposes one tool per API endpoint scales badly. A better design exposes a few tools that can reach many operations. Swytchcode's default profile exposes 7 tools, discover, info, exec, list, search, add and a read-only policy, and those seven reach all 363 integrations in the catalog. The model searches for an operation rather than being handed 363 of them up front.

Reading the vocabulary

A short glossary, since the terms get used loosely.

Should you build an MCP server or use one?

If you have a product you want AI tools to reach, building a server is the right move and the protocol is the reason you only build it once.

If you are trying to let an agent use APIs that already exist, building a server per provider is the slow path. You end up maintaining integrations and, more painfully, maintaining them as the providers change. That is what why AI coding agents keep using deprecated APIs is about. Every API added to Swytchcode becomes agent-ready in minutes and is then tracked for breaking changes by observing its specs and documentation, which is the alternative to that being somebody's standing job.

FAQ

What is MCP in simple terms?

MCP, the Model Context Protocol, is a standard that lets an AI model discover what tools are available and call them with typed parameters. Write one MCP server for your product and any AI client that speaks the protocol can use it, instead of building a separate plugin for every assistant.

What is the difference between an MCP client and an MCP server?

The client is the AI tool, such as Cursor, Claude Code or Claude Desktop. It connects to servers and shows their tools to the model. The server is the process that exposes capabilities, either locally over stdio or remotely over HTTP. One client typically connects to several servers at once.

Is MCP the same as an API?

No. An API is the thing being called. MCP is a standard way of describing and transporting that call so a model can discover and use it. An MCP server usually sits in front of one or more APIs. The protocol gives the model a typed menu; it does not change what the underlying API does or how it fails.

Does MCP make my AI agent safe?

No, and this is the most common misreading. MCP standardises how tools are described and invoked. It does not validate the model's arguments, prevent a retry from duplicating a write, decide whether an operation should be allowed, or keep an audit trail. Those belong to whatever actually executes the request.

What changed in MCP in 2026?

The 2026-07-28 revision removed sessions entirely, making the protocol stateless. The initialize handshake and Mcp-Session-Id header are gone, protocol version and capabilities moved into request metadata, and SSE resumability was removed so a broken stream must be re-issued with a new request ID. That last point rules out using request IDs for deduplication.

How do I add an MCP server to my AI tool?

Most clients take one command rather than hand-edited JSON. swy init --editor=cursor writes ~/.cursor/mcp.json, swy mcp serve --claude registers with Claude Code, and swy init --editor=windsurf writes ~/.codeium/windsurf/mcp_config.json. There are equivalent flags for Copilot, Codex, Gemini CLI, OpenClaw and Hermes.

How many MCP servers should I connect at once?

As few as cover genuinely different jobs. Every server's tool definitions sit in context on every request, so servers are a standing cost and too many similar tools makes the model worse at choosing. Prefer a small number of servers that each expose few tools.

Protocol details here come from the MCP 2026-07-28 spec guide and the Swytchcode MCP docs. For setup in a specific tool, see best MCP servers for Cursor or best MCP servers for Claude Code.