Model Context Protocol: A Developer's Guide

The Model Context Protocol (MCP) represents a significant advancement in the way Large Language Models (LLMs) interact with external applications and data sources. It offers a standardized framework designed to enhance the contextual understanding of LLMs, leading to more relevant and accurate responses. By establishing a universal and open protocol, MCP addresses the complexities associated with integrating LLMs with diverse systems, moving away from bespoke, one-off solutions towards a more sustainable and interoperable ecosystem. This initiative, spearheaded by Anthropic and made available to the wider developer community, aims to foster innovation and collaboration in the field of AI-powered applications.

For developers looking to leverage the power of LLMs, understanding MCP is becoming increasingly crucial. The protocol's core concepts, including Sampling, Transport, Tools, Prompts, Resources, and Architecture, provide a structured approach to managing the context provided to these models. This standardization simplifies the development process, optimizes context management for better model interactions, offers a flexible architecture that can be extended, and provides intuitive APIs that are easy to use. The benefits extend to standardized AI integration, allowing for greater flexibility in choosing AI models and vendors, while also enhancing security by enabling data to remain within the developer's infrastructure during AI interactions. Ultimately, MCP empowers developers to build robust servers that can securely expose data and functionality to LLM applications, functioning as specialized APIs tailored for AI interactions. This capability to establish secure, two-way connections between data sources and AI-powered tools is a cornerstone of MCP's value proposition. The breakdown of MCP into specific, well-defined areas such as Sampling, Transport, and Tools indicates a deliberate and organized design, suggesting a comprehensive approach to managing the complexities of LLM interactions. The fact that these concepts are further categorized, with "Roots" being listed under client features, highlights a nuanced understanding of the different responsibilities on the client and server sides of the communication.

The architecture of the Model Context Protocol follows a client-host-server model. In this model, the Host acts as a central hub responsible for managing and coordinating multiple Client instances. The host's duties include creating and overseeing the lifecycle of clients, controlling their connection permissions, enforcing security policies and consent requirements, managing user authorization, coordinating AI/LLM integration and sampling processes, and aggregating context from various clients. Each Client, in turn, establishes a dedicated and isolated connection with a specific Server. A client maintains a single stateful session with each server, handling protocol negotiation, exchanging capabilities, routing protocol messages bidirectionally, managing subscriptions and notifications, and ensuring security boundaries between different servers. This establishes a one-to-one relationship between a client and a particular server. Servers are the entities that provide specialized context and capabilities to the clients. They expose resources, tools, and prompts through the primitives defined by MCP, operate independently with focused responsibilities, request sampling through client interfaces, must adhere to security constraints, and can be implemented as either local processes or remote services 9. The introduction of the "Host" component signifies a design that anticipates environments where multiple AI integrations might be active concurrently. The host's broad range of responsibilities points to a centralized management approach for the overall AI interaction environment.

Communication within the MCP architecture is structured through distinct layers. The Protocol Layer defines the high-level communication patterns, including how messages are framed and how requests are linked to their corresponding responses . Key components within this layer include the Protocol, Client, and Server classes, with the Protocol class managing both incoming and outgoing requests and notifications. The Transport Layer is responsible for the actual transmission of data between clients and servers. MCP supports several transport mechanisms, including Stdio for local processes and HTTP with Server-Sent Events (SSE) for web-based communication. HTTP with SSE uses SSE for server-to-client communication and standard HTTP POST requests for client-to-server communication. Notably, all transports within the MCP architecture utilize JSON-RPC 2.0 as the standard format for exchanging messages. The choice of JSON-RPC 2.0 as the underlying messaging format is significant as it ensures broad interoperability, leveraging a widely recognized standard for remote procedure calls. The availability of both Stdio and HTTP with SSE transports provides developers with flexibility to choose the most suitable option for their specific deployment scenarios, whether local or remote.

The communication lifecycle in MCP involves a structured sequence of stages. The Initialization phase begins with the client sending an initialize request to the server, which includes information about the client's protocol version and its capabilities. The server then responds with its own protocol version and capabilities. Finally, the client sends an initialized notification to acknowledge the connection, at which point the system is ready for message exchange. Following initialization, the Message Exchange phase allows for two primary communication patterns: Request-Response, where either the client or the server can initiate a request and expect a response from the other party, and Notifications, which are one-way messages that do not require a response. The final stage is Termination, where either the client or the server can end the connection. This can occur through a clean shutdown using a close() function, a disconnection at the transport level, or as a result of error conditions. This well-defined communication lifecycle ensures a predictable and reliable interaction between clients and servers. The initial capability negotiation is particularly important as it allows the communicating parties to understand and agree upon the features and functionalities they both support, ensuring compatibility throughout the session.

