This is an open-source standard for connecting A.I applications to external systems. Using MCP, A.I applications like Claude or ChatGPT can connect to data sources (e.g. local files, databases), tools (e.g. search engines, calculators) and workflows (e.g. specialized prompts), enabling them to access key information and perform tasks.

The Problem That MCP Exists to Solve

Before MCP existed, here is what happened every time you wanted to give an AI agent access to an external tool or system. Say you are building a LangGraph agent and you want it to be able to:

• Read files from Google Drive
• Create tasks in Notion
• Look up employee records in HiBob
• Send Slack messages

For each one of those, you had to write a completely custom function, handle authentication your own way, manage errors your own way, format the data your own way, and wire it all up manually. If you later switched from LangGraph to a different agent framework, you would have to rewrite everything. If someone else built a better Google Drive connector, you could not easily plug it in; theirs was written for their system, not yours.

Why Does MCP Matter?

Depending on where you sit in the ecosystem, MCP can have a range of benefits.

• Developers

  MCP reduces development time and complexity when building, or integrating with, an AI application or agent.

• AI Applications or Agents

  MCP provides access to an ecosystem of data sources, tools and apps which will enhance capabilities and improve the end-user experience.

• End-Users

  MCP results in more capable AI applications or agents which can access your data and take actions on your behalf when necessary.

The Three Roles in MCP

Every MCP setup has exactly three roles. Understanding these is the foundation of everything else.

MCP Server

This is what exposes tools or data to the AI. A program that provides context to MCP clients. It is a program that says "here are the things I can do." For example, a Notion MCP server says: "I can read pages, create pages, update databases, search content." A HiBob MCP server would say: "I can get employee records, check leave balances, update profiles." The server does not know anything about AI; it just knows how to expose its capabilities in the MCP standard format.

MCP Client

This is the component inside your AI app that talks to the server. It is the bridge. It asks the server "what can you do?" and then makes requests on behalf of the AI. A component that maintains a connection to an MCP server and obtains context from an MCP server for the MCP host to use.

MCP Host

This is the application the user is actually interacting with. The AI application that coordinates and manages one or multiple MCP clients. Claude Desktop is a host. Claude Code is a host. Your custom LangGraph app would be a host.

The MCP client asks its server for a list of tools and resources the server provides; the server replies with a natural-language description of the capabilities of each tool and the expected format to call the tool. This information is given to the LLM; if it requires the services of one of these tools, the MCP host will instruct the relevant MCP client to call the tool. The MCP server performs the tool action and returns the results, which the MCP host then injects into the LLM conversation.

MCP follows a client-server architecture where an MCP host establishes connections to one or more MCP servers. The MCP host accomplishes this by creating one MCP client for each MCP server. Each MCP client maintains a dedicated connection with its corresponding MCP server.

Local MCP servers that use the STDIO transport typically serve a single MCP client, whereas remote MCP servers that use the Streamable HTTP transport will typically serve many MCP clients.

Note that MCP server refers to the program that serves context data, regardless of where it runs. MCP servers can execute locally or remotely. For example, when Claude Desktop launches the filesystem server, the server runs locally on the same machine because it uses the STDIO transport. This is commonly referred to as a "local" MCP server. The official Sentry MCP server runs on the Sentry platform, and uses the Streamable HTTP transport. This is commonly referred to as a "remote" MCP server.

What MCP Servers Actually Expose (The Three MCP Primitives)

MCP primitives are the most important concept within MCP. They define what clients and servers can offer each other. These primitives specify the types of contextual information that can be shared with AI applications and the range of actions that can be performed. An MCP server can expose three types of things.

1. Tools: Actions the AI Can Take

Things that do something. Examples: "create a Notion page", "send a Slack message", "query a database", "book a calendar event." Tools are what the AI calls when it decides it needs to take an action. Tools are executable functions that AI applications can invoke to perform actions. They change state, interact with the world, take actions. The AI reads the tool's name and description, decides if it needs it, and calls it.

Here is a real tool definition in the JSON format MCP uses:

{
  "name": "create_hibob_leave_request",
  "description": "Submit a leave request for an employee in HiBob. Use this when an employee wants to request time off.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "employee_id": {
        "type": "string",
        "description": "The unique ID of the employee in HiBob"
      },
      "start_date": {
        "type": "string",
        "format": "date",
        "description": "Leave start date in YYYY-MM-DD format"
      },
      "end_date": {
        "type": "string",
        "format": "date"
      },
      "leave_type": {
        "type": "string",
        "enum": ["annual", "sick", "emergency", "unpaid"]
      }
    },
    "required": ["employee_id", "start_date", "end_date", "leave_type"]
  }
}

Notice the description on the tool and on each field. These descriptions are not just documentation for humans; the AI reads them to decide if and how to use the tool. Bad descriptions mean the AI misuses or ignores your tool. Good descriptions mean the AI uses it exactly right. This is one of the most important things to get right when building MCP servers.

The execution flow:

• Discovery: Client calls tools/list → server returns all available tool definitions.
• AI receives those definitions in its context and understands what it can do.
• User sends a request.
• AI decides to use a tool → formats the call with proper arguments.
• Client calls tools/call with tool name and arguments.
• Server executes the actual function (calls HiBob API, writes to a database, etc.).
• Server returns the result.
• AI incorporates the result into its response.

2. Resources: Data the AI Can Read

Data the AI can read but cannot act on directly. Think of them as files or documents the AI can access. They are data sources that provide contextual information to AI applications. Examples: a company wiki page, a list of employees, a CSV file, API responses. Resources are read-only context. The AI does not call resources directly the way it calls tools; the app retrieves them and includes them in the conversation. Resources are passive; tools are active.

Direct Resources have fixed URIs:

calendar://events/june-2026
file:///company/handbook.pdf
employees://directory/engineering-team

Resource Templates are dynamic: URI patterns with parameters.

employees://{department}/{role}
→ employees://engineering/senior-engineer
→ employees://finance/analyst

3. Prompts: Pre-Built Templates

