What Is an MCP Server? A Developer's Beginner Guide (2026)

The acronym you cannot avoid

If you have touched an AI coding tool in the last twelve months, you have seen the letters MCP. They show up in Claude Code docs, in the Cursor settings panel, in every new Anthropic launch video, and now in the OpenAI Codex docs too. In April 2026 the MCP Directory we maintain at mcp.developersdigest.tech lists 271 active servers. The official Anthropic MCP registry tracks thousands more.

Most beginner posts either wave their hands ("it connects AI to tools") or drown you in JSON-RPC frame diagrams. This guide sits in between. Everything you are about to read is pulled directly from the official spec at modelcontextprotocol.io and the Claude Code MCP documentation. If a claim is not sourced to a primary doc, it is not in this post.

What MCP actually is, in the spec's own words

The Model Context Protocol is described on the official introduction page as "an open-source standard for connecting AI applications to external systems." The same page uses the now-famous analogy: "Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems."

That is the whole idea. Before MCP, every AI tool that wanted to talk to your filesystem, your database, or your Slack had to ship a bespoke integration. Anthropic open-sourced MCP in November 2024 to replace that N-by-M mess with a single protocol. One server, every client.

The Wikipedia entry on MCP and coverage in The New Stack both note that the approach worked. OpenAI formally adopted the protocol in March 2025, and the OpenAI Codex docs at developers.openai.com/codex/mcp now list first-party MCP support. Microsoft Copilot Studio, Google's Gemini CLI, Cursor, VS Code, and Claude Code all ship MCP clients today. In December 2025 Anthropic donated the protocol to the Agentic AI Foundation under the Linux Foundation, with Block and OpenAI as co-founders.

That is what "won" looks like for a protocol: your competitor ships it.

The architecture: hosts, clients, servers

MCP defines three roles.

A host is the AI application you sit in front of. Claude Code, Cursor, ChatGPT Desktop, Gemini CLI. The host runs the LLM and owns the conversation.

A client is the connection the host opens for each server. One client per server, one-to-one.

A server is a small program that exposes capabilities over the protocol. It runs locally as a subprocess or remotely as an HTTP service. It does not care which host is on the other end.

The transport between client and server is JSON-RPC 2.0 encoded as UTF-8. That is fixed by the spec.

The three primitives

Every MCP server exposes some combination of three primitives. This is the part that trips up beginners the most, because they look similar but have different ownership semantics.

Tools

From the spec: "Tools in MCP are designed to be model-controlled, meaning that the language model can discover and invoke tools automatically based on its contextual understanding and the user's prompts."

Tools are functions the model can call. The server declares them by listing a name, description, and inputSchema (JSON Schema). When the client asks, the server returns the list. When the model wants to invoke one, it sends tools/call with arguments, and the server returns a result.

A tool definition from the spec looks like this:

{
  "name": "get_weather",
  "title": "Weather Information Provider",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or zip code" }
    },
    "required": ["location"]
  }
}

The spec is explicit that "there SHOULD always be a human in the loop with the ability to deny tool invocations." That is why Claude Code prompts you before running a new tool the first time.

Resources

Resources are "application-driven" context: files, database rows, API payloads, anything the host might want to feed into the model. Each resource is identified by a URI. The spec defines standard schemes like file://, https://, and git://, and allows custom ones.

Clients call resources/list to discover what is available, then resources/read with a URI to fetch contents. Resources can also be subscribable. The server notifies the client when a file changes.

The key distinction: the host decides when to pull in a resource, not the model. In Cursor, the @ picker that lets you attach a file to a prompt is a resource picker. Tools are for the model to invoke; resources are for the app (or the user) to attach.

Prompts

Prompts are "user-controlled" templates. The spec describes them as "structured messages and instructions for interacting with language models," and the docs show the canonical UI: slash commands.

A prompt template is a named, argument-accepting message builder. The server returns a list of message objects when asked. Most MCP clients surface these as slash commands like /review-code or /summarize-thread.

The mental model: tools are the model's hands, resources are its eyes, prompts are its phrasebook.

Transports: stdio and streamable HTTP

There are two transports in the current spec, and exactly one of them is new enough that most beginner posts get it wrong.

The spec is direct: "The protocol currently defines two standard transport mechanisms for client-server communication: stdio and Streamable HTTP."

stdio

The client launches the server as a subprocess. JSON-RPC messages flow over stdin and stdout, delimited by newlines. Logs go to stderr. This is the local, on-your-machine transport.

Streamable HTTP

Introduced in protocol version 2025-03-26, Streamable HTTP is now the standard remote transport. It uses a single HTTP endpoint that accepts both POST (client-to-server messages) and GET (open an SSE stream for server-to-client messages). It supports resumable sessions via an Mcp-Session-Id header.

The older HTTP+SSE transport from protocol version 2024-11-05 is deprecated. The transports spec page includes this note verbatim: "This replaces the HTTP+SSE transport from protocol version 2024-11-05." If an article tells you to "set up an SSE server," it is at least a year out of date. The Claude Code docs also flag this directly: "The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available."

