MCP Demo Project 🚀

A minimal demonstration of the Model Context Protocol (MCP) using Python. This project shows how to:

• Create an MCP server that exposes a calculator tool
• Build a client that uses OpenAI's gpt-4o-mini to intelligently call the tool
• Demonstrate model-driven tool calling through MCP

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It enables AI models to securely access tools, data sources, and services through a unified interface.

Project Structure

mcp-demo/
├── server.py          # MCP server with calculator tool
├── client.py          # Client that uses OpenAI to call the tool
├── requirements.txt   # Python dependencies
├── .env              # Your API keys (create this)
└── README.md         # This file

Features

✅ Simple Calculator Tool - Performs add, subtract, multiply, divide operations
✅ Proper JSON Schema - Well-defined input validation
✅ Structured Output - Clean, formatted results
✅ Lightweight Model - Uses OpenAI's gpt-4o-mini (fast & cost-effective)
✅ Natural Language - Ask questions in plain English
✅ Clean Code - Well-commented, easy to understand

Prerequisites

• Python 3.10 or higher
• OpenAI API key (get one at https://platform.openai.com/api-keys)

Installation

1. Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate  # On Windows

2. Install dependencies

pip install -r requirements.txt

3. Set up your OpenAI API key

Create a .env file in the project root:

echo "OPENAI_API_KEY=your-api-key-here" > .env

Or copy the example:

cp .env.example .env
# Then edit .env and add your actual API key

Usage

Running the Demo

The client automatically starts the server and runs a demo calculation:

python client.py

Expected Output

🚀 Starting MCP Client Demo
==================================================
✅ Connected to MCP server

📋 Available tools: 1
   • calculator: Perform basic arithmetic operations: add, subtract, multiply, divide

💬 User prompt: What is 156 multiplied by 27?

🤖 Asking OpenAI gpt-4o-mini to solve the problem...
✅ Model decided to use a tool!

🔧 Tool Call Details:
   Name: calculator
   Arguments: {'operation': 'multiply', 'a': 156, 'b': 27}

⚙️  Executing tool via MCP server...
✨ Tool Result:
   Result: 156 multiply 27 = 4212

🎯 Final Answer:
   156 multiplied by 27 equals 4212.

==================================================
✅ Demo completed successfully!

How It Works

1. MCP Server (server.py)

• Exposes a calculator tool via MCP protocol
• Defines a JSON schema for input validation
• Handles arithmetic operations: add, subtract, multiply, divide
• Returns structured results

2. Client (client.py)

1. Connects to the MCP server via stdio
2. Discovers available tools from the server
3. Sends a natural language prompt to OpenAI
4. OpenAI analyzes the prompt and decides to call the calculator tool
5. Client executes the tool via MCP
6. Returns the result to OpenAI for a natural language response

3. The Flow

User Question → OpenAI (gpt-4o-mini) → Tool Call Decision
                          ↓
                    MCP Client
                          ↓
                    MCP Server → Calculator Tool
                          ↓
                    Result → OpenAI → Natural Answer

Customization

Try Different Questions

Edit the user_prompt in client.py:

# Examples:
user_prompt = "What is 156 multiplied by 27?"
user_prompt = "Calculate 100 divided by 5"
user_prompt = "Add 45 and 67"
user_prompt = "What's 89 minus 23?"

Add More Tools

In server.py, add more tools to the list_tools() function:

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(name="calculator", ...),
        Tool(name="weather", ...),  # Add your new tool
    ]

Then handle them in call_tool():

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "calculator":
        # ... existing code
    elif name == "weather":
        # ... your new tool logic

Troubleshooting

"OPENAI_API_KEY not found"

• Make sure you created a .env file
• Verify it contains: OPENAI_API_KEY=sk-...

"Module not found" errors

• Activate your virtual environment
• Run pip install -r requirements.txt

"Connection refused" or server issues

• The client automatically starts the server
• Make sure server.py is in the same directory
• Check that Python is in your PATH

Architecture Details

MCP Protocol

• Transport: stdio (standard input/output)
• Format: JSON-RPC 2.0
• Tools: JSON Schema for validation

Model

• Provider: OpenAI
• Model: gpt-4o-mini
• Features: Function calling, tool use

Learn More

• MCP Documentation
• MCP Python SDK
• OpenAI Function Calling

License

MIT - Feel free to use this demo for learning and building your own MCP tools!

---

Happy Building! 🎉