Pre-built prompt templates that the server exposes. They are reusable templates that help structure interactions with language models. Less commonly used but useful for standardizing how users interact with the server. For example, a "summarize this document" prompt template. They are for standardizing how people interact with complex workflows.

The practical use case: Imagine a company's HR team uses an AI tool daily. Instead of typing a different natural language request every time and getting inconsistent results, you create a prompt called employee_onboarding_review with defined fields: employee_name, start_date, department. The HR team fills in the fields and gets a consistent, well-structured interaction every time.

In Claude Code or Claude Desktop, prompts typically show up as slash commands: /plan_vacation, /onboard_employee, /generate_leave_report.

Where MCP Fits in Code You Actually Write

This is where it clicks for developers. There are two situations you will encounter.

Situation A: Using an Existing MCP Server Someone Else Built

There are already hundreds of pre-built MCP servers for popular platforms. Anthropic has shared pre-built MCP servers for popular enterprise systems like Google Drive, Slack, GitHub, Git, Postgres, and Puppeteer. Notion has one. GitHub has one. Many tools you already use have them.

In this situation, you do not write the server at all. You just configure your agent (or Claude Desktop/Code) to connect to it, and suddenly your agent can use those tools. This is where MCP saves the most time: you get a full Notion integration without writing a single line of Notion API code yourself.

Situation B: Building Your Own MCP Server

When a platform does not have an MCP server yet, or you need custom functionality, you build one. For example, building MCP servers for HiBob, Entra, internal platforms, etc., so that Claude can interact with those systems. A basic MCP server in Python looks conceptually like this (simplified):

from mcp.server import Server
from mcp.types import Tool
 
server = Server("my-hibob-server")
 
@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_employee",
            description="Get an employee's details from HiBob by their ID",
            inputSchema={
                "type": "object",
                "properties": {
                    "employee_id": {"type": "string"}
                }
            }
        )
    ]
 
@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_employee":
        # call HiBob API here
        return hibob_api.get_employee(arguments["employee_id"])

You define what tools exist, what they are called, what arguments they take, and what they do. Claude then discovers these tools automatically and can call them when relevant.

MCP in Claude Code Specifically

Claude Code is where MCP becomes incredibly powerful for a developer's day-to-day. You configure MCP servers in a config file, and then Claude Code gains access to all those tools natively: it can browse your GitHub issues, read your Notion docs, query your database, all from within your coding session.

For example, if you add a GitHub MCP server to Claude Code, you can say: "Look at the open issues tagged 'bug', find the three most critical ones, and write fixes for them." Claude Code can actually read the issues, understand them, write the code, and if you have a Git MCP server too, even commit.

The Two Layers of MCP

MCP consists of two layers:

• Transport layer: Defines the communication mechanisms and channels that enable data exchange between clients and servers, including transport-specific connection establishment, message framing, and authorization.
• Data layer: Defines the JSON-RPC based protocol for client-server communication, including lifecycle management, and core primitives, such as tools, resources, prompts and notifications.

Conceptually the data layer is the inner layer, while the transport layer is the outer layer.

Transport Layer: How MCP Communicates Under the Hood

Client and server communicate using the JSON-RPC 2.0 transport protocol. There are two transport methods:

• stdio (Standard Input/Output): For local servers running on the same machine. The client literally communicates with the server by passing messages through the terminal's stdin/stdout. This is what you use for local development and local tools (file system access, local database, etc.).
• HTTP with SSE (Server-Sent Events): For remote servers. This is what you use when the server is hosted somewhere else, like an MCP server you deploy to a cloud service so multiple people or agents can use it. MCP uses HTTP POST for client-to-server messages with optional Server-Sent Events for streaming capabilities. This transport enables remote server communication and supports standard HTTP authentication methods including bearer tokens, API keys, and custom headers. MCP recommends using OAuth to obtain authentication tokens.

The transport method (stdio vs HTTP) describes how your code communicates with the MCP server process, not how that server talks to the external API.

When you "use the GitHub MCP server," you typically download and run that server locally on your own machine. It becomes a process running on your computer. Your MCP client talks to it via stdio (local pipes). That server then internally makes its own regular HTTP calls out to GitHub's API. But that is invisible to MCP: from MCP's perspective, it is just a local process.

So the two transport modes are not about "local service vs cloud service." They are about where the MCP server process itself is running.

• stdio (Standard Input/Output)

  The MCP server runs on the same machine as your code. Your client communicates by literally writing to and reading from that process's stdin/stdout, like piping text between programs in a terminal. When you use it:

  • Running any of the pre-built MCP servers (GitHub, Notion, Google Drive, Postgres) locally on your dev machine
  • Building a server that reads local files or talks to local databases
  • Development and testing of any MCP server
  • Claude Code with locally configured MCP servers

• HTTP with SSE (Server-Sent Events)

  The MCP server is running somewhere else: deployed to the cloud, or on a different machine on the network. Your client connects over HTTP. When you use it:

  • An organization has deployed a shared MCP server that multiple engineers (or multiple Claude instances) all connect to
  • You build an MCP server and deploy it to Railway or Render so your whole team can use it
  • A company hosts a HiBob MCP server centrally that all their internal tools connect to
  • A product that exposes its capabilities as a remote MCP server (this is where the ecosystem is heading)

SSE specifically is how the server pushes updates to the client in real time (like notifications). HTTP POST handles client-to-server messages, and SSE handles server-to-client streaming. Together they give you full two-way communication over HTTP.

Data Layer

The data layer implements a JSON-RPC 2.0 based exchange protocol that defines the message structure and semantics. This layer includes:

• Lifecycle management: Handles connection initialization, capability negotiation, and connection termination between clients and servers.
• Server features: Enables servers to provide core functionality including tools for AI actions, resources for context data, and prompts for interaction templates from and to the client.
• Client features: Enables servers to ask the client to sample from the host LLM, elicit input from the user, and log messages to the client.
• Utility features: Supports additional capabilities like notifications for real-time updates and progress tracking for long-running operations.

Data Layer Protocol