Custom transports are allowed. The spec only requires that they preserve JSON-RPC semantics and lifecycle.

The clients you can actually use today

Rather than hand-wave ecosystem claims, here is what the primary sources show as of April 2026.

• Claude Code ships claude mcp add as a first-class CLI for managing servers. Docs at code.claude.com/docs/en/mcp.
• Cursor reads ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). Docs at cursor.com/docs/context/mcp.
• Claude Desktop supports MCP via the Developer settings pane.
• VS Code ships MCP support in GitHub Copilot Chat per code.visualstudio.com/docs/copilot/chat/mcp-servers.
• OpenAI Codex supports MCP per developers.openai.com/codex/mcp.
• ChatGPT exposes MCP servers via Connectors per developers.openai.com/api/docs/mcp/.
• Gemini CLI, MCPJam, Continue.dev, and dozens of others are listed on the official clients page at modelcontextprotocol.io/clients.

The protocol is client-agnostic by design. Write once, connect anywhere.

Installing your first MCP server in Claude Code

The Claude Code docs define three scopes for server configuration, and the precise storage location for each.

Pick one and go. Here are three real installs using real servers from our directory.

A local stdio server: filesystem

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem

This gives the model scoped file operations. The server is listed as an official reference implementation on the modelcontextprotocol GitHub org.

A remote HTTP server: Notion

claude mcp add --transport http notion https://mcp.notion.com/mcp

Notion publishes an official MCP endpoint. No local install needed. Claude Code handles the OAuth flow on first use.

A remote HTTP server with a header: custom API

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Per the Claude Code docs, all flags must come before the server name, and the -- separator precedes the subprocess command for stdio servers.

After any install, type /mcp inside Claude Code to see the status of every configured server, their tool counts, and reconnect any that dropped.

Installing in Cursor

Cursor's docs show the same config shape for every server, just in JSON instead of a CLI.

Create ~/.cursor/mcp.json for global install or .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {}
    },
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Cursor supports ${env:VARIABLE_NAME} interpolation inside the config, which is the cleanest way to inject API keys without committing them.

Picking MCPs that are actually worth it

The MCP Directory at mcp.developersdigest.tech indexes 271 active servers. You do not need 271. You need five. A short list of reference servers from the Anthropic-maintained modelcontextprotocol/servers repo, all real and listed in our directory:

• @modelcontextprotocol/server-filesystem - sandboxed file operations.
• @modelcontextprotocol/server-git - read, search, and diff Git repos.
• @modelcontextprotocol/server-fetch - fetch URLs and convert HTML to clean markdown.
• @modelcontextprotocol/server-postgres - read-only Postgres queries.
• @modelcontextprotocol/server-sequential-thinking - step-by-step reasoning scaffold.

Our full opinionated shortlist lives in 271 MCP Servers Exist. These 5 Actually Make Claude Code Better.. The filters we apply: actively maintained, one-command install, fills a gap Claude Code does not already cover, returns clean structured output.

Security: what the spec says, and what to actually do

The spec takes security seriously, and Streamable HTTP has three explicit warnings you should internalize before exposing a server.

From the transports spec: "Servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding attacks. When running locally, servers SHOULD bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0). Servers SHOULD implement proper authentication for all connections."

Translation: do not run a public MCP server without auth, do not bind 0.0.0.0 on a dev machine, and validate Origin.

On the tools side, the spec requires client-side defences too: "Prompt for user confirmation on sensitive operations. Show tool inputs to the user before calling the server, to avoid malicious or accidental data exfiltration. Validate tool results before passing to LLM."

Practical rules for a beginner:

1. Install servers from publishers you trust. The Anthropic reference servers and the mcp-registry publishers are the safest defaults.
2. Use project scope only for servers the whole team should have. Everything experimental stays in local scope.
3. API keys go in env blocks or environment variables, never in committed config.
4. Read the server's README before you let it touch your filesystem. "Sandboxed" servers like server-filesystem let you whitelist directories.

Writing your own MCP server

The fastest path is the official TypeScript SDK.

npm init -y
npm install @modelcontextprotocol/sdk zod

A minimal server with one tool, built from the shape in the official quickstart:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "hello-mcp", version: "1.0.0" });