For developers interested in working with MCP and Gemini, both Python and Node.js offer robust SDKs. The official Python SDK, accessible at https://github.com/modelcontextprotocol/python-sdk, provides a comprehensive implementation of the full MCP specification. This SDK simplifies the process of building both MCP clients and servers, supports standard transports like stdio and SSE, and provides tools for handling all MCP protocol messages and lifecycle events. Additionally, it offers utilities that streamline model querying and data exchange 12. Complementing the official SDK is fastmcp (https://github.com/jlowin/fastmcp), a Pythonic framework designed to expedite the development of MCP servers. fastmcp aims to provide a complete implementation of the core MCP specification while offering a high-level, intuitive interface that often requires minimal boilerplate code, leveraging Python decorators for ease of use 8. It handles many of the underlying protocol complexities, allowing developers to concentrate on building the specific tools and resources they need 8. Notably, fastmcp has been integrated into the official Python SDK as the recommended high-level framework for server development . The existence of both a full-fledged official SDK and a more streamlined framework like fastmcp provides developers with options based on their specific needs and preferences. fastmcp's focus on ease of use and rapid development makes it an attractive choice for server-side implementations. The continuous updates and feature additions to the Python SDK, such as lifespan support and asynchronous resource handling, indicate an active and evolving ecosystem around MCP in Python.

Setting up a Python development environment for MCP typically involves using the uv package manager, which is highly recommended 5. Installation instructions for uv are available for both Mac/Linux and Windows systems. The process usually involves creating a new project directory, initializing it with uv, creating and activating a virtual environment, and then adding the mcp[cli] dependency using the uv add command. Alternatively, for those preferring pip, the mcp package can be installed using pip install mcp 7. It's important to ensure that Python 3.10 or a later version is installed 5. The strong recommendation for using uv suggests that it may offer specific advantages for managing MCP projects, possibly related to its efficiency or its integration with other tools within the MCP ecosystem, such as Claude Desktop as highlighted by the requirement of uv for deploying servers in some contexts.

To illustrate the development of MCP servers in Python, consider the following examples:

from mcp.server.fastmcp import FastMCP

# Create an MCP server instance named "My App"
mcp = FastMCP("My App")

# Define a tool using the @mcp.tool() decorator
@mcp.tool()
def calculate_bmi(weight_kg: float, height_m: float) -> float:
    """Calculate BMI given weight in kg and height in meters"""
    return weight_kg / (height_m**2)

# Define a resource using the @mcp.resource() decorator
@mcp.resource("config://app")
def get_config() -> str:
    """Static configuration data"""
    return "App configuration here"

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

This code snippet demonstrates the creation of a basic MCP server using fastmcp. The FastMCP("My App") line instantiates the server with a given name. The @mcp.tool() decorator registers the calculate_bmi function as a tool, allowing LLMs to call this function with the specified arguments (weight_kg and height_m) to calculate the Body Mass Index. The docstring associated with the function serves as a description of the tool for the LLM. Similarly, the @mcp.resource("config://app") decorator registers the get_config function as a resource accessible via the URI config://app. This resource simply returns a static string containing application configuration. The use of decorators in fastmcp provides a concise and readable way to define the capabilities of the MCP server.

More advanced examples can involve dynamic resources and the use of the Context object:

from mcp.server.fastmcp import FastMCP, Context

mcp = FastMCP("My App")

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """Dynamic user data"""
    return f"Profile data for user {user_id}"

@mcp.tool()
async def long_task(files: list[str], ctx: Context) -> str:
    """Process multiple files with progress tracking"""
    for i, file in enumerate(files):
        ctx.info(f"Processing {file}")
        await ctx.report_progress(i, len(files))
        # Simulate reading a resource
        # data, mime_type = await ctx.read_resource(f"file://{file}")
    return "Processing complete"

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

Here, the get_user_profile resource demonstrates the use of a URI template users://{user_id}/profile, where {user_id} is a path parameter that will be passed to the function. The long_task tool illustrates how to access the Context object. By including a parameter annotated with Context, fastmcp automatically injects the context object when the tool is called. The Context object provides functionalities like logging (ctx.info()) and reporting progress (ctx.report_progress()). The ability to define both static and dynamic resources through URI templates offers a flexible way to expose different kinds of data to LLMs, similar to how RESTful APIs function. The Context object's features, such as logging and progress reporting, enable developers to build more interactive and observable tools within the MCP framework. The lifespan API, accessible through the context, further enhances resource management by allowing initialization and cleanup at the server level.