A core part of MCP is defining the schema and semantics between MCP clients and MCP servers. Developers will likely find the data layer, in particular the set of primitives, to be the most interesting part of MCP. It is the part of MCP that defines the ways developers can share context from MCP servers to MCP clients.

MCP uses JSON-RPC 2.0 as its underlying RPC protocol. Client and servers send requests to each other and respond accordingly. Notifications can be used when no response is required.

JSON-RPC 2.0, Demystified

• JSON is just a data format. A way of writing structured information that both humans and computers can read. Like: {"name": "Jonathan", "role": "engineer"}.
• RPC stands for Remote Procedure Call. "Procedure" is just an old word for function. So RPC means: calling a function that lives in a different process or machine, not in your own code. Think about it: when your LangGraph agent calls a tool, it is essentially saying "run this function for me." RPC is the general concept of doing that across process boundaries.
• 2.0 is just the version number.

So JSON-RPC 2.0 is a standard that says: here is exactly how you should format a message when you want to call a function on another process, using JSON. That is it.

What the Messages Look Like

There are three types of messages in JSON-RPC 2.0:

A Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_employee",
    "arguments": { "employee_id": "EMP001" }
  }
}

• jsonrpc: Always "2.0". Just identifies the protocol version.
• id: A unique number you assign so you can match the response to this specific request. If you send 10 requests, each gets a different id so you know which response belongs to which request.
• method: The function you want to call. In MCP, these follow a pattern like tools/list, tools/call, resources/read.
• params: The arguments you are passing to that function.

A Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "Employee: Jonathan Mukhobe" }]
  }
}

• Same id as the request: this is how you know "this response answers request #3."
• result: The returned data.

A Notification

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

Notice that there is no id here. That is the key difference. No id means no response is expected. The sender is just saying "FYI, something changed" and moving on.

That is genuinely all JSON-RPC 2.0 is. MCP uses it as its language: every single message between an MCP client and server is one of these three formats.

Lifecycle Management: The Handshake

The purpose of lifecycle management is to negotiate the capabilities that both client and server support. This section provides a step-by-step walkthrough of an MCP client-server interaction, focusing on the data layer protocol.

Every time your MCP client connects to a server, they go through a handshake before they do anything useful. This is lifecycle management. Think of it like two people meeting for the first time and establishing ground rules before working together. There are three phases:

Phase 1: Initialize Request (Client → Server)

The client sends an initialize request to establish the connection and negotiate supported features. The client says: "Hello, I'm connecting. Here's what version of MCP I speak, and here's what features I support."

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "clientInfo": { "name": "my-agent", "version": "1.0" },
    "capabilities": {
      "elicitation": {}
    }
  }
}

The client is declaring: "I support the elicitation feature", meaning if the server needs to ask the user for input, the client can handle that.

Phase 2: Initialize Response (Server → Client)

The server responds: "Understood. Here's what version I speak, and here's what I offer."

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "serverInfo": { "name": "hibob-server", "version": "1.0" },
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": {}
    }
  }
}

The server is declaring: "I have tools and resources. And I can send you notifications when my tool list changes (listChanged: true)."

Phase 3: Initialized Notification (Client → Server)

After successful initialization, the client sends a notification to indicate it is ready. This is a notification (no id, no response expected):

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Understanding the Initialization Exchange

The initialization process is a key part of MCP's lifecycle management and serves several critical purposes:

• Protocol Version Negotiation: The protocolVersion field (e.g. "2025-11-25") ensures both client and server are using compatible protocol versions. This prevents communication errors that could occur when different versions attempt to interact. If a mutually compatible version is not negotiated, the connection should be terminated.
• Capability Discovery: The capabilities object allows each party to declare what features they support, including which primitives they can handle (tools, resources, prompts) and whether they support features like notifications. This enables efficient communication by avoiding unsupported operations.
• Identity Exchange: The clientInfo and serverInfo objects provide identification and versioning information for debugging and compatibility purposes.

In this example, the capability negotiation demonstrates how MCP primitives are declared:

Client Capabilities:

• "elicitation": {}: The client is declaring "I support the elicitation feature", meaning if the server needs to ask the user for input, the client can handle that.

Server Capabilities:

• "tools": {"listChanged": true}: The server supports the tools primitive AND can send tools/list_changed notifications when its tool list changes.
• "resources": {}: The server also supports the resources primitive (can handle resources/list and resources/read methods).

How This Works in AI Applications

During initialization, the AI application's MCP client manager establishes connections to configured servers and stores their capabilities for later use. The application uses this information to determine which servers can provide specific types of functionality (tools, resources, prompts) and whether they support real-time updates.

async with stdio_client(server_config) as (read, write):
    async with ClientSession(read, write) as session:
        init_response = await session.initialize()
        if init_response.capabilities.tools:
            app.register_mcp_server(session, supports_tools=True)
        app.set_server_ready(session)

Next Step 1: Tool Discovery (Primitives)

Now that the connection is established, the client can discover available tools by sending a tools/list request. This request is fundamental to MCP's tool discovery mechanism: it allows clients to understand what tools are available on the server before attempting to use them.

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

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "calculator_arithmetic",
        "title": "Calculator",
        "description": "Perform mathematical calculations including basic arithmetic, trigonometric functions, and algebraic operations",
        "inputSchema": {
          "type": "object",
          "properties": {
            "expression": {
              "type": "string",
              "description": "Mathematical expression to evaluate (e.g., '2 + 3 * 4', 'sin(30)', 'sqrt(16)')"
            }
          },
          "required": ["expression"]
        }
      },
      {
        "name": "weather_current",
        "title": "Weather Information",
        "description": "Get current weather information for any location worldwide",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name, address, or coordinates (latitude,longitude)"
            },
            "units": {
              "type": "string",
              "enum": ["metric", "imperial", "kelvin"],
              "description": "Temperature units to use in response",
              "default": "metric"
            }
          },
          "required": ["location"]
        }
      }
    ]
  }
}

Understanding the Tool Discovery Exchange

