Model Context Protocol (MCP) Learning Project

📚 Overview

This project demonstrates the implementation and usage of the Model Context Protocol (MCP) with various tools and servers. MCP is a standardized protocol that allows AI models to securely connect to and interact with external tools and data sources.

🎯 Learning Objectives

By working through this project, you will learn:

• How to create MCP servers that expose tools to AI models
• How to build MCP clients that can connect to and use multiple servers
• How to implement tool-calling functionality with AI models
• How to structure a multi-server MCP architecture
• How to handle local vs remote MCP server connections

📁 Project Structure

MCP/
├── 📄 README.md                     # This documentation file
├── 📄 server_config.json           # Configuration for multiple MCP servers
├── 📄 SECURITY.md                  # Security guidelines and API safety
│
├── 🤖 Chatbot Implementations
│   ├── chatbot.ipynb              # Original notebook-based chatbot
│   ├── mcp_chatbot.py             # Single MCP server client
│   ├── mcp_many_server_chatbot.py # Multi-server MCP client
│   └── chatbot_client.py          # Alternative client implementation
│
├── 🔧 Server Implementations
│   ├── mcp_server_tool_creation.py # Basic MCP server creation
│   ├── create_server.py           # Server creation utilities
│   └── mcp_project_far/           # Research paper tools server
│       ├── research_server.py     # Local MCP server
│       ├── remote_research_server.py # Remote MCP server
│       └── papers/               # Stored research data
│
└── 📊 Data Storage
    └── papers/                   # Research papers database
        ├── computers/
        ├── mathematics/
        ├── physics/
        └── quantum_physics/

🚀 Getting Started

Prerequisites

# Required Python packages
pip install anthropic
pip install arxiv
pip install fastmcp
pip install python-dotenv

# Required Node.js packages (for MCP Inspector)
npx @modelcontextprotocol/inspectorcd C:/Users/ffarh/OneDrive/Desktop/MCP
python -m venv venv
source venv/Scripts/activate
pip install arxiv mcp anthropic python-dotenvcd C:/Users/ffarh/OneDrive/Desktop/MCP
python -m venv venv
source venv/Scripts/activate
pip install arxiv mcp anthropic python-dotenvcd C:/Users/ffarh/OneDrive/Desktop/MCP
python -m venv venv
source venv/Scripts/activate
pip install arxiv mcp anthropic python-dotenv

Environment Setup

1. Create a .env file in your project root:

ANTHROPIC_API_KEY=your_anthropic_api_key_here
# Add other API keys as needed

2. Activate your virtual environment:

source venv/Scripts/activate  # Windows
# or
source venv/bin/activate      # Linux/Mac

📖 Core Concepts

1. What is MCP?

Model Context Protocol (MCP) is a standardized way for AI models to:

• Connect to external tools and services
• Execute functions safely and reliably
• Exchange data in a structured format
• Scale across multiple tool providers

2. MCP Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Model      │    │   MCP Client    │    │   MCP Server    │
│   (Claude)      │◄──►│   (Your App)    │◄──►│   (Tools)       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

• AI Model: The language model (e.g., Claude) that needs tools
• MCP Client: Your application that manages tool connections
• MCP Server: Services that expose tools via MCP protocol

3. Transport Methods

Local (stdio)

# Direct process communication
server_config = {
    "command": "python",
    "args": ["server.py"]
}

Remote (SSE - Server-Sent Events)

# HTTP-based communication
server_url = "http://localhost:8001/sse"

🛠️ Implementation Examples

1. Basic MCP Server (mcp_server_tool_creation.py)

from mcp.server.fastmcp import FastMCP

# Initialize MCP server
mcp = FastMCP("my_server")

@mcp.tool()
def my_function(param: str) -> str:
    """Tool description for the AI model"""
    return f"Result: {param}"

if __name__ == "__main__":
    mcp.run()

Key Concepts:

• @mcp.tool() decorator exposes functions as tools
• Function docstrings become tool descriptions
• Type hints help with parameter validation

2. Research Paper Server (remote_research_server.py)

This server provides tools for:

• Searching arXiv papers by topic
• Extracting paper information by ID
• Storing results in JSON format

@mcp.tool()
def search_papers(topic: str, max_results: int = 5) -> List[str]:
    """Search for papers on arXiv based on a topic"""
    # Implementation details...
    
@mcp.tool()
def extract_info(paper_id: str) -> str:
    """Get detailed information about a specific paper"""
    # Implementation details...

3. Multi-Server Client (mcp_many_server_chatbot.py)