Python MCP servers can be run directly using mcp.run() for basic execution. For development and testing, fastmcp offers a Development Mode that can be accessed via the command mcp dev server.py. This mode often includes integration with the MCP Inspector, a GUI tool for testing and debugging MCP servers. Dependencies can be added during development using the --with flag, and local code can be mounted for live updates using --with-editable. Integration with Claude Desktop is also straightforward using the command mcp install server.py, with options for customizing the installation name and setting environment variables 6. The availability of a dedicated development mode with features like dependency management and live updates, along with the integration with the MCP Inspector and platforms like Claude Desktop, significantly streamlines the process of building and testing Python MCP servers.

In the Node.js ecosystem, the primary SDK for MCP is the official TypeScript SDK, available at https://github.com/modelcontextprotocol/typescript-sdk and as an npm package @modelcontextprotocol/sdk 11. This SDK provides a full implementation of the MCP specification, enabling developers to build both clients and servers, utilize standard transports (stdio, SSE), and manage all aspects of the MCP protocol. The SDK also includes examples such as an Echo Server and an SQLite Explorer to help developers get started. Beyond the official SDK, there are other related Node.js projects like mcp-node, which facilitates controlling Node.js via MCP, and community-driven client libraries like mcp-client. The choice of TypeScript for the official SDK reflects the prevalence of TypeScript in server-side development and its benefits for type safety, which is particularly valuable in the context of a structured protocol like MCP. The emergence of community-driven projects indicates a growing interest and adoption of MCP within the Node.js developer community.

Setting up a Node.js environment for MCP development involves having Node.js installed on the system. A new project can be initialized using npm init -y, followed by installing the core SDK dependency with npm install @modelcontextprotocol/sdk. For TypeScript development, it's common to install TypeScript and type definitions for Node.js as development dependencies using npm install --save-dev typescript @types/node and to configure TypeScript compilation via a tsconfig.json file. The npx tool, which comes bundled with Node.js, is often used for executing packages directly from the command line. This setup process aligns with standard Node.js development workflows, making it accessible for developers familiar with this environment. The use of TypeScript, while adding a compilation step, provides significant advantages in terms of code maintainability and early error detection.

Here are example code snippets demonstrating common MCP operations in Node.js:

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

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

server.tool(
  "add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content:
  })
);

server.resource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  async (uri, { name }) => ({
    contents: [{
      uri: uri.href,
      text: `Hello, ${name}!`
    }]
  })
);

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

This code demonstrates the creation of a basic MCP server using the @modelcontextprotocol/sdk. It imports necessary modules and then instantiates an McpServer with a name and version. The server.tool() method defines a tool named "add" that takes two numerical arguments, "a" and "b", validated using Zod. The asynchronous function provided as the third argument implements the tool's logic, returning a result with a text content representing the sum. The server.resource() method defines a resource named "greeting" with a URI template greeting://{name}. The associated asynchronous function handles requests to this resource, extracting the name parameter and returning a personalized greeting as text content. Finally, a StdioServerTransport is created and the server is connected to it, enabling communication via standard input and output. The Node.js SDK provides a well-structured approach to defining tools and resources, with Zod being instrumental in ensuring type safety for the input arguments. The support for different transport mechanisms like Stdio and SSE allows for flexibility in how the server is deployed and accessed.

Node.js MCP servers built with TypeScript are typically built using npm run build, which compiles the TypeScript code into JavaScript. The server can then be run using node build/index.js. For testing and debugging, the MCP Inspector can be used by running npx @modelcontextprotocol/inspector node index.js. Integration with platforms like Claude Desktop can be achieved by configuring the mcpServers section within the Claude Desktop MCP Server configuration file. Additionally, for the Cursor code editor, MCP servers can be configured on a project-specific or global level. Similar to the Python ecosystem, Node.js development with MCP benefits from integrations with tools like the MCP Inspector and direct configuration options within popular development platforms, simplifying the testing and adoption process.

gemini

When prompting a Gemini model for development work involving MCP, it's essential to convey the core principles of the protocol. MCP offers a standardized approach for LLMs to interact with external tools and data, making the understanding of Servers, Clients, Tools, and Resources paramount. Given the availability of well-supported SDKs in both Python and Node.js, developers have flexibility in choosing their preferred language. The provided code examples in this report serve as foundational templates for guiding Gemini to generate custom MCP integrations. It is important to highlight the interoperability of MCP, where a server built in one language can be consumed by a client or LLM application in another, provided they both adhere to the MCP specification 22. This language-agnostic nature, facilitated by the use of JSON-RPC for communication, allows for building flexible and modular systems where different components can be implemented using the most suitable technology.

