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 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

⚙️ Prerequisites

• Python 3.10+

• Node.js (for MCP Inspector)

• OpenWeatherMap API key

• Google Custom Search API key + CSE ID

📦 Installation

🔐 Environment Configuration

Create a .env file in the project root:

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:

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:

Output:

🌦️ Weather Tool

Input:

Output:

📈 Stock Price Tool

Input:

Output:

🚧 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