Building an Agent with MCP: Seamless Integration of AI and External Resources

Introduction

Model Context Protocol (MCP) is an open protocol designed to standardize how applications provide context to large language models (LLMs). Think of MCP like a USB-C port for AI applications - just as USB-C provides a standardized way to connect devices to various peripherals, MCP provides a standardized way to connect AI models to different data sources and tools.

This tutorial will guide you through implementing MCP in your AI agent applications, demonstrating how it can enhance your agents' capabilities by providing seamless access to external resources, tools, and data sources.

Why MCP Matters for Agents

Traditional methods of connecting AI models with external resources often involve custom integrations for each data source or tool. This leads to:

• Integration Complexity: Each new data source requires a unique implementation
• Scalability Issues: Adding new tools becomes progressively harder
• Maintenance Overhead: Updates to one integration may break others

MCP solves these challenges by providing a standardized protocol that enables:

• Unified Access: A single interface for multiple data sources and tools
• Plug-and-Play Extensions: Easy addition of new capabilities
• Stateful Communication: Real-time, two-way communication between AI and resources
• Dynamic Discovery: AI can find and use new tools on the fly

Here's a concise paragraph highlighting the official MCP Server examples:

Official MCP Server Examples

The MCP community maintains a collection of reference server implementations that showcase best practices and demonstrate various integration patterns. These official examples, available at MCP Servers, provide valuable starting points for developers looking to create their own MCP servers.

What We'll Build

In this tutorial, we'll implement:

1. Build Your MCP Servers and Use It: Build a MCP server with customized tools and connect to Claude Desktop
2. Customized Tool-Enabled Agent: Create an customized agent that can use external tools via MCP

By the end of this tutorial, you'll understand how MCP can enhance your AI agents by providing them with access to the broader digital ecosystem, making them more capable, context-aware, and useful.

Let's begin by understanding the MCP architecture and setting up our environment!

📖 For more background on the Model Context Protocol (MCP) and its applications, check out our detailed blog post: Model Context Protocol (MCP) explained

DiamantAI is a top 0.1% newsletter for AI with over 25,000 subscribers, focusing on AI techniques, breakthroughs, and tutorials.

MCP Architecture Overview

MCP follows a client-server architecture with three main components:

• Host: The AI application (like Claude Desktop, Cursor or a customized agent) that needs access to external resources
• Clients: Connectors that maintain connections with servers
• Servers: Lightweight programs that expose capabilities (data, tools, prompts) via the MCP protocol
• Data Sources: Both local (files, databases) and remote services (APIs) that MCP servers can access

Communication within MCP uses JSON-RPC 2.0 over WebSocket connections, ensuring real-time, bidirectional communication between components.

Experiencing MCP: Try Before You Build

While this tutorial focuses on building your own MCP servers and integrating them with AI agents, you might want to quickly experience how MCP works in practice before diving into development.

The official MCP documentation provides an excellent quick start guide for users who want to try existing MCP servers with Claude Desktop or other compatible AI applications. This gives you a hands-on feel for the capabilities MCP enables without writing any code.

👉 Try it yourself: MCP Quick Start Guide for Users

By exploring the quick start guide, you'll gain practical insight into what we're building in this tutorial. When you're ready to understand the inner workings and create your own implementations, continue with our step-by-step development process below.

Now, let's start building our own MCP server and client!

Building Your MCP Server

Now that we understand the basics of MCP, let's build our first MCP server! In this section, we'll create a cryptocurrency price lookup service using the CoinGecko API. Our server will provide tools that allow an AI to check the current price or market data of cryptocurrencies.

Setting Up Our Environment

Before we dive into implementation, let's install the necessary packages and set up our environment.

Note: For the installation steps, please open a terminal window. These commands should be run in a regular terminal, not in a Jupyter notebook cell.

Step 1: Install uv Package Manager

# Run this in your terminal, not in Jupyter
curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Set up the Project

# Create and navigate to a project directory
mkdir mcp-crypto-server
cd mcp-crypto-server
uv init

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv add "mcp[cli]" httpx

Running the MCP Server

After we set up the envirnment, we can start build our tools.

Please checkout mcp_server.py to see how to build tools.

now we can start the server by runnning following commands in the ternimal:

# Copy the server file from the scripts folder
cp ../scripts/mcp_server.py .

# Start the MCP server 
uv run mcp_server.py

Integration with Claude Desktop

If you haven't download Claude Desktop, checkout this page.

To connect your MCP server to Claude Desktop:

Step 1: Find the absolute path to your uv command:

which uv

Copy the output (e.g., /user/local/bin/uv or similar)

Step 2: Create or edit the Claude Desktop configuration file:

• On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• On Windows: %APPDATA%\Claude\claude_desktop_config.json
• On Linux: ~/.config/Claude/claude_desktop_config.json

You can checkout this page to see how to create a config file.

Step 3: Add your MCP server configuration:

{
    "mcpServers": {
        "crypto-price-tracker": {
            "command": "/ABSOLUTE/PATH/TO/uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/GenAI_Agents/all_agents_tutorials/mcp-crypto-server",
                "run",
                "mcp_server.py"
            ]
        }
    }
}

