Mannequin Context Protocol (MCP) Tutorial: Constructing your first MCP server in 6 steps

Context Protocol (MCP)?

On account of the current emergence of AI brokers and RAG-based purposes, there’s a rising demand for customizing large-scale language fashions (LLMs) by integrating with exterior assets (RAG-based techniques) and instruments (resembling agent-based techniques). This enhances present capabilities of LLMS by incorporating exterior information and permitting for autonomous job execution.

First launched by humanity in November 2024, the Mannequin Context Protocol (MCP) is gaining reputation because it supplies a extra coherent and constant technique to join LLMS with exterior instruments and assets, and is a compelling different to constructing customized API integrations for every use case. MCP is a standardized open supply protocol that gives a constant interface that permits LLM to work together with quite a lot of exterior instruments and assets, permitting finish customers to encapsulate MCP servers with enhanced performance. In comparison with present agent system design patterns, MCP provides a number of necessary benefits.

• Standardized integration improves system scalability and maintainability.
• A single MCP server implementation works with a number of MCP shoppers, lowering overlapping growth efforts.
• Keep away from vendor lock-in by flexibly switching between LLM suppliers as LLM doesn’t join tightly to the agent system.
• It dramatically accelerates the event course of by enabling speedy creation of viable merchandise.

This text goals to information you thru the basics of the mannequin context protocol and the important thing elements for constructing an MCP server. These ideas apply by way of sensible examples of constructing an MCP server the place LLM can merely present URLs resembling the instance beneath to summarize and visualize the GitHub codebase.

Person enter:

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

MCP output:

---

Understanding MCP Elements

MCP Structure

MCP employs a client-server structure. A shopper is a tool or software on which the shopper requests companies supplied by a centralized server. A helpful similarity in client-server relationships is the similarity between prospects and eating places. Clients act like shoppers and ship requests by ordering by way of the menu, however eating places are much like servers, providing companies resembling meals and seating. Eating places have sufficient assets to serve a number of prospects in a brief time frame, however prospects merely fear about receiving their orders.

The MCP structure consists of three elements: MCP server, MCP shopper, MCP host. MCP Server It supplies instruments and assets, exposes the capabilities that AI fashions could be leveraged by way of structured requests. MCP Host Supplies a runtime atmosphere that manages communication between shoppers and servers, resembling Claude desktops and IDES with MCP-supported extensions. Persevering with the analogy of the identical buyer restaurant above, the MCP host could be seen as a restaurant administration system that coordinates communication between the shopper (shopper) and the restaurant and processes order acquisition and fee processing. MCP Consumer Sometimes, it’s embedded in a bunch software, permitting customers to work together with the server by way of the interface. Nonetheless, there’s the pliability to develop customized MCP shoppers with specialised use circumstances and necessities, resembling constructing easy AI internet apps utilizing Streamlit to help extra front-end options.

MCP Server Elements

This text focuses on understanding MCP servers and applies information to construct a easy, customized MCP server. The MCP server envelops varied API calls to exterior instruments and assets, permitting shoppers to entry these options with out worrying about further setups. The MCP server helps incorporating three completely different elements tailor-made to 3 frequent LLM customization methods:

• useful resource Information, information and paperwork that act as an exterior information base to complement present LLM information. That is particularly helpful for RAG-based techniques.
• software For instance, it’s integration with different packages for performing Google searches and creating GIGMA prototypes that may be leveraged on agent-based techniques, and is built-in with different packages.
• immediate A predefined instruction template to information the output of LLM, resembling responses in skilled or informal tones. That is helpful in techniques that profit from speedy engineering methods.

If you wish to be taught extra about LLM customization methods, take a look at my earlier article and video on “Merely explaining six frequent LLM customization methods.”

https://www.youtube.com/watch?v=jflqodtb1fg

---

Construct an MCP server in 6 steps

Utilizing a easy instance, we present tips on how to construct your first MCP server utilizing Python. This lets you invoke customized visualize_code A software that turns uncooked code information extracted from GitHub repository into visible diagrams like the next instance.

For folks with information science background studying to construct MCP servers, there are some unfamiliar however necessary software program growth ideas, resembling asynchronous programming to deal with asynchronous operations, shopper/server structure, and Python decorators to switch useful conduct. As we proceed by way of this sensible instance, we are going to clarify these ideas in additional element.

Step 1. Organising your atmosphere

• Package deal Supervisor Setup: Utilized by MCP uv Because the default package deal supervisor. For MacOS and Linux techniques, set up it uv Use to run sh With shell command:

• Begin a brand new working listing /visibleactivate the digital atmosphere, create a undertaking construction and save the principle script visible.py:

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

# Create digital atmosphere 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 the required dependencies: pip set up mcp httpx fastapi uvicorn

Learn extra:

Official weblog submit from humanity:For Server Developers – Model Context Protocol“Supplies a easy information to organising your MCP server growth atmosphere.

Step 2: Primary Server Setup

