Skip to content

What is an MCP server?

Mikhail Bodnarchuk

Definition

An MCP server is a program that exposes tools, resources and prompts to AI applications through the Model Context Protocol (MCP), an open standard built on JSON-RPC 2.0. An AI host such as an IDE, a coding agent or a chat app connects to it, discovers what it offers, and lets the model call its tools.

How does an MCP server work?

MCP has three participants. The host is the AI application, such as an IDE or a coding agent. Inside it, one client per connection talks to one server, the program that provides context and actions (MCP architecture). A host connected to five servers runs five clients.

The protocol has two layers. The data layer defines JSON-RPC 2.0 messages. The transport layer carries them, over standard input and output (stdio) for local servers or Streamable HTTP for remote ones.

A typical exchange under the current revision:

  1. Discovery (optional). The client calls server/discover and gets the server's supported protocol versions, capabilities and identity in one reply.
  2. Listing. The client calls tools/list and passes the tool names, descriptions and JSON Schemas to the model.
  3. Calling. The model picks a tool. The client sends tools/call with arguments that match the tool's inputSchema.
  4. Result. The server returns content, plus structuredContent when the tool declares an outputSchema.

Every request carries the protocol version and the client's capabilities in its _meta field, so the server needs nothing from earlier requests to answer it.

What can an MCP server expose?

A server offers three building blocks (Understanding MCP servers). They differ in who decides to use them.

PrimitiveWhat it isControlled byMethods
ToolsFunctions with typed inputs that can write data, call APIs or change filesThe modeltools/list, tools/call
ResourcesRead-only context such as file contents, schemas or docsThe applicationresources/list, resources/read
PromptsInstruction templates that combine tools and resourcesThe userprompts/list, prompts/get

In the other direction, a server can ask the user for missing input or a confirmation through elicitation, a client feature.

What changed in MCP spec 2026-07-28?

MCP versions are dates in YYYY-MM-DD form, marking the last backwards-incompatible change. The current revision is 2026-07-28 (versioning). Guides written for earlier revisions describe a session handshake, so check which revision a tutorial targets.

Up to 2025-11-252026-07-28
Session startinitialize handshakeNone. Each request declares its version in _meta
Capability discoveryDuring the handshakeserver/discover, or per request
Version mismatchSettled in the handshakePer-request UnsupportedProtocolVersionError
Roots, sampling, protocol loggingSupportedDeprecated

The deprecation notes in the architecture overview suggest replacements: pass paths through tool parameters instead of roots, call your LLM provider directly instead of sampling, and log to stderr or OpenTelemetry instead of protocol logging.

How do you build a minimal MCP server?

This server exposes one tool that lists failed tests from a JUnit XML report. It uses the v2 TypeScript SDK, @modelcontextprotocol/server, which implements the 2026-07-28 spec.

npm init -y && npm pkg set type=module
npm install @modelcontextprotocol/server zod
// server.ts
import { readFile } from "node:fs/promises";
import { resolve, sep } from "node:path";
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

// The tool may read only files inside this folder.
const REPORTS_DIR = resolve(process.env.REPORTS_DIR ?? "reports");

// serveStdio can ask for a fresh instance per client, so build one per call.
function createServer() {
  const server = new McpServer({ name: "junit-report", version: "1.0.0" });

  server.registerTool(
    "list_failed_tests",
    {
      description: "List failed test cases in a JUnit XML report from the reports folder",
      inputSchema: z.object({
        file: z.string().describe("Report file name, for example report.xml"),
      }),
    },
    async ({ file }) => {
      const path = resolve(REPORTS_DIR, file);
      if (!path.startsWith(REPORTS_DIR + sep)) {
        return { content: [{ type: "text", text: "File is outside the reports folder" }], isError: true };
      }
      const xml = await readFile(path, "utf8");
      const failed = [...xml.matchAll(/<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g)]
        .filter((m) => /<(failure|error)\b/.test(m[2] ?? ""))
        .map((m) => m[1].match(/(?:^|\s)name="([^"]*)"/)?.[1] ?? "unnamed");
      return {
        content: [{ type: "text", text: failed.length ? failed.join("\n") : "No failed tests" }],
      };
    },
  );

  return server;
}

serveStdio(createServer, { onerror: (e) => console.error("server error:", e) });
console.error("junit-report MCP server running on stdio"); // stdout is reserved for JSON-RPC

