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 functions in recent times, there’s an growing demand for customizing Giant 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 job execution.

Mannequin Context Protocol (MCP), first launched in November 2024 by Anthropic, has grown in reputation because it presents a extra coherent and constant method to join LLMs with exterior instruments and sources, making it a compelling different 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 presents a number of key advantages:

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

This text is purpose 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 a sensible instance of constructing a MCP server that permits 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 Elements

MCP Structure

MCP adopts a client-server structure the place the shopper is a tool or utility that requests providers supplied 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 prospects in a brief time period, whereas prospects solely want to fret about receiving their orders.

MCP structure consists of three parts: MCP server, MCP shopper and MCP host. MCP server presents instruments and sources, exposing functionalities that AI fashions can leverage by structured requests. MCP host presents the runtime surroundings that manages communication between shoppers and servers, similar 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 prospects (shoppers) and eating places, handles order taking and cost processing. MCP shopper is often constructed into the host utility permitting the customers to work together with the server by an interface. Nonetheless, there’s the flexibleness of creating customized MCP shoppers for specialised use instances and necessities, similar to constructing a easy AI net app utilizing Streamlit to help extra front-end functionalities.

MCP Server Elements

On this article, we’ll give attention to 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 shoppers accessing these functionalities with out worrying concerning the additional setup. The MCP server helps incorporating three sorts of parts which aligns with three frequent LLM customization methods.

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

If you’re to know extra about LLM customization methods, try 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 display the best way to construct your first MCP server utilizing Python, which allows calling a customized visualize_code device to show uncooked code recordsdata extracted from GitHub repositories into visible diagrams like the next instance.

For folks with information science background studying to construct MCP servers, there are a number of software program growth ideas that could be unfamiliar however vital to grasp: asynchronous programming for dealing with asynchronous operations, shopper/server structure, and Python decorators for modifying operate conduct. We’ll clarify these ideas in additional element as we stroll by this sensible instance.

Step 1. Setting Setup

• Package deal 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 surroundings, create the mission construction to retailer the principle script visible.py:

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

# Create digital surroundings 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 publish from Anthropic “For Server Developers – Model Context Protocol” gives easy-to-follow information for organising the MCP server growth surroundings.

Step 2: Fundamental Server Setup

Within the visible.py script, import the required libraries and provoke our MCP server occasion and outline a person 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 operate 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 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 break down the get_code() operate into just a few parts.

Asynchronous Implementation

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

• The operate is said 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 shopper.get().

URL Processing

Configure Settle for header for HTML content material and set acceptable Consumer-Agent to determine the shopper 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 Device

Utilizing just a few additional strains of code, we are able to now create our most important MCP server device visualize_code().

@mcp.device()
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

A Python Decorator is a particular operate that modifies or enhances the conduct of one other operate or technique with out altering its unique code. FastMCP gives decorators that wrap round customized features to combine them into the MCP server. For instance, we use @mcp.device() to create an MCP server device by adorning the visualize_code operate. 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 kind hints and docstrings to robotically enhancing device definitions, simplifying the creation and upkeep of MCP instruments. For our use case, we create device features with kind 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 grasp device 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 evaluate how the MCP device features with and with out docstring supplied, by calling the MCP server by 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 regionally with easy I/O transport utilizing “stdio”. When working the code in your native machine, the MCP server is positioned in your native machine and listening for device requests from MCP shoppers. For manufacturing deployment, you possibly can configure completely 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 display the best way to use this MCP server by Claude Desktop, nonetheless, please notice that it permits connecting the server to completely different hosts (e.g. Cursor) by barely tweaking the configuration. Try “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 individual 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 be capable to toggle on the visualize_code device we simply created.

5. Strive the visualization device by offering a GitHub URL, for instance:

Take-House Message

This text gives an outline of MCP structure (MCP shopper, host and server), with the first give attention to MCP server parts and functions. It guides by the method of constructing a customized MCP server that allows code-to-diagram from GitHub repositories.

Important steps for constructing a customized MCP server:

1. Setting Setup
2. Fundamental Server Setup
3. Create Helper Features
4. Implemente the MCP Device
5. Configure the MCP Server
6. Use the MCP Server from Claude Desktop

If you’re taken with additional exploration, potential instructions embrace exploring distant MCP servers on cloud supplier, implementing security measures and sturdy error dealing with.

Extra Contents Like This