Notes and references for building an MCP server using the official tutorial and example code.

Building MCP Servers — Quickstart and Example Code

# Building MCP Servers

How to build a Model Context Protocol (MCP) server, with steps and example code references.

## Summary of Findings

- Core capabilities an MCP server can expose:
  - Resources: file-like data clients can read (e.g., API responses, file contents)
  - Tools: functions callable by the LLM (with user approval)
  - Prompts: prewritten templates to help users perform tasks
- Tutorial focus: Tools. The example “weather” server exposes two tools:
  - get_alerts(state: str): returns active weather alerts for a US state
  - get_forecast(latitude: float, longitude: float): returns forecast for a location
- System requirements (Python path in tutorial):
  - Python 3.10+
  - Python MCP SDK 1.2.0+
- Environment setup (Python):
  - Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh (restart terminal afterward)
  - Project init (macOS/Linux shown):
    - uv init weather; cd weather
    - uv venv; source .venv/bin/activate
    - uv add "mcp[cli]" httpx
    - touch weather.py
- Server implementation (Python example):
  - Import FastMCP from mcp.server.fastmcp; use httpx for HTTP requests
  - Define helper functions for National Weather Service (NWS) API (make_nws_request, format_alert)
  - Implement tools with @mcp.tool() decorators for get_alerts and get_forecast
  - Run server: mcp.run(transport='stdio')
  - Start server: uv run weather.py
- Logging guidance:
  - For STDIO-based servers: never write to stdout (e.g., print in Python, console.log in JS, fmt.Println in Go); use a logger that writes to stderr or files. Writing to stdout corrupts JSON-RPC messages.
  - For HTTP-based servers: stdout logging is fine (doesn’t interfere with HTTP responses).
  - Tool names should follow the MCP spec’s naming format.
- Testing with Claude for Desktop:
  - Claude for Desktop is not yet available on Linux; Linux users can proceed to building a client instead.
  - Configure ~/Library/Application Support/Claude/claude_desktop_config.json with an mcpServers entry, e.g.:
    {
      "mcpServers": {
        "weather": {
          "command": "uv",
          "args": ["--directory", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather", "run", "weather.py"]
        }
      }
    }
  - You may need the full path to the uv executable (which uv / where uv) and must use an absolute path to the server directory/file.
  - After configuration, restart Claude for Desktop and use the tool settings icon; try prompts like:
    - What’s the weather in Sacramento?
    - What are the active weather alerts in Texas? (Note: NWS covers US locations.)
- “Under the hood” flow:
  - Client sends the user’s question to Claude
  - Claude decides which tool(s) to use
  - Client executes tool(s) via the MCP server
  - Results return to Claude, which formulates the final response
- Reference code:
  - Complete example code is available in the “weather-server-python” folder (weather.py, pyproject.toml, etc.). The repo README labels it “A Simple MCP Weather Server written in Python” and points back to the tutorial.

## Sources
- [Build an MCP server — Model Context Protocol](https://modelcontextprotocol.io/docs/develop/build-server) - Official tutorial covering concepts, environment setup with uv, Python example using FastMCP, logging best practices, and Claude for Desktop configuration/testing steps.
- [quickstart-resources/weather-server-python — GitHub](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-python) - Repository directory containing the full Python weather server example code and project files referenced in the tutorial.