What Is an MCP Server? How It Works, Real Examples and How to Build One (2026)

An MCP server is a program that gives an AI application a set of things it can do or read, such as search a database, create a GitHub issue or send an email, through one standard protocol. The protocol is MCP, the Model Context Protocol. Any AI app that speaks MCP can connect to any MCP server without custom integration code on either side.

This guide explains what is inside an MCP server, what the messages look like on the wire, how local and remote servers differ, and which real servers exist. It also includes a working server you can build in 20 lines of Python and an honest section on what can go wrong.

What is an MCP server?

An MCP server is the "tool side" of the Model Context Protocol. The "AI side" is an MCP client, which lives inside an application such as Claude Desktop, ChatGPT, Cursor or VS Code. The server tells the client what it offers; the client passes that menu to the language model; when the model decides to use something, the client sends the request back to the server and returns the result.

The official docs compare MCP to a USB-C port for AI applications: one connector shape, many devices. The practical effect is that a tool is written once as an MCP server and then works in every compatible client. Before MCP, a company that wanted its product available in three AI assistants built and maintained three separate connectors.

A short history helps to place it. Anthropic open-sourced MCP on November 25, 2024; it was created by David Soria Parra and Justin Spahr-Summers, and the first pre-built servers covered Google Drive, Slack, GitHub, Git, Postgres and Puppeteer. On December 9, 2025 Anthropic donated the protocol to the Agentic AI Foundation, a fund under the Linux Foundation co-founded by Anthropic, Block and OpenAI. At that point the project counted more than 10,000 active public servers and over 97 million monthly SDK downloads across Python and TypeScript. The specification is versioned by date; the current revision is 2026-07-28.

How an MCP server works

Three roles take part in every MCP connection.

• Host. The user-facing AI application: Claude Desktop, Cursor, a custom agent you wrote.
• Client. A component inside the host that holds one connection to one server. A host with five servers runs five clients.
• Server. The program that exposes tools, resources and prompts.

A single request goes like this. You type "what are my open pull requests?" into the host. The host already asked each connected server what it offers, so the model sees a list of tool names, descriptions and input schemas. The model picks a tool such as list_pull_requests and fills in the arguments. The client sends the call to the server. The server calls GitHub's API, formats the answer and sends it back. The model reads it and replies to you.

The step worth noticing is discovery. The client does not ship with knowledge of any particular server. It connects, asks "what can you do?" and works from the answer. That is why adding a new server to your setup is a config change, not a code change.

Everything travels as JSON-RPC 2.0 messages. The next section shows two of them.

What an MCP server exposes: tools, resources and prompts

The MCP specification defines three building blocks. They differ in who decides when each one is used.

Tools are what most servers are built around, and most clients support them best. Resources and prompts exist in the protocol, but many servers ship only tools.

What the messages look like

To learn what a server offers, the client sends tools/list:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

The server answers with each tool's name, description and a JSON Schema for its inputs. This is the response from the specification's weather example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "City name or zip code" }
          },
          "required": ["location"]
        }
      }
    ]
  }
}

When the model chooses the tool, the client sends tools/call:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "get_weather", "arguments": { "location": "New York" } }
}

The reply carries the output as content blocks and an isError flag. If you know JSON, this is all there is to the wire format: no custom binary protocol and no per-tool SDK.

Local and remote MCP servers

The spec defines two standard ways to carry these messages, called transports.

stdio. The client launches the server as a subprocess and talks to it through standard input and output. The server runs on your machine, uses your files and your network, and stops when the host closes it. Local servers are usually started with a command like npx or uv.

Streamable HTTP. The server is an independent web service with a single HTTP endpoint, for example https://example.com/mcp. Clients send each message as an HTTP POST and the server replies with JSON or a stream of server-sent events. This replaced the older HTTP+SSE transport from the 2024-11-05 spec version. The current spec revision still lists these two as the standard transports.

Rule of thumb: if the tool needs your filesystem, run it locally. If the tool is a service somebody already hosts, use their remote server.

MCP server examples

These are real, public servers that show the range of what MCP covers.