The tools/list request is simple, containing no parameters. The response contains a tools array that provides comprehensive metadata about each available tool. This array-based structure allows servers to expose multiple tools simultaneously while maintaining clear boundaries between different functionalities. Each tool object in the response includes several key fields:

• name: A unique identifier for the tool within the server's namespace. This serves as the primary key for tool execution and should follow a clear naming pattern (e.g. calculator_arithmetic rather than just calculate).
• title: A human-readable display name for the tool that clients can show to users.
• description: Detailed explanation of what the tool does and when to use it.
• inputSchema: A JSON Schema that defines the expected input parameters, enabling type validation and providing clear documentation about required and optional parameters.

How This Works in AI Applications

The AI application fetches available tools from all connected MCP servers and combines them into a unified tool registry that the language model can access. This allows the LLM to understand what actions it can perform and automatically generates the appropriate tool calls during conversations.

available_tools = []
for session in app.mcp_server_sessions():
    tools_response = await session.list_tools()
    available_tools.extend(tools_response.tools)
conversation.register_available_tools(available_tools)

Next Step 2: Tool Execution (Primitives)

The client can now execute a tool using the tools/call method. This demonstrates how MCP primitives are used in practice: after discovering available tools, the client can invoke them with appropriate arguments.

The tools/call request follows a structured format that ensures type safety and clear communication between client and server. Note that we are using the proper tool name from the discovery response (weather_current) rather than a simplified name:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "weather_current",
    "arguments": {
      "location": "San Francisco",
      "units": "imperial"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in San Francisco: 68°F, partly cloudy with light winds from the west at 8 mph. Humidity: 65%"
      }
    ]
  }
}

Key Elements of Tool Execution

The request structure includes several important components:

• name: Must match exactly the tool name from the discovery response (weather_current). This ensures the server can correctly identify which tool to execute.
• arguments: Contains the input parameters as defined by the tool's inputSchema. In this example: location is "San Francisco" (required parameter) and units is "imperial" (optional parameter, defaults to "metric" if not specified).
• JSON-RPC Structure: Uses standard JSON-RPC 2.0 format with unique id for request-response correlation.

Understanding the Tool Execution Response

The response demonstrates MCP's flexible content system:

• content Array: Tool responses return an array of content objects, allowing for rich, multi-format responses (text, images, resources, etc.).
• Content Types: Each content object has a type field. In this example, "type": "text" indicates plain text content, but MCP supports various content types for different use cases.
• Structured Output: The response provides actionable information that the AI application can use as context for language model interactions.

This execution pattern allows AI applications to dynamically invoke server functionality and receive structured responses that can be integrated into conversations with language models.

How This Works in AI Applications

When the language model decides to use a tool during a conversation, the AI application intercepts the tool call, routes it to the appropriate MCP server, executes it, and returns the results back to the LLM as part of the conversation flow. This enables the LLM to access real-time data and perform actions in the external world.

async def handle_tool_call(conversation, tool_name, arguments):
    session = app.find_mcp_session_for_tool(tool_name)
    result = await session.call_tool(tool_name, arguments)
    conversation.add_tool_result(result.content)

Next Step 3: Real-Time Updates (Notifications)

MCP supports real-time notifications that enable servers to inform clients about changes without being explicitly requested. This demonstrates the notification system, a key feature that keeps MCP connections synchronized and responsive.

When the server's available tools change, such as when new functionality becomes available, existing tools are modified, or tools become temporarily unavailable, the server can proactively notify connected clients:

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

Key Features of MCP Notifications

• No Response Required: Notice there is no id field in the notification. This follows JSON-RPC 2.0 notification semantics where no response is expected or sent.
• Capability-Based: This notification is only sent by servers that declared "listChanged": true in their tools capability during initialization.
• Event-Driven: The server decides when to send notifications based on internal state changes, making MCP connections dynamic and responsive.

Client Response to Notifications

Upon receiving this notification, the client typically reacts by requesting the updated tool list. This creates a refresh cycle that keeps the client's understanding of available tools current:

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

Why Notifications Matter

This notification system is crucial for several reasons:

• Dynamic Environments: Tools may come and go based on server state, external dependencies, or user permissions.
• Efficiency: Clients do not need to poll for changes; they are notified when updates occur.
• Consistency: Ensures clients always have accurate information about available server capabilities.
• Real-time Collaboration: Enables responsive AI applications that can adapt to changing contexts.

This notification pattern extends beyond tools to other MCP primitives, enabling comprehensive real-time synchronization between clients and servers.

How This Works in AI Applications

When the AI application receives a notification about changed tools, it immediately refreshes its tool registry and updates the LLM's available capabilities. This ensures that ongoing conversations always have access to the most current set of tools, and the LLM can dynamically adapt to new functionality as it becomes available.

async def handle_tools_changed_notification(session):
    tools_response = await session.list_tools()
    app.update_available_tools(session, tools_response.tools)
    if app.conversation.is_active():
        app.conversation.notify_llm_of_new_capabilities()

Client Features: What the Client Offers the Server

This is the part most people miss. MCP is two-way. Servers expose tools and resources to clients, but clients also expose features to servers. The server can use these features to build richer, more powerful interactions.

Elicitation: The Server Asks the User a Question

Normally: User → Client → AI → Server (the server just receives and acts). With elicitation, the server can pause its work and say to the client: "I need more information from the user before I can continue."

A concrete example: Your agent is in the middle of booking a flight. The MCP server handling the booking has found options and is ready to confirm. But before finalizing, it needs the user's passport number and seat preference. The server can use elicitation to pause and ask:

{
  "method": "elicitation/create",
  "params": {
    "message": "Before I confirm your booking, I need a few details:",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "passport_number": { "type": "string" },
        "seat_preference": {
          "type": "string",
          "enum": ["window", "aisle", "middle"]
        },
        "confirm_booking": { "type": "boolean" }
      },
      "required": ["passport_number", "confirm_booking"]
    }
  }
}

The client shows this as a UI form to the user, collects the structured response, and sends it back to the server. The server then continues with that information.

