Model Context Protocol (MCP) Tutorial: Build Your First MCP Server in 6 Steps

Context Protocol (MCP)?

Because of the emergence of AI brokers and RAG-based purposes in recent times, there’s an growing demand for customizing Massive Language Fashions (LLMs) by integrating with exterior sources (e.g. RAG-based techniques) and instruments (e.g. Agent-based techniques). This enhances LLMs’ present capabilities by incorporating exterior data and enabling autonomous process execution.

Mannequin Context Protocol (MCP), first launched in November 2024 by Anthropic, has grown in reputation because it provides a extra coherent and constant option to join LLMs with exterior instruments and sources, making it a compelling various to constructing customized API integrations for every use case. MCP is a standardized, open-source protocol that gives a constant interface that allow LLM to work together with numerous exterior instruments and sources, therefore enable finish customers to MCP server that has been encapsulated with enhanced functionalities. In comparison with present agentic system design patterns, MCP provides a number of key advantages:

• Improve scalability and maintainability of the system by way of standardized integrations.
• Cut back duplicate improvement effort since a single MCP server implementation works with a number of MCP purchasers.
• Keep away from vendor lock-in by offering flexibility to modify between LLM suppliers, for the reason that LLM is now not tightly coupled with the agentic system.
• Velocity up the event course of considerably by enabling speedy creation of workable merchandise.

This text is goal for guiding you thru the basics of Mannequin Context Protocol and the important parts of constructing an MCP server. We’ll apply these ideas by way of a sensible instance of constructing a MCP server that enables LLMs to summarize and visualize GitHub codebases by merely offering a URL like the instance under.

Consumer Enter:

https://github.com/aws-samples/aws-cdk-examples/blob/main/python/codepipeline-docker-build/Base.py

MCP Output:

Understanding MCP Parts

MCP Structure

MCP adopts a client-server structure the place the consumer is a tool or software that requests providers provided by a centralized server. A useful analogy for the client-server relationship is that of a buyer and a restaurant. The client acts just like the client-side, sending requests by ordering from the menu, whereas the restaurant resembles the server, offering providers like dishes and seatings. The restaurant possesses enough sources to serve a number of clients in a brief time period, whereas clients solely want to fret about receiving their orders.

MCP structure consists of three parts: MCP server, MCP consumer and MCP host. MCP server provides instruments and sources, exposing functionalities that AI fashions can leverage by way of structured requests. MCP host provides the runtime setting that manages communication between purchasers and servers, equivalent to Claude Desktop or IDEs with MCP-supported extensions. If we proceed with the identical customer-restaurant analogy above, MCP host might be thought-about as a restaurant administration system that coordinates communications between clients (purchasers) and eating places, handles order taking and cost processing. MCP consumer is usually constructed into the host software permitting the customers to work together with the server by way of an interface. Nevertheless, there’s the pliability of creating customized MCP purchasers for specialised use circumstances and necessities, equivalent to constructing a easy AI net app utilizing Streamlit to help extra front-end functionalities.

MCP Server Parts

On this article, we’ll concentrate on understanding MCP server and apply our data to construct a easy, customized MCP server. MCP server wraps round numerous APIs calls to the exterior instruments and sources, enabling the purchasers accessing these functionalities with out worrying in regards to the additional setup. The MCP server helps incorporating three sorts of parts which aligns with three widespread LLM customization methods.

• Sources are knowledge, recordsdata and paperwork that function the exterior data base to complement LLM’s present data. That is significantly helpful in a RAG-based system.
• Instruments are executable capabilities and integrations with different applications to complement LLM’s motion area, for instance, carry out Google Search, create a Figma prototype and so on, which might be leveraged in an Agent-based system.
• Prompts are pre-defined instruction templates to information LLM’s output, e.g. response in knowledgeable or informal tone. That is helpful within the system that advantages from immediate engineering strategies.

If you’re to know extra about LLM customization methods, take a look at my earlier article and video on “6 Common LLM Customization Strategies Briefly Explained”.

Construct Your MCP Server in 6 Steps

We’ll use a easy instance to show methods to construct your first MCP server utilizing Python, which allows calling a customized visualize_code instrument to show uncooked code recordsdata extracted from GitHub repositories into visible diagrams like the next instance.

For folks with knowledge science background studying to construct MCP servers, there are a number of software program improvement ideas that could be unfamiliar however necessary to know: asynchronous programming for dealing with asynchronous operations, consumer/server structure, and Python decorators for modifying perform habits. We’ll clarify these ideas in additional element as we stroll by way of this sensible instance.

Step 1. Atmosphere Setup

• Bundle managers setup: MCP makes use of uv because the default bundle supervisor. For macOS and Linux system, set up uv and execute it utilizing sh with the shell command:

• Provoke a brand new working listing /visible, activate the digital setting, create the venture construction to retailer the principle script visible.py:

# Create a brand new listing for our venture
uv init visible
cd visible

# Create digital setting and activate it
uv venv
supply .venv/bin/activate

# Set up dependencies
uv add "mcp[cli]" httpx

# Create our server file
contact visible.py

• Set up required dependencies: pip set up mcp httpx fastapi uvicorn

Additional Studying:

The official weblog put up from Anthropic “For Server Developers – Model Context Protocol” gives easy-to-follow information for establishing the MCP server improvement setting.

Step 2: Primary Server Setup

Within the visible.py script, import the required libraries and provoke our MCP server occasion and outline a consumer agent for making HTTP requests. We’ll use FastMCP because the official Python MCP SDK.

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("visual_code_server")

Step 3: Create Helper Features

We’ll create a helper perform get_code() to fetch code from the GitHub URL.