We ran it on 2026-11-19 with @modelcontextprotocol/server 2.4.0 and zod 4.6.7 on Node.js 22.9 (node --experimental-strip-types server.ts), and it passed tsc --strict. A client from the official @modelcontextprotocol/client package connected over stdio twice. With version negotiation set to auto, discovery returned ["2026-07-28"]. With the default legacy initialize handshake, the same server answered too, because serveStdio handles both eras (build guide). In both runs, tools/list returned list_failed_tests. The call on a report with one failure and one error returned the two test names. A call with ../server.ts returned the error result instead of the file.

Two details matter. A stdio server must never print to stdout, because stdout carries the JSON-RPC messages. And the path check is there because the model chooses the arguments: without it, the tool would read any file the process can open.

What is the difference between a local and a remote MCP server?

Local (stdio)Remote (Streamable HTTP)
Where it runsA child process on the user's machineA web service
Clients servedUsually oneUsually many
CredentialsTaken from the environmentOAuth 2.1, when the server requires authorization
Typical useFile system, local git, dev toolsSaaS products, shared company data

The authorization spec makes authorization optional. Stdio servers should not follow it and should read credentials from the environment instead.

What should you check before connecting an MCP server?

The spec is direct about risk: tools are arbitrary code execution, hosts must get user consent before invoking a tool, and tool descriptions or annotations count as untrusted unless the server is trusted (MCP specification).

  1. Read the code or know the publisher. A malicious server can describe one action and perform another.
  2. Scope every credential. The security best practices say an MCP server must not accept tokens that were not issued for it. They call forwarding a client's token to a downstream API, known as token passthrough, an anti-pattern.
  3. Limit what each tool can reach. Restrict paths, hosts and database rows in the tool itself, as in the example above.
  4. Keep writes behind confirmation. Use the host's approval prompt or elicitation for anything that changes data.
  5. Log every call. Record the tool, arguments and result so you can audit what an agent did.

MCP is widely used. Anthropic reported more than 10,000 active public servers and over 97 million monthly SDK downloads across Python and TypeScript when it donated MCP to the Linux Foundation's Agentic AI Foundation (Anthropic, 2025-12-09). Those are Anthropic's own figures.

Our post on APIs that AI agents can call covers credential and identity problems found in public MCP servers. To give agents safe access to your own systems, see AI integration and API services. For how coding agents use these servers day to day, see agentic coding.

Sources

  1. Specification (current revision 2026-07-28), Model Context Protocol, 2026-07-28
  2. Versioning and Compatibility, Model Context Protocol, 2026-07-28
  3. Versioning, Model Context Protocol, 2026-11-18
  4. Architecture overview, Model Context Protocol, 2026-11
  5. Understanding MCP servers, Model Context Protocol, 2026-11
  6. Build an MCP server, Model Context Protocol, 2026-11
  7. SDKs, Model Context Protocol, 2026-10-31
  8. Authorization, Model Context Protocol, 2026-07-28
  9. Security best practices, Model Context Protocol, 2026-11-18
  10. @modelcontextprotocol/server 2.4.0, npm (MCP TypeScript SDK), 2026-10-23
  11. Donating the Model Context Protocol and establishing the Agentic AI Foundation, Anthropic, 2025-12-09

Frequently asked questions

What is the difference between MCP and an API?

An API is the interface of one service. MCP is a common protocol that lets any compatible AI host discover and call tools without custom glue code per service. Many MCP servers are thin wrappers that call an existing API on the model's behalf.

Does ChatGPT use MCP?

Yes. When Anthropic donated MCP to the Agentic AI Foundation on 2025-12-09, it listed ChatGPT, Cursor, Gemini, Microsoft Copilot and Visual Studio Code among the products that had adopted it (Anthropic).

Is an MCP server free or paid?

MCP is an open-source protocol, its official TypeScript SDK is published under Apache-2.0 (npm) and its Python SDK under MIT (PyPI), and it is now governed by the Agentic AI Foundation, a directed fund under the Linux Foundation. A server you write yourself costs only its hosting. Servers run by vendors follow the pricing of the product behind them.

Which languages can I write an MCP server in?

The official SDK list rates TypeScript, Python, C#, Go, Rust and Ruby as Tier 1, Java as Tier 2, and Swift, PHP and Kotlin as Tier 3 (MCP SDKs). Each SDK adopts new protocol revisions on its own schedule, so check which revision it supports.

Mikhail BodnarchukMikhail BodnarchukFounder of Codeception and CodeceptJSBoth are open-source testing frameworks: Codeception for PHP, CodeceptJS for JavaScript.LinkedInGitHub

Building with AI agents? Talk to an engineer.