Roots: Filesystem Scope Boundaries

Roots are how the client tells the server which directories it is allowed to operate in. If you connect a filesystem MCP server to help with a project, you do not want it looking through your entire machine; you point it at specific folders.

{
  "roots": [
    { "uri": "file:///home/jonathan/projects/projects", "name": "Projects" },
    { "uri": "file:///home/jonathan/docs/research", "name": "Research" }
  ]
}

Important caveat from the docs: Roots are a convention, not a hard security boundary. A well-behaved server respects them. But they do not enforce access at the OS level. Think of them as telling a trusted contractor "please only work in these rooms"; they should follow that, but it is not a locked door. Real security enforcement happens through OS-level file permissions, not MCP roots.

Claude Code uses roots automatically when you open a folder: it tells any connected MCP servers "this is the project scope."

Sampling: The Server Asks the AI to Think

This is the most advanced and counterintuitive client feature. Sampling allows the server to make a request back to the AI (through the client) during its own operation.

Why would a server need to ask the AI? Sometimes a tool needs intelligence to decide what to do. Example: your MCP server retrieves 47 flight options. It could return all 47 to the AI in the main conversation, but that would flood the context window. Instead, the server can use sampling: "Hey client, can you ask the AI to look at these 47 flights and tell me the top 3 for this user's preferences?" The AI analyzes them in a separate call, returns a structured answer, and the server uses that to give a clean response.

Why this keeps the client in control: The sampling request goes through the client, and the client can show it to the user for approval before forwarding it to the AI. The server cannot make secret AI calls on the user's behalf. The client is the gatekeeper.

For your projects: Sampling is advanced and you likely will not need it in your first MCP builds. But knowing it exists helps you understand why MCP is powerful: you can build server-side logic that uses AI reasoning without the server needing its own LLM integration.

Notifications: One-Way Messages

You have seen these throughout. The pattern is simple: a notification is a JSON-RPC message with no id field. This means no response is expected. It is a signal, not a request. The most important notifications in practice:

• notifications/tools/list_changed: Server tells the client its tool list has changed. The client should call tools/list again to get the updated list. This matters when servers dynamically add or remove tools based on user permissions or system state.
• notifications/initialized: Client tells the server it is ready to work (sent after the initialize handshake).
• notifications/progress: For long-running operations. The server sends progress updates: "Step 1 of 5 complete... Step 2 of 5..."

Tasks (Experimental): Long-Running Operations

This is a newer, still-experimental feature. Normal tool calls are synchronous: you call a tool, you wait, you get the result. But some operations take minutes or hours, like "run a batch report on all 7 million customers" or "process this large dataset." Tasks are durable execution wrappers that let you fire off a long operation and check on it later:

• Call a tool that starts a task → get back a task_id immediately
• Do other things
• Later, check task_id for status: "running" / "complete" / "failed"
• When complete, retrieve the result

This is analogous to Celery in Django: you enqueue a job, it runs in the background, you check on it. Same concept, just standardized in MCP. For large company automations that touch large data sets or multi-step workflows, this is the mechanism that would make those agents non-blocking and production-grade.

Versioning: How MCP Manages Change

The Date-Based Version Format (YYYY-MM-DD)

MCP uses dates as version numbers, not v1.0 or v2.0. The current version as of this article is 2025-11-25. The date represents the last time a breaking (backwards-incompatible) change was made.

The key rule: If Anthropic adds a new feature to MCP but does not break anything that already works, the version date stays the same. They only bump the date when they make a change that would break existing implementations. This is a deliberately conservative approach: the protocol can keep improving without forcing everyone to upgrade constantly.

Individual Feature States

Beyond whole-version states, individual features within a version can have their own lifecycle:

• Deprecated: The feature still works but is being phased out. They give at least 12 months warning (90 days minimum in exceptional cases) before removing it. Use this time to migrate away.
• Removed: Gone in a new version. You will see it in older specs but it will not work in current servers.

Version Negotiation During Initialization

This is the practical part. During the initialization handshake (Phase 1 above), the client says "I speak version 2025-11-25." The server responds with what version it uses. If they are on different versions:

• If backwards compatible → they can still work together
• If incompatible → the connection terminates gracefully with an error, rather than silently failing or producing weird behavior

I rebuilt my own WhatsApp agent on this protocol, and the Kylie MCP case study shows what each of these pieces looks like in a real repository.

What You Actually Write, In Summary

• When You Build an MCP Server

  You write tool definitions (name, description, inputSchema), tool handlers (the actual function that runs), resource endpoints (if exposing data), and optionally notification senders (if your tool list changes dynamically).

• When You Build an MCP Client (Your Agent)

  You write the initialization handshake, the tools/list call on startup, tool call routing when the AI decides to use a tool, notification listeners to keep your tool registry fresh, and optionally elicitation UI if you want users to answer mid-task questions.

• When You Deploy to Production

  You move from stdio (local) to HTTP+SSE (remote), add proper authentication (OAuth or API keys in the HTTP headers), add observability (logging on each tool call, the same discipline as an Opik-style tracing setup), and version pin to the Current spec.

You are now ready to go build. The jump from understanding to hands-on will make everything click, especially the initialization sequence, which looks abstract until you see it happen in logs for the first time.

Think of MCP like a USB-C port for AI applications: one standard connector between any AI application and any external system, so nobody has to keep soldering custom wires.

RAG is a technique that exerts influence on a model's response through the integration of our own data. Rather than baking knowledge directly into model weights, it retrieves the most relevant information at query time and injects it into the prompt, giving the model an accurate, up-to-date context without ever retraining.

Why Fine-Tuning Is Often the Wrong Answer

One possible way to influence a model with your own data is through fine-tuning and incorporating it into the training process. This approach enables the model to construct responses taking into account the provided data. However, often this may not be the optimal solution for various reasons:

• Cost and effort involved in fine-tuning a model, including computer resources and GPU access.
• Information is not valid forever. It might need to be changed, which calls for fine-tuning every time the information is modified.
• There is no mechanism to make the model forget what it has learned.
• In a scenario where information increases periodically, fine-tuning is not the best approach.
• A model can receive data in two ways: through fine-tuning and through the system prompt. But the information we can give to the prompt is limited.