This client can connect to multiple MCP servers simultaneously:

class MCPChatbot:
    def __init__(self):
        self.servers = {}
        self.available_tools = []
        
    async def connect_to_servers(self):
        """Connect to all configured MCP servers"""
        for server_name, config in server_configs.items():
            # Connect to each server
            # Collect available tools

Benefits:

• Access tools from multiple sources
• Centralized tool management
• Scalable architecture

🔧 Running the Project

Option 1: Single Server Setup

1. Start the research server:

cd mcp_project_far
python remote_research_server.py

2. Run the MCP Inspector (in another terminal):

npx @modelcontextprotocol/inspector

3. Connect via Inspector:
   • URL: http://localhost:8001/sse
   • Transport: SSE
   • Connection: Via Proxy

Option 2: Multi-Server Setup

1. Configure servers in server_config.json
2. Run the multi-server client:

python mcp_many_server_chatbot.py

🎛️ Configuration Files

server_config.json

{
  "mcpServers": {
    "far_research_assistant": {
      "command": "python",
      "args": ["mcp_project_far/research_server.py"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }
  }
}

Configuration Options:

• command: Executable to run the server
• args: Arguments passed to the command
• env: Environment variables (if needed)

🔍 Tool Examples

Research Tools

# Search for papers
search_papers("machine learning", max_results=3)
# Returns: ["paper_id_1", "paper_id_2", "paper_id_3"]

# Get paper details
extract_info("2301.07041")
# Returns: JSON with title, authors, summary, etc.

Filesystem Tools

# Read file
read_file("/path/to/file.txt")

# Write file
write_file("/path/to/output.txt", "content")

# List directory
list_directory("/path/to/directory")

🚨 Security Considerations

API Key Management

• ✅ DO: Use environment variables for API keys
• ✅ DO: Use .env files that are gitignored
• ❌ DON'T: Hardcode API keys in source code
• ❌ DON'T: Commit API keys to version control

Example Safe Implementation:

from dotenv import load_dotenv
import os

load_dotenv()
client = Anthropic()  # Reads from ANTHROPIC_API_KEY env var

File Access Security

• MCP servers should validate file paths
• Restrict access to specific directories
• Validate user inputs to prevent path traversal

🐛 Troubleshooting

Common Issues

1. "Connection failed" Error

# Check if server is running
python remote_research_server.py

# Verify the port is correct
netstat -an | findstr 8001

2. "404 Not Found" from MCP Server

• Ensure the server exposes MCP endpoints (usually /sse)
• Try different transport methods (stdio vs SSE)
• Check server logs for errors

3. "Tool not found" Error

• Verify tool registration with @mcp.tool() decorator
• Check tool name spelling in client calls
• Ensure server is properly connected

4. Import Errors

# Install missing packages
pip install anthropic arxiv fastmcp python-dotenv

# Verify virtual environment is activated
which python

📈 Advanced Topics

Custom Tool Schemas

@mcp.tool()
def advanced_search(
    query: str,
    filters: Dict[str, Any],
    sort_by: Literal["relevance", "date"] = "relevance"
) -> Dict[str, Any]:
    """Advanced search with complex parameters"""
    pass

Error Handling

@mcp.tool()
def robust_function(param: str) -> str:
    try:
        # Tool logic here
        return result
    except Exception as e:
        return f"Error: {str(e)}"

Async Tools

@mcp.tool()
async def async_function(param: str) -> str:
    """Asynchronous tool execution"""
    result = await some_async_operation(param)
    return result

🎓 Learning Path

Beginner Level

1. Start with chatbot.ipynb to understand basic concepts
2. Run mcp_server_tool_creation.py to create your first server
3. Use MCP Inspector to test your tools

Intermediate Level

1. Study mcp_chatbot.py for single-server client implementation
2. Create custom tools for your specific use case
3. Learn about different transport methods

Advanced Level

1. Implement mcp_many_server_chatbot.py for multi-server architecture
2. Create production-ready error handling and logging
3. Deploy servers remotely and manage authentication

📚 Additional Resources

• MCP Official Documentation
• FastMCP Framework
• Anthropic Tool Use Guide

🤝 Contributing

This is a learning project. Feel free to:

• Add new tools and servers
• Improve error handling
• Enhance documentation
• Share your implementations

📄 License

This project is for educational purposes. Please respect API terms of service and rate limits when using external services.

---

This documentation is part of a comprehensive MCP learning project. Each file in this directory serves a specific educational purpose and demonstrates different aspects of MCP implementation.