in visible.py Outline a consumer agent to import scripts, the required libraries, begin an MCP server occasion, and make HTTP requests. I will use it 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 a helper perform

Create a helper perform get_code() To get the code from a 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 = {
        "Person-Agent": USER_AGENT,
        "Settle for": "textual content/html"
    }
    
    async with httpx.AsyncClient() as shopper:
        strive:
            # Convert GitHub URL to uncooked content material URL
            raw_url = url.change("github.com", "uncooked.githubusercontent.com")
                        .change("/blob/", "/")
            response = await shopper.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 disassemble get_code() It really works for a number of elements.

Asynchronous implementation

Asynchronous programming permits a number of operations to be carried out concurrently, rising effectivity by not blocking execution whereas ready for an operation to finish. It’s sometimes used to effectively deal with I/O operations resembling community requests, consumer enter, and API calls. In distinction, synchronous operations sometimes used for machine studying duties are carried out sequentially till every operation is blocked earlier than transferring to the subsequent job. To outline this perform asynchronously, the next adjustments are made:

• The perform is said with async def Permits a number of operations to be processed concurrently.
• use async with With the context supervisor httpx.AsyncClient() For non-blocking HTTP requests.
• Add to deal with asynchronous HTTP requests await key phrase shopper.get().

URL Processing

Accepts headers for HTML content material and configures the suitable consumer agent to establish the shopper that may make the HTTP request. visual-fastmcp/0.1 . Converts common Github URLs to RAW file format.

Error Dealing with

Catches HTTP-specific exceptions (httpx.RequestError, httpx.HTTPStatusError) and catches different frequent exception dealing with as fallbacks and returns a written error message for debugging.

Learn extra:

Step 4: Implement the MCP Server Instrument

I’ve now been capable of create the principle MCP server software with some further code visualize_code().

@mcp.software()
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 a part of(code)
    return "n".be a part of(visualization)

Decorator

Python decorator is a particular characteristic Modify or improve the conduct of one other characteristic or methodology With out modifying the unique code. FASTMCP supplies a decorator that wraps customized features and integrates them into an MCP server. For instance, use @mcp.software() Beautify and create an MCP server software visualize_code perform. Equally, it may be used @mcp.useful resource() Sources and @mcp.immediate() For prompts.

Enter your suggestions and docus strings

The FASTMCP class leverages Python kind hints and docustrations to mechanically improve software definitions and simplifies the creation and upkeep of MCP instruments. To be used circumstances, create software features utilizing kind hints visualize_code(url: str) -> straccepts enter parameters url Makes use of string format to generate the output as a mixed string of all code extracted from the supply file. Subsequent, add the next Docstring to assist LLM perceive tips on how to use the software:

    """
    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 MCP instruments work with and with out offering DocString by invoking the MCP server by way of the Claude desktop.

Mannequin output with out docustring – generates solely a abstract of the textual content

Mannequin output supplied with Docstring – generates each textual content overview and diagram

Learn extra:

Step 5: Configure the MCP server

Add the principle execution block because the final step visible.py script. Use “stdio” to run the server regionally on a easy I/O transport. Whenever you run code in your native machine, the MCP server is positioned on the native machine and listens for software requests from the MCP shopper. For manufacturing deployments, varied transport choices could be configured, resembling “Streamable-HTTP” for web-based deployments.

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

Step 6. Use MCP server from Claude desktop

This is tips on how to use this MCP server by way of the Claude desktop, however please word that by barely tweaking the configuration, the server could be linked to a unique host (e.g. cursor). Take a look at”For Claude Desktop Users – Model Context Protocol“For Claude’s official information.

1. Please obtain Claude Desktop
2. Set the configuration file for server settings in a neighborhood folder ~/Library/Software Assist/Claude/claude_desktop_config.json (For macos) and updates <PARENT_FOLDER_ABSOLUTE_PATH> In your working folder path.

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

3. Run utilizing the command line uv --directory <PARENT_FOLDER_ABSOLUTE_PATH>/visible run visible.py
4. Launch (or restart) the Claude desktop, choose Search and Instruments, then choose Visible. It’s best to be capable to change with visualize_code A software that I simply created.

5. For instance, check out the visualization software by offering a GitHub URL.

---

Take-out message

This text supplies an outline of the MCP structure (MCP shoppers, hosts, servers) that focuses totally on MCP server elements and purposes. It guides you thru the method of constructing a customized MCP server that permits deargrams from code from GitHub repository.

Necessary steps to constructing a customized MCP server:

1. Organising your atmosphere
2. Primary server setup
3. Create a helper perform
4. Implement the MCP software
5. Configure the MCP server
6. Use an MCP server from Claude Desktop

If you’re thinking about additional investigation, potential instructions embrace exploring distant MCP servers for cloud suppliers, implementing safety features, and strong error dealing with.

Extra content material like this

https://www.youtube.com/watch?v=jflqodtb1fg