Steps Followed by a RAG System

Knowledge Storage

The first step is to store the information the model can draw upon. This knowledge base can include structured data (like databases), unstructured data (like text documents), or even code. We use a vector database to store this information.

Question Reception

The RAG system receives the user's question or request. This could be in natural language, just like a question you would ask a person.

Information Retrieval

This is where the "Retrieval" in RAG comes into play. The system selects relevant information to the user's question from the stored data. In a vector database, this involves vector comparison to retrieve related information.

Vector Comparison is how the system figures out which stored information is most similar to your question, using math behind the scenes to compare meaning. It matches the meanings of your question to the most relevant stored documents, not by keywords, but by how close their meanings are in a mathematical space.

Prompt Construction

A prompt is constructed using the relevant information and the user's question. This prompt is designed to effectively communicate the context of the user's query to the language model. In this way, not only is the model provided with information to construct its response, but hallucinations are also reduced since the model does not have to invent information it does not know.

Calling the Model

The prompt is passed to the language model. The model uses the context provided in the prompt to generate a response.

Response from the Model

The model's response is presented to the user. If the RAG system has been constructed correctly, this response should be relevant and grounded in the retrieved information from the knowledge base.

How Vector Databases Work

Of all the steps mentioned, one is particularly important and sensitive: searching for relevant information to answer the user's question. This is where vector databases come into play, assisting in selecting which information from the database is relevant to what the user asks.

Vector databases store information as numerical representations called vectors. So it is necessary to transform text into vectors before storing it.

Tokenization

The first step is to tokenize the text. Tokens are the smallest units of text that are meaningful to the model. There are various types of tokens, including words, subwords, characters, and byte-pair encodings. The choice of token type depends on the specific use case and the language being modeled.

Vectorization

Tokens are converted into vectors, which are numerical representations of objects in a continuous vector space. They capture the semantic meaning or properties of those objects in a way that can be efficiently searched. A vector represents a point in a multidimensional space, anywhere from roughly 100 to 4,000 dimensions in practice.

Embeddings and Semantic Proximity

The vector, also known as an embedding, captures the semantic meaning of the stored text. The magic lies in how these embeddings are generated: words with similar meanings have vectors that are closer together in this multidimensional space than words with different meanings.

For example, "cat" and "kitty" have very similar meanings, even though the words themselves are quite different letter by letter. Their embeddings will be numerically close because the model has learned they appear in similar contexts.

Distance Calculation and Search

Once text is converted, it is possible to calculate the difference between one vector and another, or search for vectors that are closer to a specific one. That is how it is possible to find similar texts to a reference one. Mathematically, there is not much difference between calculating the distance between two points whether they are in two, three, or any number of dimensions.

Where Do Embedding Numbers Come From?

The numbers in vector embeddings do not just appear by chance. They come from machine learning models that have been trained on huge amounts of text (or other types of data like images, audio, etc.).

Behind the Scenes: Neural Networks

These embeddings are created by models like:

• Word2Vec
• GloVe
• BERT
• OpenAI's models, etc.

These models use neural networks to analyze text contextually and assign each word (or sentence) a place in a high-dimensional space. So instead of saying "cat and dog are related because they appear together," they say "let me place cat and dog in a vector space so they end up close together because the model has seen them used in similar ways."

When you hear about embedding models or vectorization tools like OpenAI Embeddings API, Hugging Face Transformers, SentenceTransformers, or spaCy, these are tools that generate those vectors from text, making it ready to store and search in a vector database.

Summary: End-to-End RAG Flow

In summary, this is how Retrieval Augmented Generation works:

• The text to store is tokenized and converted into embeddings, which are then stored in the vector database.
• The user's question is also tokenized and converted into an embedding.
• The vector database is queried to find the embeddings that are closest to the user's question embedding.
• These embeddings are converted back into text and returned as context for the model.

Here is a brief summary of the process text undergoes before reaching a language model. First it is tokenized, meaning it is divided into small parts. Then it is converted into vectors, which in the world of large language models are known as embeddings. This vector, containing numbers, is passed to the model, and it generates another vector as output. The output vector undergoes the reverse process and is converted into text, which is what we see as a response.

The key is to utilize selected text related to the question and build a powered prompt with the information and the user request. In this way, the model has the necessary information to build a proper response. To select the text to use to enrich the prompt, a vectorized database is employed, enabling a search based on vector similarity. This ensures that the model has information relevant to what it needs to respond.

The important thing is to understand that embeddings are numerical representations capable of capturing the meaning of sentences, and that they allow you to perform simple vector operations such as calculating the distance between them.

At its core, load balancing is the practice of distributing incoming network traffic across multiple servers so that no single server becomes overwhelmed. Think of it like a supermarket with multiple checkout lanes: instead of everyone queuing at one cashier, a manager directs customers to whichever lane is shortest. The customers get served faster, and no cashier burns out.

For example, when a user hits a React app and then a Django API, something has to decide which server instance handles that request. That "something" is a load balancer.

Why it matters: A single server has a ceiling, in terms of CPU, RAM, and network bandwidth. Load balancers let you scale horizontally (add more servers) rather than just vertically (buy a bigger server). They also give you redundancy: if one server crashes, traffic is automatically rerouted to the healthy ones.

Types of Load Balancers

There are three broad categories, each with different trade-offs in cost, control, and capability.

• Hardware Load Balancers

  Physical appliances from vendors like F5 or Citrix. They are extremely fast (purpose-built silicon), handle millions of connections, and are found in large banks and telecoms. The downside: they are expensive (tens of thousands of dollars), inflexible, and hard to scale. As a developer building web apps, you will almost certainly never touch one of these.

• Software Load Balancers

  Programs running on commodity hardware or VMs. NGINX, HAProxy, and Envoy are the big names. You get full control, they are cheap, and they are extraordinarily configurable. The trade-off is that you are responsible for running and scaling the software itself.

