Back-end12 min read
What is MCP (Model Context Protocol)? A practical guide
What is the Model Context Protocol? MCP explained with two servers I use every day: host, client and server, tools, transports and a minimal TypeScript server.

If you use Claude Code, Cursor or any AI inside your editor, you've already run into the acronym MCP. It shows up in config files, in "connector" lists, in every post about agents.
I use MCP every day. I have my own server that draws characters for one of my apps, and I use an extended version of Talk to Figma to draw in Figma straight from the terminal. The illustrations in this post came from there.
So this is the post I wish I'd read when I started: what MCP is, how the pieces talk to each other, and what a real server looks like on the inside.
TL;DR#
- MCP is an open standard for connecting AI apps to external systems: files, databases, APIs, Figma.
- Three pieces: the host (the app you use), one client per connection and the server (whoever offers the tools).
- The server offers tools, resources and prompts. Tools are the most used: actions the model decides to call.
- Under the hood it's JSON-RPC 2.0, over
stdio(local process) or Streamable HTTP (remote server). - The spec changed on 2026-07-28: it became stateless, dropped the
initializehandshake, and marked sampling and roots as deprecated. A tutorial from 2025 is already out of date. - A tool is code running with your permissions. Install an MCP server with the same care you'd give a dependency.
The problem MCP solves#
Picture three AI apps (Claude Code, Cursor and the app you're building) and four tools you want to use with them: GitHub, Figma, Postgres and Slack.
Without a standard, each app needs its own integration with each tool. That's 3 × 4 = 12 integrations, each with its own format, its own auth and its own bugs. A new app comes along? Four more. A new tool? Three more.
With MCP, the math turns into a sum: each app implements one MCP client and each tool gets one MCP server. That's 3 + 4 pieces, and any app can talk to any tool.
A USB-C port for AI#
The official documentation defines MCP as an open-source standard for connecting AI applications to external systems. And it uses an image that helps a lot: think of MCP as a USB-C port for AI applications.
Before USB-C, every device had its own cable. Today one cable works for the charger, the monitor and the external drive. MCP does that between AI and tools: the app doesn't need to know anything about Figma, it just needs to speak MCP.
A bit of history: Anthropic launched MCP in November 2024 and, in December 2025, donated the protocol to the Agentic AI Foundation, part of the Linux Foundation. In the donation announcement, Anthropic mentioned more than 10,000 active public MCP servers.
The three pieces: host, client and server#
This is the part that confuses people the most, so I'll use my own setup as the example.
- Host is the AI app you use. In my case, Claude Code. It keeps the conversation, talks to the model and asks for your permission before running a tool (unless you've allowed it).
- Client is the piece inside the host that keeps one connection to one server. The host creates a client for each configured server.
- Server is the program that offers the tools. It can run on your machine or somewhere else.
My two local servers are very different on the inside:
- the character server assembles characters in SVG from the pieces in a brandbook and returns the finished image;
- TalkToFigma doesn't draw anything by itself: it forwards the commands, over a local WebSocket, to a plugin open in Figma. The plugin is what touches the layers.
To Claude Code, both are the same: an MCP server with a list of tools.
What a server offers#
A server can offer three kinds of things, which the spec calls primitives. The difference between them is who decides to use them.
Tools: the model decides#
Tools are actions. Searching for something, creating a file, sending a message, generating a character. The server lists its tools with a name, a description and the shape of the parameters, and the model decides when to call each one. It's by far the most used primitive: my two servers only have tools.
Resources: the app decides#
Resources are data that give context: the contents of a file, a database schema, the git history. Each one has a URI, and the app decides what to attach to the conversation.
Prompts: you decide#
Prompts are ready-made message templates that you pick on the spot, like a slash command. Talk to Figma ships a few, like design_strategy, with best practices for working in Figma.
What about the client side?#
The opposite direction exists too: the server can ask the client for things. This is where the 2026-07-28 spec changed a lot:
- Elicitation stays: the server asks you for some information in the middle of a task (a login, a confirmation).
- Sampling (the server asking the host's model for a response) and Roots (the client telling the server which folders it can see) were marked as deprecated. They still work, but new implementations shouldn't use them.
If you're reading a tutorial from 2025, this is where it will mislead you the most.
Under the hood: JSON-RPC#
Every conversation between client and server is JSON-RPC 2.0: JSON messages with a method, params and an id to match the request with the response. To call a tool, the client sends a tools/call:
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "greet", "arguments": { "name": "Yasmin" } } }And the server replies with the result. This response is real: it came from the minimal server I show further down.
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [{ "type": "text", "text": "Hello, Yasmin!" }],
"resultType": "complete"
}
}In the current version, every request also carries the protocol version and the client's capabilities in a _meta field. The spec leaves that field out of its examples to keep them short, and I did the same.
The transports#
The JSON has to travel somehow, and the spec defines two transports:
- stdio: the host starts the server as a child process and talks over standard input and output, one message per line. That's what my two servers use.
- Streamable HTTP: each message is a
POSTto a single endpoint, and the response comes back as JSON or as an SSE stream. That's how you run a remote server that serves many clients.
The old HTTP+SSE transport, which shows up in a lot of tutorials, has been deprecated since version 2025-03-26.
A tool call, step by step#
Putting it all together, this is what happens when I ask Claude Code for a character:
- The client discovers the server. In the current spec, with
server/discover, which returns the versions and capabilities. In the 2025 versions, it was theinitializehandshake. - The client asks for the list of tools (
tools/list). My server returns 11, each with a name, a description and the parameter schema. - You ask, in natural language: "draw a 70-year-old person".
- The model picks the tool by reading the descriptions, and builds the arguments:
{ anos: 70 }. - The host asks for your permission. You can say no.
- The model hands the call to the client.
- The client sends the
tools/calland the server runs the code. - The result comes back: in my case, a PNG image and a JSON with the seed and the traits.
- The model replies with the character.
Notice that the model never talks to the server. It only picks the tool and the arguments. The one talking to the server is the client, inside the host, and only after you say ok.
A minimal server in TypeScript#
The fastest way to understand it is to write one. The official TypeScript SDK is on version 2, with separate packages for the server and the client:
npm install @modelcontextprotocol/server zodAnd this is a whole server, with one tool:
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
// serveStdio calls this for every instance it needs
function createServer() {
const server = new McpServer({ name: "hello-mcp", version: "1.0.0" });
server.registerTool(
"greet",
{
description: "Greets someone by name. Use it when the user asks to say hi to someone.",
inputSchema: z.object({ name: z.string().describe("Who to greet") }),
},
async ({ name }) => ({
content: [{ type: "text", text: `Hello, ${name}!` }],
}),
);
return server;
}
serveStdio(createServer, {
onerror: (error) => console.error("hello-mcp error:", error),
});
console.error("hello-mcp running on stdio"); // stderr: stdout belongs to the protocolThree details that matter:
- The description is what the model reads to decide whether to call the tool. Write it as if it were for someone on your team.
- The zod schema becomes JSON Schema in
tools/list. That's how the model knows which arguments to send. - No
console.log. On stdio, standard output belongs to the protocol: any stray text there breaks the messages. Logs go toconsole.error.
serveStdio handles both new clients and clients that still open with the 2025 initialize. I tested both by sending the messages by hand, and the server answered correctly in each version.
To plug it into Claude Code, after compiling:
claude mcp add hello-mcp -- node build/index.jsAnd to test it with no AI at all, the Inspector lists the tools from the command line:
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/listWhat it looks like in my real server#
The character server has 11 tools. This is the main one, with the names translated to English (on the server it's called gerar_personagem, which is the name that shows up in the diagrams):
server.registerTool(
"generate_character",
{
title: "Generate character",
description:
"Generates a character from a seed (the same seed always gives the same character). " +
"Without a seed, draws a new one. Traits in 'locked' are kept. 'age' shows the same person in another phase of life. " +
"Returns the image and the traits.",
inputSchema: { seed: z.string().optional(), locked: partialTraits.optional(), ...visual },
annotations: { readOnlyHint: true },
},
async ({ seed, locked, ...v }) => {
const s = seed ?? newSeed();
return respond(draw(s, locked), s, v);
},
);And the response returns two things: the image, for you to see, and a JSON, so the model can keep working:
return {
content: [
{ type: "image", data: png.toString("base64"), mimeType: "image/png" },
{ type: "text", text: JSON.stringify(info, null, 2) }, // seed, age and traits
],
};That's how the character in the animation was made: I asked for a happy 70-year-old person, and the server returned the image with the seed 0d2kajwu. With the same seed, another tool shows the same person in another phase of life.
This server is still on SDK v1 (@modelcontextprotocol/sdk), wired up with server.connect(new StdioServerTransport()). It works with the Claude Code I use today, but the new documentation warns that this approach only serves 2025-era clients. For a new server, I'd start on v2 right away, with serveStdio.
What I learned#
The description is the prompt. The model doesn't read your code, it reads the description of the tool and its parameters. In my server, each drawing style has a sentence explaining what it changes, because that's all the model sees when it's choosing.
Give the model a way to find the valid values. I created a listar_opcoes tool that just lists the ids of the pieces and colors. The description of the character assembly tool tells the model to check it, and the invalid trait error points to it too. That way the model has somewhere to look, instead of making up an id that doesn't exist.
Return what the model will need in the next step. The seed in the JSON looks like a detail, but it's what lets you ask for "now this same person at 10 years old".
Not everything has to go through MCP. The illustrations in this post were drawn in Figma from the terminal, but the commands I added to the Talk to Figma plugin I call from a script that talks directly to the relay, in a batch of more than 200 steps. MCP is the door for AI to talk to the tool. When a script is in the driver's seat, a simple client does the job.
Security precautions#
The spec itself is blunt: tools represent arbitrary code execution. So:
- Know who runs what. A
stdioserver is a process on your machine, with your permissions: it reads your files and accesses your network. A remote server runs on someone else's machine, and everything you send to it leaves your computer. - Install an MCP server like you install a dependency. Read the code, pin the version, be wary of servers without a clear owner. With Talk to Figma, I made the relay accept only connections from
127.0.0.1and removed Google Analytics from the plugin before using it. - Don't auto-approve everything. The spec asks the host to get your consent before calling any tool, and says you should always be able to say no. Allowing everything means giving that up.
- Annotations are hints, not guarantees.
readOnlyHint: truesays the tool only reads, but the spec says to treat annotations as untrusted unless the server is trusted. - Be careful with what comes back. A tool's result goes into the model's context. A web page or an issue can carry hidden instructions, and the model may try to follow them.
References#
Read next

Back-end18 min read
What is RAG? Indexing, hybrid search and a real case

Front-end16 min read
Multilingual SEO in React: hreflang, prerendering, sitemap

Front-end15 min read
How I make AI videos with Remotion: a real case study