• GitHub. The official GitHub MCP server lets an agent read repositories, issues and pull requests, and take actions on them.
• Playwright. Playwright MCP from Microsoft gives an agent a browser to navigate and interact with pages.
• Filesystem and reference servers. The modelcontextprotocol/servers repository holds reference implementations, including file access, which is the simplest case to read if you want to see how a server is structured.
• Email. Servers that give an agent an inbox to read, search and send. A hosted one is covered in a later section.

For a ranked review of what is worth installing, see our list of the best MCP servers in 2026.

Is an MCP server just an API?

No, but it usually sits on top of one. An API is an address that accepts requests in a fixed shape. An MCP server wraps one or more APIs and adds three things: a standard way to list what exists, descriptions the model can read, and a standard transport. The GitHub MCP server still calls GitHub's REST and GraphQL APIs. It just presents them in a form any MCP client understands.

When you control the code and the agent does one narrow job, calling the API directly is often simpler. When the same tool has to work across several AI clients, or the person using it is not the person who wrote the agent, MCP pays off. The trade-offs, including token cost, are covered in MCP vs API.

How to build a simple MCP server

You need Python 3.10 or higher and the official SDK. This example uses the Python SDK's MCPServer class, which turns type hints and docstrings into tool definitions. I ran it against SDK version 2.3.0.

uv init notes && cd notes
uv venv && source .venv/bin/activate
uv add "mcp[cli]"

Create server.py:

from mcp.server import MCPServer

mcp = MCPServer("notes")

NOTES: list[str] = []


@mcp.tool()
def add_note(text: str) -> str:
    """Save a short note.

    Args:
        text: The note to save.
    """
    NOTES.append(text)
    return f"Saved. {len(NOTES)} note(s) stored."


@mcp.tool()
def list_notes() -> str:
    """Return all saved notes, one per line."""
    return "\n".join(NOTES) if NOTES else "No notes yet."


if __name__ == "__main__":
    mcp.run(transport="stdio")

That is a complete server. The function signature becomes the input schema, and the docstring becomes the description the model reads. Sending it a tools/call request for add_note with {"text": "hi"} returns:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "Saved. 1 note(s) stored." }],
    "isError": false
  }
}

(The SDK also returns a structuredContent field alongside; it is trimmed here.)

One rule for stdio servers: never write to standard output yourself. A stray print() corrupts the JSON-RPC stream. Log to standard error with Python's logging module instead.

Connect it to a client

In Claude Desktop, add the server to claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) under the mcpServers key:

{
  "mcpServers": {
    "notes": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/notes", "run", "server.py"]
    }
  }
}

Restart the app and the two tools appear in the tool list. Other hosts, such as Cursor and VS Code, use a similar JSON block with a command and args for local servers or a url for remote ones.

For anything beyond a demo, the official build-a-server guide covers real API calls, error handling and testing.

Are MCP servers safe?

An MCP server is code you run or a service you trust, and what it returns lands in the model's context. That makes it a security boundary. These cases are public and documented.

Tool poisoning. In April 2025 Invariant Labs described how a malicious server can hide instructions inside a tool's description. The user sees a simple tool name; the model reads the full text and follows the hidden instructions, for example to read an SSH key and send it as a parameter. They also showed that one malicious server can alter how the model uses other, trusted servers connected to the same client. OWASP lists this as MCP Tool Poisoning, a form of indirect prompt injection. If that term is new, what a prompt injection attack is explains the mechanism.

Local servers reachable from the browser. CVE-2025-66416 affected the MCP Python SDK before version 1.23.0: HTTP-based servers on localhost did not have DNS rebinding protection on by default, so a malicious website could send requests to a local server. The fix shipped in 1.23.0. It did not affect stdio servers.

Servers exposed with no authentication. CVE-2026-59726, published in July 2026, covered the agent harness Ruflo: its default docker-compose setup exposed POST /mcp without authentication, which allowed unauthenticated tool calls including shell execution. It received a CVSS 3.1 score of 10.0 and was fixed in version 3.16.3.

What these have in common is that the protocol did not fail. Trust, defaults and missing authentication did. The specification itself says there should always be a human in the loop who can deny tool invocations. Practical rules:

• Know the source. Install servers from the vendor or a repository you can inspect. Treat a random registry listing like a random npm package.
• Narrow credentials. Give each server only the scopes it needs. A read-only token cannot be talked into deleting anything.
• Approve writes. Keep confirmation on for tools that send, delete or pay.
• Bind and authenticate HTTP servers. If you run one yourself, authenticate every request, validate the Origin header, and bind to 127.0.0.1 when it is local.
• Limit how many servers share one agent. Every connected server can influence how the model uses the others.

These measures reduce risk but do not remove it. Free-text tool output cannot be fully sanitized today.

MCP server for email: Atomic Mail Agentic

Email is a good fit for an MCP server because agents need an inbox for sign-up confirmations, replies and notifications, and most existing mail systems were not built for that. Atomic Mail Agentic is an email API for AI agents (open alpha, free, no card). It offers two MCP servers, and the difference between them is the local-versus-remote choice from earlier in this article.

Hosted (remote). https://mcp.atomicmail.ai/mcp runs over Streamable HTTP with nothing to install. You connect with OAuth in the browser, or send an inbox API key as a bearer token to skip the browser:

{
  "mcpServers": {
    "atomicmail": {
      "type": "http",
      "url": "https://mcp.atomicmail.ai/mcp",
      "headers": {
        "Authorization": "Bearer <inbox-api-key>"
      }
    }
  }
}

Without the headers block, the same config connects over OAuth. The tools include read_inbox, read_message, search_messages, send_email, reply_to_message and list_agents, plus a built-in help tool. Hosts with a connector UI, such as ChatGPT and Claude, accept the URL directly.

Local (stdio). @atomicmail/mcp runs through npx. It lets the agent register its own inbox with a proof-of-work sign-up, so no human has to create an account first:

{
  "mcpServers": {
    "atomicmail": {
      "command": "npx",
      "args": ["-y", "@atomicmail/mcp"]
    }
  }
}

It exposes three tools: register, jmap_request and help. Under the hood the mail API is JMAP, which is why a model can write correct calls without a proprietary SDK.

Which to pick: use the hosted server when a person owns the mailbox, or when your host cannot run npx. Use the local one when an autonomous agent should create and own its inbox. The API key for the hosted server is a long-lived secret with full access to that inbox, so keep it in your host's secret store and prefer OAuth wherever a human can click through it. For a full walkthrough, see how to build an AI email agent with its own inbox.

FAQ

What is an MCP server in simple terms?

It is a program that tells an AI app what tools and data it can use, and then does the work when the AI asks. Think of it as a plug-in that follows one shared standard.

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

An API is the interface of a service. An MCP server wraps that interface so any AI client can discover and call it the same way. Most MCP servers call an API underneath.

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

The client lives inside the AI application and connects to servers. The server exposes the tools. One host can run many clients, each linked to one server.

Is ChatGPT an MCP server?

No. ChatGPT is a host that acts as an MCP client. It connects to MCP servers to use their tools.

Do I need to code to use an MCP server?

No. For most servers you add a few lines of JSON to your client's config, or paste a URL into its connector settings. You need code only to build your own.

Where do MCP servers run?

Either on your machine as a subprocess (stdio) or on a provider's infrastructure, reached over HTTPS (Streamable HTTP).

Does MCP replace function calling?

No. Function calling is how a model asks to run a tool. MCP standardizes where the tool definitions come from and how the call is delivered.

Which languages can I use to build an MCP server?

Official SDKs exist for all major languages. Python and TypeScript account for the 97 million monthly SDK downloads Anthropic reported in December 2025.

Are MCP servers free?

The protocol and SDKs are open source. Individual servers vary: many are free, and hosted ones may charge for the underlying service.

Is MCP only for Claude?

No. It started at Anthropic but is now governed by the Agentic AI Foundation, and ChatGPT, Gemini, Microsoft Copilot, Cursor and VS Code support it.

Which MCP server setup fits you

If you are trying MCP for the first time, build the 20-line notes server above and connect it locally. You will learn more in ten minutes than from any diagram. If you need a tool your team already uses, look for its official remote server before running third-party code. And if the missing piece is an inbox for your agent, connect https://mcp.atomicmail.ai/mcp and have it read and answer its first message.

‍

[CTA: Give your agent its own inbox. Connect the hosted MCP server at mcp.atomicmail.ai or run npx @atomicmail/mcp, free during open alpha.]

‍