server.tool(
  "greet",
  "Return a friendly greeting",
  { name: z.string() },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}.` }],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

Run it once with node server.js to sanity check. Then register it with Claude Code:

claude mcp add --transport stdio hello -- node /absolute/path/to/server.js

Reload Claude Code, type /mcp, and hello should show up with one tool. Python, Kotlin, Java, C#, Rust, and Swift SDKs are all listed on modelcontextprotocol.io if TypeScript is not your stack.

For deeper dives on building servers, see the official SDK quickstart at modelcontextprotocol.io/quickstart/server and the concepts docs linked in the references below.

What MCP is not

A quick reality check, because misconceptions spread fast.

• MCP is not an agent framework. It does not schedule tasks, plan steps, or orchestrate loops. It is a protocol for exposing capabilities to a model.
• MCP is not a replacement for function calling inside a single LLM provider's SDK. It is the protocol that makes function calling portable across clients.
• MCP does not run the model. The host does. The server just exposes tools, resources, and prompts.
• MCP is not secure by default. The spec defines the mechanics, not the policy. That is on you.

Next steps

If you are new to MCP, do these four things in order:

1. Install Claude Code or Cursor if you do not have one.
2. Run claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem or paste the Cursor config above.
3. Open /mcp (Claude) or the MCP panel (Cursor) and confirm the server is connected.
4. Ask your agent to list the contents of a directory. Watch the tool call fire.

That is the entire loop. Everything else - custom servers, remote deployments, prompts, resources - is the same pattern scaled up.

If you want a curated shortlist, read our 271 MCP Servers post. If you want to browse the full ecosystem, the MCP Directory at mcp.developersdigest.tech is kept current.

USB-C took a decade to win. MCP took about eighteen months. That tells you exactly how starved the AI tooling space was for a standard.

Frequently Asked Questions

What is the difference between MCP tools, resources, and prompts?

Tools are functions the model can call - they are model-controlled. Resources are data the host application or user attaches to context - they are application-controlled. Prompts are templates that generate structured messages - they are user-controlled via slash commands. The spec distinguishes them by who initiates: the model decides to use tools, the app decides to load resources, and the user decides to run prompts.

Is MCP only for Claude, or does it work with other AI tools?

MCP works with any client that implements the protocol. As of April 2026, that includes Claude Code, Claude Desktop, Cursor, VS Code (via GitHub Copilot Chat), OpenAI Codex, ChatGPT, and Gemini CLI. OpenAI formally adopted MCP in March 2025. The protocol was donated to the Linux Foundation in December 2025, making it a true industry standard rather than an Anthropic-only feature.

What is the difference between stdio and HTTP transport?

Stdio transport runs the server as a local subprocess on your machine, with JSON-RPC messages flowing over stdin/stdout. HTTP transport (specifically Streamable HTTP since protocol version 2025-03-26) runs the server remotely and communicates over a single HTTP endpoint with POST for requests and GET for SSE streaming. Use stdio for local servers, HTTP for hosted services like Notion's official endpoint.

Is the SSE transport deprecated?

Yes. The HTTP+SSE transport from protocol version 2024-11-05 is deprecated. The Claude Code docs state this explicitly. Streamable HTTP is the current standard for remote servers. If a tutorial tells you to set up an SSE server, it is outdated.

How do I pass API keys to an MCP server securely?

Use environment variables or the env block in your config. In Claude Code, you can pass environment variables in the CLI install. In Cursor, use ${env:VARIABLE_NAME} interpolation inside mcp.json to inject secrets from your environment. Never commit API keys to version control.

Can MCP servers run arbitrary code on my machine?

Yes, stdio servers run as local processes with your user permissions. That is why the spec emphasizes human-in-the-loop confirmation for tool invocations. Only install servers from publishers you trust. The Anthropic reference servers and verified mcp-registry publishers are the safest defaults.

What languages can I use to write MCP servers?

The official SDKs support TypeScript, Python, Kotlin, Java, C#, Rust, and Swift. TypeScript and Python are the most mature. You can write servers in any language as long as you implement the JSON-RPC 2.0 protocol over stdio or HTTP.

How many MCP servers should I install?

Start with one or two. The filesystem and fetch reference servers cover most workflows. Adding too many servers increases startup time and cognitive overhead. Install servers as you hit real gaps, not preemptively.

References

• modelcontextprotocol.io/introduction - official definition, USB-C analogy, ecosystem list.
• modelcontextprotocol.io/docs/concepts/transports - stdio and Streamable HTTP spec, HTTP+SSE deprecation note.
• modelcontextprotocol.io/docs/concepts/tools - tool primitive, schema, safety warnings.
• modelcontextprotocol.io/docs/concepts/resources - resources, URI schemes, subscriptions.
• modelcontextprotocol.io/docs/concepts/prompts - prompt templates and user-controlled model.
• modelcontextprotocol.io/clients - official list of supported clients.
• code.claude.com/docs/en/mcp - Claude Code install commands, scope storage paths, transport notes.
• cursor.com/docs/context/mcp - Cursor config file locations and JSON format.
• developers.openai.com/codex/mcp - OpenAI Codex MCP support.
• developers.openai.com/api/docs/mcp/ - ChatGPT MCP connector docs.
• code.visualstudio.com/docs/copilot/chat/mcp-servers - VS Code MCP support.
• en.wikipedia.org/wiki/Model_Context_Protocol - adoption timeline, Linux Foundation donation, OpenAI adoption date.
• thenewstack.io/why-the-model-context-protocol-won - industry context on MCP adoption.
• github.com/modelcontextprotocol/servers - official reference servers.
• mcp.developersdigest.tech - the MCP Directory, 271 indexed servers as of April 2026.