Mannequin Context Protocol (MCP) Tutorial: Construct Your First MCP Server in 6 Steps

Context Protocol (MCP)?

On account of the emergence of AI brokers and RAG-based purposes lately, there’s an rising demand for customizing Giant Language Fashions (LLMs) by integrating with exterior assets (e.g. RAG-based methods) and instruments (e.g. Agent-based methods). This enhances LLMs’ current capabilities by incorporating exterior information and enabling autonomous activity execution.

Mannequin Context Protocol (MCP), first launched in November 2024 by Anthropic, has grown in recognition because it affords a extra coherent and constant option to join LLMs with exterior instruments and assets, 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 assets, therefore permit finish customers to MCP server that has been encapsulated with enhanced functionalities. In comparison with present agentic system design patterns, MCP affords a number of key advantages:

Constructing Analysis Brokers for Tech Insights

5 Key Methods LLMs Can Supercharge Your Machine Studying Workflow

Enhance scalability and maintainability of the system via standardized integrations.
Scale 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 change between LLM suppliers, because the LLM is not tightly coupled with the agentic system.
Velocity up the event course of considerably by enabling speedy creation of workable merchandise.

This text is intention for guiding you thru the basics of Mannequin Context Protocol and the important parts of constructing an MCP server. We are going to apply these ideas via 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 beneath.

Person Enter:

https://github.com/aws-samples/aws-cdk-examples/blob/predominant/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 utility that requests companies supplied by a centralized server. A useful analogy for the client-server relationship is that of a buyer and a restaurant. The shopper acts just like the client-side, sending requests by ordering from the menu, whereas the restaurant resembles the server, offering companies like dishes and seatings. The restaurant possesses ample assets 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 affords instruments and assets, exposing functionalities that AI fashions can leverage via structured requests. MCP host affords the runtime atmosphere that manages communication between shoppers and servers, corresponding to Claude Desktop or IDEs with MCP-supported extensions. If we proceed with the identical customer-restaurant analogy above, MCP host may be thought-about as a restaurant administration system that coordinates communications between clients (shoppers) and eating places, handles order taking and cost processing. MCP consumer is often constructed into the host utility permitting the customers to work together with the server via an interface. Nevertheless, there’s the flexibleness of creating customized MCP shoppers for specialised use circumstances and necessities, corresponding 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 information to construct a easy, customized MCP server. MCP server wraps round numerous APIs calls to the exterior instruments and assets, enabling the shoppers accessing these functionalities with out worrying in regards to the further setup. The MCP server helps incorporating three varieties of parts which aligns with three widespread LLM customization methods.

Assets are information, recordsdata and paperwork that function the exterior information base to complement LLM’s current information. That is notably 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 many others, which may 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.

In case you are to know extra about LLM customization methods, try my earlier article and video on “6 Frequent LLM Customization Methods Briefly Defined”.

Construct Your MCP Server in 6 Steps

We are going to use a easy instance to exhibit easy methods 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 necessary to grasp: asynchronous programming for dealing with asynchronous operations, consumer/server structure, and Python decorators for modifying perform habits. We are going to clarify these ideas in additional element as we stroll via this sensible instance.

Step 1. Setting Setup

Bundle managers setup: MCP makes use of uv because the default package deal 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 atmosphere, create the venture construction to retailer the primary script visible.py:

# Create a brand new listing for our venture
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 required dependencies: pip set up mcp httpx fastapi uvicorn

Additional Studying:

The official weblog publish from Anthropic “For Server Builders – Mannequin Context Protocol” gives easy-to-follow information for establishing the MCP server growth atmosphere.

Step 2: Fundamental 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 are going to 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 Capabilities

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 = {
        "Person-Agent": USER_AGENT,
        "Settle for": "textual content/html"
    }
    
    async with httpx.AsyncClient() as consumer:
        attempt:
            # Convert GitHub URL to uncooked content material URL
            raw_url = url.exchange("github.com", "uncooked.githubusercontent.com")
                        .exchange("/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 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, corresponding to community request, consumer 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 shifting to the subsequent activity. The next adjustments are made to outline this perform asynchronously:

The perform 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 consumer.get().

URL Processing

Configure Settle for header for HTML content material and set applicable Person-Agent to determine 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 Device

Utilizing just a few further strains of code, we are able to now create our predominant 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 perform that modifies or enhances the habits of one other perform or methodology with out altering its authentic code. FastMCP gives decorators that wrap round customized capabilities to combine them into the MCP server. For instance, we use @mcp.device() to create an MCP server device by adorning the visualize_code perform. Equally, we are able to use @mcp.useful resource() for assets and @mcp.immediate() for prompts.

Sort Trace and Docstring

The FastMCP class leverages Python sort hints and docstrings to mechanically enhancing device definitions, simplifying the creation and upkeep of MCP instruments. For our use case, we create device 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 beneath 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 capabilities with and with out docstring supplied, by calling the MCP server via 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 primary execution block because the final step within the visible.py script. Run the server domestically with easy I/O transport utilizing “stdio”. When operating 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’ll be able to 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 are going to exhibit easy methods to use this MCP server via 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 Customers – Mannequin Context Protocol” for Claude’s official information.

Obtain the Claude Desktop
Arrange config file for server settings in your native folder ~/Library/Software Help/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"
            ]
        }
    }
}

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

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

Take-House Message

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

Important steps for constructing a customized MCP server:

Setting Setup
Fundamental Server Setup
Create Helper Capabilities
Implemente the MCP Device
Configure the MCP Server
Use the MCP Server from Claude Desktop

In case you are focused on additional exploration, potential instructions embody exploring distant MCP servers on cloud supplier, implementing safety features and strong error dealing with.