Replace /ABSOLUTE/PATH/TO/uv with the path you got from the which uv command, and /ABSOLUTE/PATH/TO/GenAI_Agents with the absolute path to your repository.

Step 4: Restart Claude Desktop for the changes to take effect.

You should see this hammer in your chat box.

Step 5: Try ask the price of Bitcoin

Type in "What is the current price of Bitcoin ?", and you will get response like:

Congrats! You've successfully apply your MCP server and tool. Now, you can try add your own tools to mcp_server.py. Here is an example:

@mcp.tool()
async def get_crypto_market_info(crypto_ids: str, currency: str = "usd") -> str:
    """
    Get market information for one or more cryptocurrencies.
    
    Parameters:
    - crypto_ids: Comma-separated list of cryptocurrency IDs (e.g., 'bitcoin,ethereum')
    - currency: The currency to display values in (default: 'usd')
    
    Returns:
    - Market information including price, market cap, volume, and price changes
    """
    # Construct the API URL
    url = f"{COINGECKO_BASE_URL}/coins/markets"
    
    # Set up the query parameters
    params = {
        "vs_currency": currency,  # Currency to display values in
        "ids": crypto_ids,        # Comma-separated crypto IDs
        "order": "market_cap_desc", # Order by market cap
        "page": 1,                # Page number
        "sparkline": "false"      # Exclude sparkline data
    }
    
    try:
        # Make the API call
        async with httpx.AsyncClient() as client:
            response = await client.get(url, params=params)
            response.raise_for_status()
            
            # Parse the response
            data = response.json()
            
            # Check if we got any data
            if not data:
                return f"No data found for cryptocurrencies: '{crypto_ids}'. Please check the IDs and try again."
            
            # Format the results
            result = ""
            for crypto in data:
                name = crypto.get('name', 'Unknown')
                symbol = crypto.get('symbol', '???').upper()
                price = crypto.get('current_price', 'Unknown')
                market_cap = crypto.get('market_cap', 'Unknown')
                volume = crypto.get('total_volume', 'Unknown')
                price_change = crypto.get('price_change_percentage_24h', 'Unknown')
                
                result += f"{name} ({symbol}):\n"
                result += f"Current price: {price} {currency.upper()}\n"
                result += f"Market cap: {market_cap} {currency.upper()}\n"
                result += f"24h trading volume: {volume} {currency.upper()}\n"
                result += f"24h price change: {price_change}%\n\n"
            
            return result
            
    except Exception as e:
        return f"Error fetching market data: {str(e)}"

Rerun your mcp server with uv run mcp_server.py, restart Claude Desktop, and type "What's the market data for Dogecoin and Solana?". You will get the response like this:

Customized Agent executing tool via MCP

After we build our own MCP, let's try building MCP Host & Client ourselves.

Understanding the Architecture

In this section, we'll build our own MCP Host and Client. Unlike the previous approach where we connected to Claude Desktop, we'll now create our own agent that can:

1. Act as an MCP Host
2. Discover available tools from our MCP server
3. Understand when to use which tool based on user queries
4. Execute tools with appropriate parameters
5. Process tool results to provide helpful responses

This architecture follows a pattern common in modern AI systems:

• Discovery Phase: Our custom host discovers what tools are available
• Planning Phase: The agent decides which tool to use based on the user's query
• Execution Phase: Our client connects to the server and executes the selected tool
• Interpretation Phase: The agent explains the results in natural language

Here is a simple worflow diagram:

Important Reminder Before Running the Code: ⚠️ Don't forget to start your MCP server first! ⚠️ Before running the agent code in following tutorial, make sure your MCP server is up and running. Otherwise, your agent won't have any tools to discover or execute.

Let's start by setting up our environment and importing the necessary libraries:

We need two primary libraries:

• MCP: To handle the client-server communication with our MCP server, allowing us to build both the host and client components
• Anthropic: To interact with Claude, which will power our agent's reasoning capabilities

Now, let's set up the necessary imports and configurations for our agent:

We're using the stdio_client interface from MCP, which allows us to connect to MCP servers that run as separate processes and communicate via standard input/output. This is a simple and robust approach for local development. By implementing both sides of the MCP protocol (host and client), we gain complete control over how our agent interacts with MCP tools.

Tool Discovery: Building Our MCP Host

The first step in building our custom MCP implementation is to create a host that can discover what tools are available from our MCP server. Our host will act as the intermediary between the user, the AI, and the available tools - similar to how Claude Desktop functions, but under our complete control.

Let's implement a function to connect to our MCP server and discover its tools:

This function acts as our host's discovery component:

1. Creates Server Parameters: Configures how to launch and connect to the MCP server
2. Establishes Connection: Uses stdio_client to create a communication channel
3. Initializes Session: Sets up the MCP session using the communication channel
4. Discovers Tools: Calls list_tools() to get all available tools
5. Formats Results: Converts the tools into a more usable format for our agent

We're using an asynchronous approach (async/await) because MCP operations are non-blocking by design. This is important in a host implementation, as it allows our agent to handle multiple operations concurrently and remain responsive even when waiting for tool operations to complete.