• Cloud-Based Load Balancers

  Managed services like AWS ALB, Cloudflare Load Balancing, and GCP Cloud Load Balancing. You configure them via a dashboard or API and the provider handles everything else. This is the most relevant category for a modern web developer stack.

Load Balancer Classification by OSI Layer

Load balancers do not all operate at the same level of the network stack, and the layer they operate at determines what information they can use to make routing decisions.

Layer 4 (Transport)

The load balancer sees the IP address, port, and whether it is a TCP or UDP connection, but it never opens the packet and reads what is inside. Think of it like a postal sorting facility that routes parcels by zip code, without opening them. It is extremely fast because the inspection is minimal.

Good for: raw TCP traffic, non-HTTP protocols (like databases, game servers, MQTT), and situations where you need maximum throughput.

Layer 7 (Application)

The load balancer actually reads the HTTP request: the URL, headers, cookies, even the body. Now it can make smart decisions. Route /api/* requests to your Django servers, / to your React build, and /uploads/* to object storage. Route requests with a specific session cookie to the same server that created that session. This is what Cloudflare, Vercel, and most modern cloud load balancers do.

Global Server Load Balancing (GSLB)

This operates above both L4 and L7. Instead of routing requests between servers in one location, a GSLB routes users to the right data center (or region) before any L4/L7 load balancing even begins. Two mechanisms power this:

• DNS-based routing: When a user queries a domain, the DNS server returns a different IP based on where the user is. A user in Kampala gets the IP of the closest data center; a user in Berlin gets a different one. Cloudflare's Load Balancing product does exactly this.
• Anycast networking: Multiple servers worldwide advertise the same IP address. Internet routing protocols (BGP) automatically direct each user's traffic to the topologically nearest server. Cloudflare's entire network runs on Anycast, which is why Cloudflare is so fast globally.

Load Balancing Algorithms

Once traffic arrives at a load balancer, it needs to decide which server gets each request. Here are the main algorithms:

Round Robin

Here, servers get requests in a sequential order i.e the first request goes to server 1, then the next request to server 2, and the third to server 3, then the next request back to server 1, so requests go to servers in a fixed cycle: 1, 2, 3, 1, 2, 3. It works when all your servers are identical(have the same capabilities) and requests take similar time. Simple and predictable.

Sticky Round Robin (Sessions)

Same as round robin, but once a client is assigned a server, all their requests go to that same server via a cookie or IP. Great for stateful apps that store sessions in memory. If your Django app stores session data in memory (not Redis), a user who gets routed to Server 2 for login must keep going to Server 2, or their session disappears. Sticky sessions handle this, though the better long-term solution is externalizing sessions to Redis.

IP/URL Hash (Deterministic)

A hash of the client's IP (or the URL) determines the server. This algorithm determines which server gets a request based on the hash of the client's IP address, for example, if client 1 makes a request to the load balancer, the load balancer uses the client's IP address, hashes it and sends the request to an appropriate server, and all future requests made by that client are redirected to tha same server by the load balancer using the IP hashing algorithm. This is useful when you want the client to consistently connect to the same server.The same input always maps to the same server. Good for caching (cache locality stays on one server), but problematic if one IP generates massive traffic (such as a mobile carrier NAT-ing thousands of users behind one IP).

Least Connections (Dynamic)

Each new request goes to whichever server currently has the fewest active connections. Like joining the shortest queue at a theme park ride. Excellent for requests with variable processing time. If some requests take 5ms and others take 5 seconds, you do not want servers getting buried while others sit idle. This algorithm prevents that.

Least Response Time (Most Responsive)

This algorithm is more focused on responsiveness. The load balancer chooses the server with the lowest response time, and fewest active connections. So, it routes to the server with the lowest combination of active connections and fastest average response time. So, first it'll try sending as many requests as possible to the most responsive server, but it also takes into account the number of active connections. If Server 3 has slightly more connections but responds in 8ms versus Server 1's 45ms, Server 3 still wins. This is effective when the goal is to provide the fastest response time to requests, and you have different servers with different capabilities.The most intelligent option, used by NGINX Plus and Cloudflare.

Weighted Algorithm

These are variants of any of the algorithms; round robin, least connections, least response time, IP hash, that can also be weighted for example weighted round robin, weighted least connections. In this case, servers are assigned weights based on their capacity and performance metrics. The load balancer takes that into account when redirecting traffic. First, it'll try sending as many requests to the server with the highest weight and then followed by the other servers if the one with the highest weight gets overwhelmed. A server with weight 3 gets 3 times more requests than one with weight 1. Like assigning more tables in a restaurant to experienced waiters. Use this when your servers have unequal specs. If you have a 4-core server and an 8-core server, give the 8-core double the weight.

Load balancing decides where a request goes; rate limiting decides whether it should be served at all, and production systems need both.

Monitoring Metrics

A load balancer is also a great observation point for your system's health, since all traffic flows through it.

• Traffic Metrics

  Tell you about volume: how much is hitting your system. RPS (requests per second) is the primary heartbeat. A sudden spike could mean a viral moment or a DDoS attack.

• Performance Metrics

  The most actionable for user experience. Average response time is misleading on its own. P95 and P99 tell you what the slowest 5% and 1% of users experience. If your average is 50ms but P99 is 5 seconds, something is deeply wrong for a non-trivial slice of users.

• Health Metrics

  The load balancer's own view of your servers. Load balancers send periodic health check requests (e.g. GET /health) and mark servers as unhealthy if they fail. Once unhealthy, traffic is stopped to that server automatically.

• Error Metrics

  The distinction between 4xx and 5xx is critical. 4xx (client errors) are usually application-level issues. 5xx (server errors) are infrastructure problems. A rising 5xx rate is a red alert.

Load balancers let you scale horizontally and give you redundancy. If one server crashes, traffic is automatically rerouted to the healthy ones. That is the foundation of any production system at scale.

An unprotected API endpoint is an open invitation to abuse, from scrapers and bots to cascading backend overload. Understanding how rate limiting and throttling work is non-negotiable for any backend engineer shipping production systems.

Rate Limiting vs Throttling

Think of an API as a highway. Rate limiting is a hard barrier, a toll gate that only lets through a fixed number of cars per hour, then turns the rest away entirely. Throttling is a speed bump: it does not block anyone, it just slows the convoy down to a manageable pace.

Both protect your system, but they are different philosophies. Rate limiting enforces a quota; throttling manages flow.

• Rate Limiting

  Setting a cap on the number of requests a client or user can make within a specific time window (e.g. 1,000 requests per minute per user). If a client tries to exceed this limit, they get blocked or receive an error response, typically a 429 Too Many Requests status code with a Retry-After header. This ensures no single source overwhelms the system. You can apply limits at different scopes:

  • Per-user: each user gets 1,000 requests per minute, preventing one bad actor from ruining others.
  • Per-application: the entire service handles 50,000 requests per minute, protecting the whole system.
  • Per-endpoint: stricter limits on expensive endpoints (e.g. /generate-report gets 10/min, /health gets unlimited).
  • Per-tier: free users get 100/hour, paid users get 10,000/hour. This is the classic SaaS model. Rate limiting is ideal when you want to enforce strict usage policies. It is straightforward: you hit the cap, you get denied.

• Throttling

  Throttling is about slowing down the rate of requests rather than outright rejecting them. It is useful when you want to maintain service availability but need to manage load more gracefully. If an API is handling more requests than usual, you can queue requests and process them at a steady rate instead of rejecting them. The user might see increased latency, but they are not blocked outright. Throttling does not say "you cannot," it says "wait your turn." Your client experiences latency but eventually gets a response.

  • Dynamic throttling: adjusts levels based on real-time metrics like CPU load, memory usage, or queue depth. When your server is at 90% CPU, you slow the drain on the queue. When it drops to 40%, you speed back up.
  • Adaptive throttling: takes this further by using heuristics or ML to predict spikes before they hit. If every Monday at 9am traffic triples, an adaptive system starts throttling at 8:55am, before the wave arrives.

Often systems implement both: first try throttling, then move on to rate limiting if capacity is threatened.

The Two Core Algorithms

Token Bucket (Rate Limiting)

This is the most widely used algorithm for rate limiting. Imagine a bucket that holds tokens, where each token represents permission to make one request. Tokens are added to the bucket at a fixed rate, and if the bucket is full, extra tokens are discarded. When a request comes in, the program checks the bucket: if a token is available, the request is allowed and a token is removed. If the bucket is empty, the request is denied.

The token bucket is great for rate limiting because it naturally handles bursty traffic. A user who makes no requests for 30 seconds builds up a reserve of tokens. When they need to fire a batch of requests, they can. This is more fair and realistic than a rigid counter.

In practice (e.g. in Redis), you store two values per user: tokens_remaining and last_refill_timestamp. On each request, you calculate how many tokens to add since the last refill, clamp to max capacity, then check if there is a token to consume.

Leaky Bucket (Throttling)

The leaky bucket solves a different problem: smoothing out a burst rather than capping it. Imagine a bucket that leaks water at a constant rate. When a request comes in, it is treated like adding water to the bucket. If the bucket is not full, the request is allowed and a bit of water is added. If the bucket is full, the request is delayed or rejected. The bucket ensures that requests are processed at a smooth constant pace, even if lots arrive at once.

The leaky bucket is ideal when you are calling a downstream service that can only handle a steady rate: a payment processor, a third-party API with strict SLAs, or a legacy backend. You absorb the burst, then deliver requests calmly. Your client waits a bit, but the downstream service stays healthy.

The Full Implementation Picture

Systems often layer both approaches: throttle first to queue the burst, then rate limit to reject genuinely excessive clients. Here is what that looks like end-to-end:

Cloudflare (Domain Layer)

This is the first and cheapest line of defense. You can block entire IP ranges before the request even touches your servers. Configure rate limiting rules under Security in the Cloudflare dashboard: for example, "block IPs that make more than 500 requests per minute to /api/*." This costs nothing in compute and handles volumetric attacks and bot traffic before they reach your backend. Enabling Bot Fight Mode handles a huge class of abusive traffic automatically.

Vercel (Frontend/Edge Layer)

Vercel's Edge Middleware runs before your React app and is a great place to rate limit session-based requests or SSR routes. You can write middleware that checks a counter in an edge KV store. For most React apps, you will rely on the backend for heavy rate limiting.

FastAPI (Main Enforcement Layer)

Use slowapi, the FastAPI equivalent of Express Rate Limit. You can apply per-IP limits globally or set stricter per-endpoint limits for expensive operations like report generation. For user-based limits (not just IP), swap the key function to extract the user ID from your JWT.

Django REST Framework

DRF has built-in throttling via AnonRateThrottle and UserRateThrottle. You configure default rates in settings.py or create per-view throttle classes for endpoint-specific limits. DRF uses a leaky bucket-style algorithm internally, which is great for throttling.

Redis (Shared State Across Instances)

The moment you scale to more than one instance, in-memory rate limiting breaks: each instance has its own counter and they do not talk to each other. Redis solves this. Add a Redis instance and point both slowapi and DRF at it. Both libraries support Redis backends directly, keeping your counters consistent across every running instance.

Rate limiting sits alongside load balancing: one caps what a client may ask for, the other spreads what gets through.

Monitor and Tune

Set up alerts on your 429 rate. If it spikes, you might be too aggressive (blocking legitimate users) or too loose (absorbing abuse). Track these metrics:

• 4xx error rate, filtered to 429s.
• P95/P99 latency (throttling shows up here before errors do).
• Queue depth if you are using any async processing.
• Per-user request rates to spot abusers.

For metrics, Railway's built-in observability dashboard is a start, but for production you will want to push to Datadog or use a lightweight option like Prometheus and Grafana.

Quick Decision Guide

The general rule: Cloudflare handles the perimeter, FastAPI or Django handles business logic limits, and Redis keeps state consistent when you scale.