MCP Tool Server

A lightweight Model Context Protocol (MCP) Tool Server built in Python that exposes real-world tools (weather, stock data, and internet search) over STDIO transport. The server is designed to be discovered and invoked by MCP-compatible clients and future AI agents, and is validated using the official MCP Inspector.

🚀 Overview

This project demonstrates how to build a correct and production-aligned MCP server that:

• Exposes reusable tools via MCP
• Integrates real external APIs
• Uses clear tool schemas and contracts
• Separates protocol logic from backend logic
• Can be directly consumed by AI agents in the future

The focus of this project is the tool layer, not agent reasoning. It intentionally stops at the MCP boundary.

🧠 Architecture & Approach

The design follows a clean separation of responsibilities:

MCP Client / Inspector
        │
        │  (STDIO)
        ▼
MCP Server (server/main.py)
        │
        ├── Tool Definitions (server/tools/)
        │       ├── Weather Tool
        │       ├── Stock Price Tool
        │       └── Web Search Tool
        │
        └── Backend Logic (server/backend/data_store.py)
                ├── OpenWeather API
                ├── Stooq Market Data
                └── Google Custom Search

• MCP Server handles protocol wiring and tool registration
• Tools define schemas and execution boundaries
• Backend layer contains all external API logic
• No agent logic is included (by design)

This mirrors how real AI platforms expose tools internally.

🛠️ Tools Implemented

🌦️ Weather Tool (get_weather)

• Fetches real-time weather data by city
• Powered by OpenWeatherMap
• Returns structured, agent-friendly JSON

📈 Stock Price Tool (get_stock_price)

• Retrieves stock market data for a given symbol
• Uses Stooq public market data (no API key required)
• Automatically normalizes symbols (e.g. AAPL → aapl.us)

🌐 Web Search Tool (web_search)

• Performs internet search using Google Custom Search
• Uses official Google APIs (no scraping)
• Returns clean search results with title, snippet, and link
• Result count is relevance-based and API-controlled

📂 Project Structure

TASK1-MCP-SERVER
│
│
├── server/
│   ├── main.py                  # MCP server entry point
│   │
│   ├── backend/
│   │   └── data_store.py         # External API integrations
│   │
│   ├── tools/
│   │   ├── get_weather.py
│   │   ├── get_stock_price.py
│   │   └── web_search.py
│
├── .env                          # API keys (not committed)
├── requirements.txt
└── README.md

⚙️ Prerequisites

• Python 3.10+
• Node.js (for MCP Inspector)
• OpenWeatherMap API key
• Google Custom Search API key + CSE ID

📦 Installation

# Clone repository
git clone <your-repo-url>
cd TASK1-MCP-SERVER

# Create virtual environment
python -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

🔐 Environment Configuration

Create a .env file in the project root:

OPENWEATHER_API_KEY=your_openweather_api_key
GOOGLE_API_KEY=your_google_api_key
GOOGLE_CSE_ID=your_custom_search_engine_id

Best practices:

• .env is excluded from version control
• No secrets are hardcoded
• Server fails safely if keys are missing

▶️ Running the MCP Server

Start the server using the MCP Inspector:

npx @modelcontextprotocol/inspector python server/main.py

The server runs over STDIO and exposes all tools automatically.

🧪 Testing with MCP Inspector

Using the Inspector UI:

1. Select STDIO transport
2. Point to server/main.py
3. Start the server
4. Invoke tools interactively

Example Tool Invocations

🌐 Web Search

Input:

{
  "query": "Model Context Protocol MCP",
  "num_results": 5
}

Output:

{
  "results": [
    {
      "title": "Model Context Protocol Documentation",
      "link": "https://modelcontextprotocol.io/",
      "snippet": "The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs..."
    },
    {
      "title": "Introducing the Model Context Protocol",
      "link": "https://anthropic.com/news/model-context-protocol",
      "snippet": "Today, we're introducing the Model Context Protocol (MCP), a new standard for connecting AI assistants..."
    }
  ]
}

🌦️ Weather Tool

Input:

{
  "city": "San Francisco"
}

Output:

{
  "city": "San Francisco",
  "temperature": 18.5,
  "conditions": "Clear sky",
  "humidity": 65,
  "wind_speed": 3.5
}

📈 Stock Price Tool

Input:

{
  "symbol": "AAPL"
}

Output:

{
  "symbol": "AAPL",
  "price": 195.89,
  "currency": "USD",
  "timestamp": "2024-01-15T16:00:00",
  "change": "+2.34",
  "change_percent": "+1.21%"
}

🚧 Why STDIO Transport?

STDIO was chosen because it provides the simplest, most reliable path for tool development and validation.

What STDIO Gives You

• Zero configuration: No ports, no networking, no HTTP servers to manage
• Perfect for inspection: MCP Inspector works flawlessly with STDIO
• Deterministic lifecycle: Process starts when called, exits when done
• Secure by default: No exposed endpoints or security concerns
• Easy debugging: Direct input/output makes testing and troubleshooting straightforward

Why Not HTTP/SSE?

While HTTP and Server-Sent Events (SSE) transports are valid MCP options, they introduce unnecessary complexity for a tool server:

HTTP Transport Issues:

• Requires managing a persistent web server alongside MCP logic
• Adds lifecycle complexity (when to start/stop, connection pooling, etc.)
• Makes local testing harder - you need HTTP clients, manage ports, handle CORS
• Overkill for simple tool execution that doesn't need persistent connections

SSE Transport Issues:

• Designed for streaming real-time updates, not one-shot tool calls
• Requires long-lived connections and complex client-side stream handling
• Harder to debug tool execution due to streaming semantics
• More complex error recovery and retry logic
• Inspector support is less mature

When to Use Other Transports

• HTTP: When you need remote deployment or multiple clients calling the server simultaneously
• SSE: When building streaming AI agents that need real-time, progressive responses

For a foundational tool server focused on correctness and reliability, STDIO is the right choice. You can always add HTTP transport later without changing any tool implementations.

💡 What This Project Intentionally Excludes

• AI agent logic
• LangChain / LangGraph workflows
• RAG pipelines
• Memory or planning systems

Those layers are meant to sit on top of this server, not inside it.

🔮 Future Extensions

This server can be extended with:

• AI agents that dynamically discover and call tools
• LangChain or LangGraph integration
• RAG pipelines grounded in web search
• Stateful or memory-based agents
• HTTP transport for remote deployment

No changes to existing tools are required.

✅ Key Takeaways

• Correct MCP server implementation using STDIO transport
• Real external integrations (weather, stocks, search)
• Clean tool contracts with clear input/output schemas
• Production-style separation of concerns
• Agent-ready foundation that can scale to complex workflows

📚 Additional Resources

• Model Context Protocol Documentation
• MCP Inspector
• OpenWeatherMap API
• Google Custom Search API