To effectively prompt Gemini, developers should start by providing the basic MCP server structure in their language of choice, referencing the examples provided in this report for syntax and organization. Specific tools or resources required for the application should then be requested, guiding Gemini to implement them based on the structure and patterns seen in the examples. Instructions on handling input parameters, whether through type hints in Python or Zod schemas in Node.js, should be clearly provided. Furthermore, the expected format for the output of tools and resources, adhering to MCP standards such as the content array with type and text fields, should be specified. Encouraging Gemini to incorporate error handling and logging within the implemented tools and resources will lead to more robust solutions. For more complex scenarios, developers can prompt Gemini to utilize the Context object to leverage advanced functionalities like progress reporting or accessing other resources. Finally, depending on the development task, prompting Gemini to create client-side logic that interacts with the developed MCP server might also be necessary. The inherent interoperability of MCP should be leveraged by emphasizing that a server in Python can communicate seamlessly with a client in Node.js, or vice versa, allowing development teams to utilize their existing skill sets and the best tools for each component of the system.

To summarize, the Model Context Protocol is poised to play a pivotal role in the future of LLM integration, enabling the development of more sophisticated and interconnected AI applications. Its potential for wider adoption across various LLM platforms and development tools is significant, and the ongoing evolution of the protocol and its SDKs promises even more features and improvements. The growing community around MCP, with increasing contributions of servers and clients, further solidifies its position as a key enabler in the AI landscape. As development tools like Cursor integrate MCP more deeply 15, and as the protocol continues to evolve, its importance in building context-aware AI applications will only increase.

Resources for Further Learning:
Official Model Context Protocol website: https://modelcontextprotocol.info/
Official Python SDK repository: https://github.com/modelcontextprotocol/python-sdk
Official TypeScript SDK repository: https://github.com/modelcontextprotocol/typescript-sdk
fastmcp repository: https://github.com/jlowin/fastmcp
List of MCP servers: https://github.com/modelcontextprotocol/servers
MCP Specification: https://modelcontextprotocol.info/specification/
MCP Docs – Model Context Protocol （MCP）https://modelcontextprotocol.info/docs/
Introducing the Model Context Protocol - Anthropic https://www.anthropic.com/news/model-context-protocol
What is the Model Context Protocol (MCP)? - WorkOS https://workos.com/blog/model-context-protocol
Getting Started: Build a Model Context Protocol Server | by Chris McKenzie - Medium 2025, https://medium.com/@kenzic/getting-started-build-a-model-context-protocol-server-9d0362363435
Model Context Protocol (MCP): A Guide With Demo Project - DataCamp] https://www.datacamp.com/tutorial/mcp-model-context-protocol
modelcontextprotocol/python-sdk: The official Python SDK ... - GitHub] https://github.com/modelcontextprotocol/python-sdk mcp
PyPI https://pypi.org/project/mcp/
jlowin/fastmcp: The fast, Pythonic way to build Model ...https://github.com/jlowin/fastmcp
Architecture – Model Context Protocol （MCP）https://modelcontextprotocol.info/specification/draft/architecture/
Core architecture – Model Context Protocol （MCP） https://modelcontextprotocol.info/docs/concepts/architecture
Model Context Protocol https://github.com/modelcontextprotocol
Model Context Protocol Python SDK download | SourceForge.net https://sourceforge.net/projects/model-cont-prot-py.mirror/
Releases · modelcontextprotocol/python-sdk - GitHub https://github.com/modelcontextprotocol/python-sdk/releases
What's New - Model Context Protocol https://modelcontextprotocol.io/development/updates
@modelcontextprotocol/sdk - npm https://www.npmjs.com/package/@modelcontextprotocol/sdk
modelcontextprotocol/typescript-sdk: The official Typescript ... - GitHub https://github.com/modelcontextprotocol/typescript-sdk
dylibso/mcpx-py: Python client library for https://mcp.run - call portable & secure tools for your AI Agents and Apps https://github.com/dylibso/mcpx-py
Accelerating Node.js development with mcp-node - Platformatic Blog https://blog.platformatic.dev/accelerating-nodejs-development-with-mcp-node
An MCP client for Node.js. - GitHub https://github.com/punkpeye/mcp-client
Creating a Model Context Protocol Server: A Step-by-Step Guide | by Michael Bauer-Wapp https://michaelwapp.medium.com/creating-a-model-context-protocol-server-a-step-by-step-guide-4c853fbf5ff2
Integrating Model Context Protocol Tools with Semantic Kernel: A Step-by-Step Guide https://devblogs.microsoft.com/semantic-kernel/integrating-model-context-protocol-tools-with-semantic-kernel-a-step-by-step-guide/
A quick look at MCP with Large Language Models and Node.js | Red Hat Developer https://developers.redhat.com/blog/2025/01/22/quick-look-mcp-large-language-models-and-nodejs
Model Context Protocol - Cursor https://docs.cursor.com/context/model-context-protocol