async def get_code(url: str) -> str:
    """
    Fetch supply code from a GitHub URL.
    
    Args:
        url: GitHub URL of the code file
    Returns:
        str: Supply code content material or error message
    """
    USER_AGENT = "visual-fastmcp/0.1"

    headers = {
        "Consumer-Agent": USER_AGENT,
        "Settle for": "textual content/html"
    }
    
    async with httpx.AsyncClient() as consumer:
        strive:
            # Convert GitHub URL to uncooked content material URL
            raw_url = url.substitute("github.com", "uncooked.githubusercontent.com")
                        .substitute("/blob/", "/")
            response = await consumer.get(raw_url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.textual content
        besides Exception as e:
            return f"Error fetching code: {str(e)}"

Let’s break down the get_code() perform into a number of parts.

Asynchronous Implementation

Asynchronous programming permits a number of operations to run concurrently, bettering effectivity by not blocking execution whereas ready for operations to finish. It’s usually used to deal with I/O operations effectively, equivalent to community request, consumer inputs and API calls. In distinction, synchronous operations, usually used for machine studying duties, are executed sequentially, with every operation blocking till completion earlier than transferring to the following process. The next modifications are made to outline this perform asynchronously:

• The perform is asserted with async def to permit dealing with a number of operations concurrently.
• Use async with context supervisor and httpx.AsyncClient() for non-blocking HTTP requests.
• Deal with asynchronous HTTP requests by including await key phrase to consumer.get().

URL Processing

Configure Settle for header for HTML content material and set applicable Consumer-Agent to establish the consumer making the HTTP requests, i.e. visual-fastmcp/0.1 . Convert common GitHub URLs to uncooked file format.

Error Dealing with

Catch HTTP-specific exceptions (httpx.RequestError, httpx.HTTPStatusError) and catch different generic exception dealing with as fallback, then return descriptive error messages for debugging.

Additional Studying:

Step 4: Implement the MCP Server Instrument

Utilizing a number of additional traces of code, we are able to now create our important MCP server instrument visualize_code().

@mcp.instrument()
async def visualize_code(url: str) -> str:
    """
    Visualize the code extracted from a Github repository URL within the format of SVG code.

    Args:
        url: The GitHub repository URL
    
    Returns:
        SVG code that visualizes the code construction or hierarchy.
    """

    code = await get_code(url)
    if "error" in code.decrease():
        return code
    else:
        return "n---n".be part of(code)
    return "n".be part of(visualization)

Decorator

A Python Decorator is a particular perform that modifies or enhances the habits of one other perform or methodology with out altering its unique code. FastMCP gives decorators that wrap round customized capabilities to combine them into the MCP server. For instance, we use @mcp.instrument() to create an MCP server instrument by adorning the visualize_code perform. Equally, we are able to use @mcp.useful resource() for sources and @mcp.immediate() for prompts.

Sort Trace and Docstring

The FastMCP class leverages Python sort hints and docstrings to robotically enhancing instrument definitions, simplifying the creation and upkeep of MCP instruments. For our use case, we create instrument capabilities with sort hints visualize_code(url: str) -> str, accepting enter parameter url with string format and producing the output as a mixed string of all code extracted from the supply file. Then, add the docstring under to assist the LLM to know instrument utilization.

    """
    Visualize the code extracted from a Github repository URL within the format of SVG code.

    Args:
        url: The GitHub repository URL
    
    Returns:
        SVG code that visualizes the code construction or hierarchy.
    """

Let’s examine how the MCP instrument capabilities with and with out docstring supplied, by calling the MCP server by way of the Claude Desktop.

Mannequin output with out docstring – solely textual content abstract is generated

Mannequin output with docstring supplied – each textual content abstract and diagram are generated

Additional studying:

Step 5: Configure the MCP Server

Add the principle execution block because the final step within the visible.py script. Run the server domestically with easy I/O transport utilizing “stdio”. When working the code in your native machine, the MCP server is situated in your native machine and listening for instrument requests from MCP purchasers. For manufacturing deployment, you may configure totally different transport choices like “streamable-http” for web-based deployments.

if __name__ == "__main__":
    mcp.run(transport='stdio')

Step 6. Use the MCP Server from Claude Desktop

We’ll show methods to use this MCP server by way of Claude Desktop, nonetheless, please be aware that it permits connecting the server to totally different hosts (e.g. Cursor) by barely tweaking the configuration. Take a look at “For Claude Desktop Users – Model Context Protocol” for Claude’s official information.

1. Obtain the Claude Desktop
2. Arrange config file for server settings in your native folder ~/Library/Software Assist/Claude/claude_desktop_config.json (for MacOS) and replace to your personal working folder path.

{
    "mcpServers": {
        "visible": {
            "command": "uv",
            "args": [
                "--directory",
                "/visual",
                "run",
                "visual.py"
            ]
        }
    }
}

3. Run it utilizing command line uv --directory /visible run visible.py
4. Launch (or restart) Claude Desktop and choose the “Search and instruments” then “visible”. It is best to have the ability to toggle on the visualize_code instrument we simply created.

5. Attempt the visualization instrument by offering a GitHub URL, for instance:

Take-Dwelling Message

This text gives an summary of MCP structure (MCP consumer, host and server), with the first concentrate on MCP server parts and purposes. It guides by way of the method of constructing a customized MCP server that permits code-to-diagram from GitHub repositories.

Important steps for constructing a customized MCP server:

1. Atmosphere Setup
2. Primary Server Setup
3. Create Helper Features
4. Implemente the MCP Instrument
5. Configure the MCP Server
6. Use the MCP Server from Claude Desktop

If you’re concerned with additional exploration, potential instructions embody exploring distant MCP servers on cloud supplier, implementing safety features and strong error dealing with.

Extra Contents Like This