{"title":"Model Context Protocol (MCP)","description":"","content":"You have built function calling into your AI application. The weather tool works, the database lookup works, the file reader works. Then your teammate builds a different AI application and needs the exact same tools. So they copy your code, adjust the interfaces, fix the bugs they introduced during copy-paste, and now you have two slightly different versions of the same tools in two different codebases. A month later, someone else builds a third application. Same story. Three copies, three sets of bugs, three maintenance burdens.\n\nThis is not a hypothetical scenario. It is the reality of AI tool integration today. Every AI application builds its own bespoke connections to external tools and data sources. Your weather tool code for a chatbot cannot be reused in a coding assistant. Your database query tool for one project has a completely different interface than the one your colleague built for theirs. There is no standard way to package a tool so that any AI application can discover and use it. Every integration is a snowflake. The Model Context Protocol (MCP) was created to fix this, by defining a universal, open standard for connecting AI models to external capabilities, the same way USB standardized how hardware peripherals connect to computers.\n\n---\n\n# The USB Analogy\n\nBefore USB existed, every hardware device had its own proprietary connector. Your printer used a parallel port. Your mouse used a PS/2 port. Your modem used a serial port. Your keyboard used a different PS/2 port. Every manufacturer designed their own cable, their own protocol, and their own driver. If you wanted to connect N devices to M computers, you needed N x M different integrations.\n\nUSB changed that equation. It defined a single standard that every device and every computer could implement. Now you needed N + M implementations instead of N x M. Any USB device works with any USB port. The device manufacturer implements the USB standard once, and it works everywhere.\n\nMCP does the same thing for AI tool integrations.\n\n\n```mermaid\nflowchart TD\n subgraph Before[\"BEFORE MCP: N x M Integrations\"]\n A1[App 1]:::primary --> T1[Weather Tool v1]:::red\n A1 --> T2[Database Tool v1]:::red\n A1 --> T3[File Tool v1]:::red\n A2[App 2]:::primary --> T4[Weather Tool v2]:::red\n A2 --> T5[Database Tool v2]:::red\n A2 --> T6[File Tool v2]:::red\n A3[App 3]:::primary --> T7[Weather Tool v3]:::red\n A3 --> T8[Database Tool v3]:::red\n A3 --> T9[File Tool v3]:::red\n end\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\n\n```mermaid\nflowchart TD\n subgraph After[\"AFTER MCP: N + M Integrations\"]\n B1[App 1]:::primary --> MCP[\"MCP Protocol\"]:::orange\n B2[App 2]:::primary --> MCP\n B3[App 3]:::primary --> MCP\n MCP --> S1[Weather Server]:::green\n MCP --> S2[Database Server]:::green\n MCP --> S3[File Server]:::green\n end\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nWithout MCP, three applications connecting to three tools requires nine separate integrations. With MCP, each application implements the MCP client protocol once, each tool implements the MCP server protocol once, and everything connects. Three client implementations plus three server implementations, six total instead of nine. The savings grow dramatically as the ecosystem scales. Ten applications and twenty tools? That is 200 custom integrations versus 30 MCP implementations.\n\nMCP is an open standard created by Anthropic and adopted by a growing number of AI clients and tool providers. It is not tied to a specific model or vendor. Any AI application that speaks MCP can use any MCP server, regardless of who built either side.\n\n---\n\n# MCP Architecture\n\nMCP defines three distinct roles that work together to connect AI applications with external capabilities.\n\n\n```mermaid\nflowchart LR\n subgraph Host[\"HOST (AI Application)\"]\n LLM[\"LLM\"]:::primary\n C1[\"MCP Client 1\"]:::orange\n C2[\"MCP Client 2\"]:::orange\n LLM --- C1\n LLM --- C2\n end\n\n C1 --> S1[\"MCP Server A
File System\"]:::green\n C1 --> S2[\"MCP Server B
GitHub\"]:::green\n C2 --> S3[\"MCP Server C
Database\"]:::green\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\n#### **Host**\n\nThis is the AI application your users interact with. Claude Desktop, a VS Code extension with AI capabilities, your custom chatbot, anything that contains an LLM and wants to give it access to external tools. The host is responsible for managing conversations, enforcing security policies, and deciding which servers to connect to. A single host can manage multiple MCP clients.\n\n#### **Client**\n\nThe client lives inside the host and manages the connection to a specific MCP server. It handles the protocol details: establishing connections, discovering what capabilities the server offers, sending requests, and receiving responses. Each client maintains a 1:1 relationship with a server. If your host connects to three servers, it runs three clients.\n\n#### **Server**\n\nThe server is where the actual capabilities live. It exposes tools, data, and prompts through the MCP protocol. A file system server provides file reading and searching. A GitHub server provides repository access. A database server provides query execution. Servers are lightweight programs that can run locally (as a subprocess) or remotely (as a web service).\n\n### How Communication Flows\n\nWhen a user asks the AI a question that requires external data, here is what happens step by step.\n\n1. The user sends a message to the host application.\n2. The host forwards the message to the LLM, along with descriptions of available tools from all connected MCP servers.\n3. The LLM decides it needs to call a tool and generates a tool call request (this is the function calling pattern from earlier in this module).\n4. The host routes the tool call to the appropriate MCP client.\n5. The client sends the request to the corresponding MCP server using the MCP protocol.\n6. The server executes the operation (reads a file, queries a database, calls an API) and returns the result.\n7. The client passes the result back to the host.\n8. The host includes the result in the next LLM call.\n9. The LLM generates a response grounded in the tool's output.\n\nThis flow should look familiar. It is the same tool-use loop we covered in Chapter 6.2, but with a standardized protocol between the application and the tools.\n\n### Transport Layer\n\nMCP supports two transport mechanisms for communication between clients and servers.\n\n**stdio (Standard Input/Output).** The server runs as a local subprocess of the host application. Communication happens through stdin and stdout using JSON-RPC messages. This is the simplest transport. No network configuration, no authentication, no firewall issues. The server starts when the host starts and stops when the host stops. Best for local tools like file system access, local database queries, or command-line utilities.\n\n**Streamable HTTP.** The server runs as a web service accessible over HTTP. The client sends requests via HTTP POST and receives responses (including streaming updates) via Server-Sent Events (SSE). This transport works for remote servers, servers shared across multiple users, and servers that need to run on different machines than the host. It requires more setup (URLs, authentication, network access) but enables much more flexible deployment patterns.\n\n\n| Transport | How it works | Best for | Setup complexity |\n|-----------|-------------|----------|-----------------|\n| **stdio** | Server runs as local subprocess, communicates via stdin/stdout | Local tools, single-user, file system access | Low |\n| **Streamable HTTP** | Server runs as web service, uses HTTP + SSE | Remote tools, shared servers, cloud services | Medium |\n\n\nMost MCP servers you will encounter use stdio for local development and Streamable HTTP for production deployment. The protocol messages are identical regardless of transport, so a server can support both without changing its logic.\n\n---\n\n# MCP Primitives\n\nMCP servers expose three types of capabilities to clients. Understanding when to use each one is key to designing good MCP servers.\n\n### Resources\n\nResources represent data that the server makes available to the AI. Think of them as files or documents the AI can read. A file system server exposes files as resources. A database server might expose query results as resources. An API server could expose endpoint responses as resources.\n\nResources are identified by URIs (like `file:///home/user/document.txt` or `db://products/schema`). The client can list available resources, read their contents, and in some cases subscribe to changes.\n\nThe key characteristic of resources is that they are **data-oriented**. They do not perform actions or have side effects. Reading a resource should be safe to do at any time.\n\n### Tools\n\nTools are functions the AI can call to perform actions or computations. This is the same concept as function calling from Chapter 6.1, but packaged in a standardized way. A tool has a name, a description, and a JSON schema defining its parameters.\n\nTools are **action-oriented**. They can have side effects: writing files, sending emails, creating database records, making API calls. Because of this, MCP clients typically require user confirmation before executing tool calls, or enforce security policies about which tools are allowed.\n\n### Prompts\n\nPrompts are reusable prompt templates that the server provides to the client. A GitHub server might offer a \"code review\" prompt template that structures how the AI should analyze a pull request. A database server might offer a \"query optimization\" prompt that guides the AI through analyzing slow queries.\n\nPrompts are **interaction-oriented**. They shape how the AI approaches a task, not what data it accesses or what actions it takes.\n\n### Comparing the Three Primitives\n\n\n| Primitive | Purpose | Controlled by | Example |\n|-----------|---------|--------------|---------|\n| **Resources** | Expose data for the AI to read | Application (client decides when to read) | Files, database schemas, API docs |\n| **Tools** | Let the AI perform actions | Model (AI decides when to call) | File search, database query, API call |\n| **Prompts** | Provide reusable prompt templates | User (user selects which prompt to use) | Code review template, debug guide |\n\n\nIn practice, tools are by far the most commonly used primitive. Most MCP servers expose a handful of tools and maybe a few resources. Prompts are less common but useful for servers that provide specialized workflows.\n\n---\n\n# Building an MCP Server (Python SDK)\n\nLet's build a working MCP server from scratch. We will create a file system server that exposes three tools (list files, read a file, search files) and one resource (reading files by URI). This is a practical server you could actually connect to Claude Desktop or any other MCP client.\n\nFirst, install the MCP Python SDK:\n\n\n```shell\npip install mcp\n```\n\n\nNow, here is the complete server implementation:\n\n\n```python\nimport os\nimport json\nfrom pathlib import Path\nfrom mcp.server.fastmcp import FastMCP\n\n# Create the MCP server\nmcp = FastMCP(\"filesystem\")\n\n# Define the root directory this server can access\nROOT_DIR = Path.home() / \"documents\"\n\n@mcp.tool()\ndef list_files(directory: str = \"\") -> str:\n \"\"\"List files and directories at the given path relative to the root directory.\n\n Args:\n directory: Relative path within the root directory. Empty string for root.\n\n Returns:\n JSON string with list of files and their types.\n \"\"\"\n target = ROOT_DIR / directory\n target = target.resolve()\n\n # Security: prevent directory traversal outside root\n if not str(target).startswith(str(ROOT_DIR.resolve())):\n return json.dumps({\"error\": \"Access denied: path outside root directory\"})\n\n if not target.exists():\n return json.dumps({\"error\": f\"Directory not found: {directory}\"})\n\n if not target.is_dir():\n return json.dumps({\"error\": f\"Not a directory: {directory}\"})\n\n entries = []\n for item in sorted(target.iterdir()):\n entries.append({\n \"name\": item.name,\n \"type\": \"directory\" if item.is_dir() else \"file\",\n \"size\": item.stat().st_size if item.is_file() else None,\n })\n\n return json.dumps({\"path\": directory or \"/\", \"entries\": entries}, indent=2)\n\n@mcp.tool()\ndef read_file(filepath: str) -> str:\n \"\"\"Read the contents of a file.\n\n Args:\n filepath: Path to the file relative to the root directory.\n\n Returns:\n The file contents as a string, or an error message.\n \"\"\"\n target = (ROOT_DIR / filepath).resolve()\n\n # Security: prevent directory traversal outside root\n if not str(target).startswith(str(ROOT_DIR.resolve())):\n return f\"Error: Access denied. Path is outside the root directory.\"\n\n if not target.exists():\n return f\"Error: File not found: {filepath}\"\n\n if not target.is_file():\n return f\"Error: Not a file: {filepath}\"\n\n # Limit file size to prevent reading huge files\n max_size = 1_000_000 # 1 MB\n if target.stat().st_size > max_size:\n return f\"Error: File too large ({target.stat().st_size} bytes). Max: {max_size} bytes.\"\n\n return target.read_text(encoding=\"utf-8\", errors=\"replace\")\n\n@mcp.tool()\ndef search_files(query: str, directory: str = \"\", extension: str = \"\") -> str:\n \"\"\"Search for files containing the query string.\n\n Args:\n query: Text to search for within files.\n directory: Subdirectory to search in. Empty for entire root.\n extension: Filter by file extension (e.g., '.txt', '.py'). Empty for all files.\n\n Returns:\n JSON string with matching files and the lines that matched.\n \"\"\"\n search_dir = (ROOT_DIR / directory).resolve()\n\n if not str(search_dir).startswith(str(ROOT_DIR.resolve())):\n return json.dumps({\"error\": \"Access denied: path outside root directory\"})\n\n if not search_dir.exists():\n return json.dumps({\"error\": f\"Directory not found: {directory}\"})\n\n matches = []\n max_results = 20\n max_file_size = 500_000 # Skip files larger than 500 KB\n\n for path in search_dir.rglob(\"*\"):\n if len(matches) >= max_results:\n break\n\n if not path.is_file():\n continue\n\n if extension and path.suffix != extension:\n continue\n\n if path.stat().st_size > max_file_size:\n continue\n\n try:\n content = path.read_text(encoding=\"utf-8\", errors=\"replace\")\n matching_lines = []\n for i, line in enumerate(content.splitlines(), 1):\n if query.lower() in line.lower():\n matching_lines.append({\"line_number\": i, \"text\": line.strip()})\n\n if matching_lines:\n matches.append({\n \"file\": str(path.relative_to(ROOT_DIR)),\n \"matches\": matching_lines[:5], # Limit matches per file\n })\n except (PermissionError, UnicodeDecodeError):\n continue\n\n return json.dumps({\n \"query\": query,\n \"total_matches\": len(matches),\n \"results\": matches,\n }, indent=2)\n\n@mcp.resource(\"file:///{filepath}\")\ndef read_file_resource(filepath: str) -> str:\n \"\"\"Read a file as an MCP resource.\n\n Args:\n filepath: Path to the file relative to the root directory.\n \"\"\"\n target = (ROOT_DIR / filepath).resolve()\n\n if not str(target).startswith(str(ROOT_DIR.resolve())):\n return \"Error: Access denied.\"\n\n if not target.exists() or not target.is_file():\n return \"Error: File not found.\"\n\n return target.read_text(encoding=\"utf-8\", errors=\"replace\")\n\nif __name__ == \"__main__\":\n mcp.run()\n```\n\n\nLet's walk through the key decisions in this server.\n\n**Security boundaries.** Every tool resolves the requested path and checks that it falls within `ROOT_DIR`. Without this check, a malicious prompt could trick the AI into reading `/etc/passwd` or other sensitive files by using `../` path traversal. This is not paranoia. It is a real attack vector when AI models control file access.\n\n**Size limits.** Both `read_file` and `search_files` enforce maximum file sizes. An LLM's context window has finite capacity, and dumping a 50 MB log file into it helps nobody. The limits keep responses useful and prevent accidental resource exhaustion.\n\n**The `@mcp.tool()` decorator.** This is the core of the FastMCP API. It registers a Python function as an MCP tool. The function's docstring becomes the tool description, and the type hints become the JSON schema that the AI uses to understand what parameters the tool accepts. You do not need to write JSON schemas by hand.\n\n**The `@mcp.resource()` decorator.** This registers a URI pattern that clients can use to read data directly. The `{filepath}` in the URI template becomes a parameter passed to the function. Resources provide an alternative to tools for data access, they are explicitly data-oriented and do not imply actions.\n\n### Testing Your Server Locally\n\nYou can test the server directly from the command line using the MCP inspector:\n\n\n```shell\n# Run the MCP inspector to test your server interactively\nmcp dev filesystem_server.py\n```\n\n\nThe inspector opens a web interface where you can see the tools your server exposes, call them with test parameters, and inspect the responses. This is the fastest way to verify your server works before connecting it to an actual AI client.\n\nYou can also test it programmatically:\n\n\n```python\nimport asyncio\nfrom mcp import ClientSession, StdioServerParameters\nfrom mcp.client.stdio import stdio_client\n\nasync def test_server():\n server_params = StdioServerParameters(\n command=\"python\",\n args=[\"filesystem_server.py\"],\n )\n\n async with stdio_client(server_params) as (read, write):\n async with ClientSession(read, write) as session:\n await session.initialize()\n\n # List available tools\n tools = await session.list_tools()\n print(\"Available tools:\")\n for tool in tools.tools:\n print(f\" - {tool.name}: {tool.description}\")\n\n # Call the list_files tool\n result = await session.call_tool(\"list_files\", {\"directory\": \"\"})\n print(f\"\\nRoot directory listing:\\n{result.content[0].text}\")\n\nasyncio.run(test_server())\n```\n\n\n**Output:**\n\n\n```shell\nAvailable tools:\n - list_files: List files and directories in the specified directory\n - read_file: Read the contents of a file\n - search_files: Search for files containing a specific keyword\n\nRoot directory listing:\nREADME.md\nfilesystem_server.py\nrequirements.txt\nsrc/\n```\n\n\nThis test client connects to your server over stdio, discovers the available tools, and calls `list_files`. The output shows you exactly what an AI client would see when connecting to your server.\n\n---\n\n# Connecting to Existing MCP Servers\n\nBuilding your own server is useful, but the real power of MCP comes from the ecosystem of pre-built servers. You can connect to servers that other people built without writing any integration code.\n\n### Claude Desktop Configuration\n\nClaude Desktop is one of the most widely used MCP clients. To connect it to an MCP server, you edit a configuration file.\n\nOn macOS, the config file is at:\n\n\n```shell\n~/Library/Application Support/Claude/claude_desktop_config.json\n```\n\n\nOn Windows:\n\n\n```shell\n%APPDATA%\\Claude\\claude_desktop_config.json\n```\n\n\nHere is a configuration that connects Claude Desktop to three MCP servers:\n\n\n```json\n{\n \"mcpServers\": {\n \"filesystem\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/filesystem_server.py\"],\n \"env\": {}\n },\n \"github\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n \"env\": {\n \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"ghp_your_token_here\"\n }\n },\n \"sqlite\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-sqlite\", \"/path/to/database.db\"],\n \"env\": {}\n }\n }\n}\n```\n\n\nEach entry in `mcpServers` defines a server connection. The `command` and `args` tell Claude Desktop how to launch the server process. The `env` object passes environment variables the server needs, like API tokens.\n\nAfter saving this file and restarting Claude Desktop, you will see the available tools in the chat interface. When you ask Claude a question that requires file access, GitHub data, or database queries, it will automatically call the appropriate MCP server.\n\n### Popular MCP Servers\n\nThe MCP ecosystem is growing quickly. Here are some of the most useful pre-built servers.\n\n\n| Server | What it does | Package |\n|--------|-------------|---------|\n| **Filesystem** | Read, write, search files on your local machine | `@modelcontextprotocol/server-filesystem` |\n| **GitHub** | Access repos, issues, PRs, file contents | `@modelcontextprotocol/server-github` |\n| **SQLite** | Query SQLite databases, inspect schemas | `@modelcontextprotocol/server-sqlite` |\n| **PostgreSQL** | Query PostgreSQL databases | `@modelcontextprotocol/server-postgres` |\n| **Brave Search** | Web search using the Brave Search API | `@modelcontextprotocol/server-brave-search` |\n| **Memory** | Persistent memory store for conversations | `@modelcontextprotocol/server-memory` |\n\n\nThese servers are all open source and follow the same MCP standard. You install them, configure the connection in your client, and they work. No custom integration code needed.\n\n---\n\n# MCP vs Custom Function Calling\n\nAt this point you might be wondering: when should I use MCP, and when should I stick with the custom function calling approach from Chapters 6.1 and 6.2?\n\nThe answer depends on your goals.\n\n### When to Use MCP\n\n#### **You want reusable tools**\n\nIf you are building a tool that multiple applications could use (a database connector, a file reader, an API wrapper), packaging it as an MCP server means any MCP-compatible client can use it without modification. Build once, use everywhere.\n\n#### **You want to leverage existing servers**\n\nThe MCP ecosystem already has servers for common integrations: file systems, databases, GitHub, web search, and more. Using these saves you from writing boilerplate integration code.\n\n#### **You are building a platform**\n\nIf you are creating an AI application that end users can extend with their own tools, MCP provides a standard way for those tools to plug in. Users can install MCP servers the same way they install browser extensions.\n\n#### **You need multi-client support**\n\nIf the same tool needs to work with Claude Desktop, VS Code, a custom chatbot, and a CI/CD pipeline, MCP ensures compatibility across all of them.\n\n### When to Use Custom Function Calling\n\n#### **You need tight integration**\n\nIf your tool is deeply intertwined with your application's internal state, session context, or business logic, custom function calling gives you full control. An MCP server runs as a separate process with its own lifecycle, which adds a layer of indirection that may not be worth it for tightly coupled tools.\n\n#### **You have a simple use case**\n\nIf your application needs two or three tools and will never share them with other projects, the overhead of running MCP servers is unnecessary. A few function definitions inline in your application are simpler.\n\n#### **You need maximum performance**\n\nMCP adds serialization overhead (JSON-RPC messages over stdio or HTTP). For tools that are called thousands of times per minute with latency-sensitive results, direct function calls are faster.\n\n#### **You need custom security models**\n\nMCP has its own security model (transport-level security, user confirmation for tool calls). If your application requires a different security model, such as fine-grained per-user permissions, audit logging, or custom authentication flows, direct integration gives you more control.\n\n### Comparison Table\n\n\n| Dimension | MCP | Custom Function Calling |\n|-----------|-----|------------------------|\n| **Reusability** | High. Any MCP client can use any MCP server | Low. Tied to your specific application |\n| **Setup complexity** | Medium. Need MCP SDK, server process, client config | Low. Define functions inline |\n| **Ecosystem** | Growing. Many pre-built servers available | None. You build everything |\n| **Performance** | Slight overhead from serialization and IPC | Direct function calls, minimal overhead |\n| **Flexibility** | Standardized protocol, some constraints | Complete control over interface |\n| **Multi-model support** | Built in. Protocol is model-agnostic | You implement per-model differences |\n| **Debugging** | MCP inspector, structured logs | Standard debugger, custom logging |\n\n\n### They Are Not Mutually Exclusive\n\nHere is something important: you do not have to choose one or the other. Many production applications use both. They use MCP for standard integrations (file system, databases, third-party APIs) and custom function calling for application-specific logic (user session management, internal business rules, custom workflows).\n\nThink of MCP as the standard library and custom function calling as your application code. You use the standard library for common tasks and write custom code for what makes your application unique.\n\n\n```mermaid\nflowchart TD\n APP[\"AI Application\"]:::primary\n\n subgraph MCP_Layer[\"MCP Servers (Standardized)\"]\n FS[\"File System
Server\"]:::green\n DB[\"Database
Server\"]:::green\n GH[\"GitHub
Server\"]:::green\n end\n\n subgraph Custom_Layer[\"Custom Functions (Application-Specific)\"]\n AUTH[\"User Auth
Check\"]:::orange\n BIZ[\"Business Logic
Validation\"]:::orange\n STATE[\"Session State
Management\"]:::orange\n end\n\n APP --> MCP_Layer\n APP --> Custom_Layer\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n```\n\n\nThe AI application connects to MCP servers for standard capabilities and uses custom function calling for logic that is specific to the application's domain. Both approaches feed tool results back into the LLM through the same tool-use loop.\n\n---\n\n### References\n\n- [Model Context Protocol Specification](undefined) - The official MCP documentation and specification\n- [MCP Python SDK](undefined) - Python SDK for building MCP clients and servers\n- [MCP Servers Repository](undefined) - Collection of pre-built MCP servers for common integrations\n- [Anthropic: Introducing the Model Context Protocol](undefined) - Announcement blog post explaining the motivation behind MCP\n- [MCP Inspector](undefined) - Development tool for testing and debugging MCP servers","pageType":"ai-engineering"}

Model Context Protocol (MCP)

Ashish Pratap Singh

Get Premium