Let's test our tool discovery function to make sure it works properly:

When we run this code, we should see a list of the tools available from our MCP server. In this case, we're expecting to see our cryptocurrency tools.

Tool Execution: Implementing Our MCP Client

Now that our host can discover available tools, we need to implement the client component that can execute them. Unlike third-party tools that might have this functionality built-in, we're creating our own client to execute MCP tools with complete control and transparency:

This function forms the core of our MCP client:

1. Connects to Server: Similar to our discovery function, it establishes a connection to the MCP server
2. Executes Tool: Calls the specified tool with the provided arguments
3. Returns Result: Gives back whatever the tool returns

Notice that for each tool execution, we create a new connection to the MCP server. While this may seem inefficient, it ensures clean separation between tool calls and avoids potential state issues. This stateless approach simplifies our implementation and makes it more robust. In a production system, you might optimize this by maintaining a persistent connection, but the current approach is excellent for educational purposes as it clearly separates each step in the process.

Now that we have functions to discover and execute tools, we need to integrate these with an AI that can determine when and how to use them. This is where Claude comes in.

Integrating AI with Our MCP Implementation

With our host and client components in place, we now need to integrate them with an AI system that can make intelligent decisions about tool usage. This is the "brains" of our custom MCP host, and it needs to:

1. Understand when a tool is needed based on user input
2. Choose the appropriate tool for the task
3. Format the arguments correctly
4. Process and explain the results

Let's implement a function that orchestrates this entire process:

This function completes our custom MCP host implementation with a sophisticated reasoning and execution flow:

1. Tool Description: We format the tool information in a way Claude can understand
2. System Prompt: We provide instructions on when and how to use tools
3. Response Analysis: We look for JSON tool requests in Claude's responses
4. Tool Execution: If a tool request is detected, we use our client to execute the appropriate tool
5. Result Processing: We send the tool results back to Claude for interpretation
6. Conversation Management: We maintain context by tracking messages

This creates a powerful synergy: Claude provides the reasoning and communication skills, while our MCP tools provide specialized capabilities and real-time data access.

Let's test our agent with a simple query about Bitcoin prices:

When we run this query, our complete MCP implementation follows this flow:

1. Claude (via our host) recognizes this as a request about Bitcoin prices
2. Our AI decides to use the get_crypto_price tool
3. It formats the arguments correctly (using "bitcoin" as the crypto_id)
4. Our client connects to the server and executes the tool, returning the current Bitcoin price
5. Claude explains the result in natural language with additional context

This demonstrates the full capability of our agent: understanding the user's intent, selecting the appropriate tool, executing it correctly, and providing a helpful, context-rich response.

Direct Tool Execution via Our Client

While our integrated MCP host typically decides which tools to use based on the user's query, sometimes we might want to directly use our client to execute a specific tool. This is useful for testing our client implementation or demonstrating specific tool functionality. Let's create a simple example:

This direct execution approach is useful for:

• Testing our client implementation in isolation
• Debugging tool functionality
• Building specialized workflows where tool execution is predetermined
• Verifying that our MCP client works correctly before integrating it with the AI

Now, let's create an interactive chat interface that uses our complete MCP host implementation:

Building an Interactive MCP Host Interface

For a complete MCP host implementation, we need a user interface that maintains context across multiple turns of conversation. This allows our host to remember previous interactions and build on them in subsequent exchanges, just like professional MCP hosts such as Claude Desktop. Let's implement a simple chat session function:

Our MCP host interface:

1. Initializes Tools: Our host discovers available tools when starting
2. Creates a Session Loop: Continuously prompts for user input
3. Maintains Context: Passes previous messages to each query, maintaining stateful conversations
4. Handles Graceful Exit: Allows the user to end the session gracefully

This creates a natural, conversational experience where the agent can remember previous interactions. For example, if a user asks about Bitcoin and then follows up with "How about Ethereum?", the agent understands the context.

Now, let's run our chat session to see the complete agent in action:

You may try what we ask in Clude Desktop: What's the market data for Dogecoin and Solana?

With this final piece, we've created a complete custom MCP host implementation that can:

1. Connect to an MCP server as a client
2. Discover available tools
3. Intelligently select and use those tools to answer user queries
4. Maintain context across a conversation

This demonstrates the power of implementing our own MCP host and client - we get complete control over how AI interacts with tools while maintaining all the benefits of the MCP protocol's standardization.

Conclusion:

The Model Context Protocol represents a transformative approach to integrating AI models with external resources, solving critical challenges in AI application development:

Protocol Advantages

• Standardized Integration: Eliminates complex, custom API connections
• Dynamic Tool Discovery: Enables AI to find and use tools seamlessly
• Flexible Communication: Supports real-time, bidirectional interactions

Technical Highlights

Our implementation demonstrated:

• Building MCP server with specialized tools
• Creating a host that can dynamically discover and execute tools
• Integrating AI model with external resources

Key Citations

• Python MCP SDK
• MCP Quick Start Guide
• CoinGecko API Documentation