Weather Chat Agent

Python monorepo demonstrating building and connecting two independent services using Anthropic's Model Context Protocol.

The first service mcp-server is a FastMCP server that exposes live weather data as AI-callable tools, backed by the free Open-Meteo API and secured with OAuth 2.1 via Okta.

The second service chat-api is a FastAPI application that lets users have multi-turn weather conversations with Earl, a grumpy retired meteorologist persona powered by Claude, with conversation history persisted in Postgres.

The two services communicate only over HTTP and are intentionally architected as if they lived in separate repositories: each has its own dependencies, Dockerfile, CI pipeline, and knows nothing about the other at the code level. The shared parent repo exists purely for convenience, one clone, one docker compose up, and the full stack is running.

---

Prerequisites

• Python 3.10+
• uv — Python package manager
• Docker (for Docker Compose mode)
• Anthropic API key
• Postgres (local install or via Docker)

---

Services

Service	Description	Port	Health
mcp-server	FastMCP server exposing live weather tools via Open-Meteo	8000	GET /healthz
chat-api	FastAPI chat service powered by Claude + Earl persona	9000	GET /healthz
postgres	Conversation history	5432	—

---

API

Method	Endpoint	Auth	Description
POST	/api/v1/auth/register	None	Create account, get JWT
POST	/api/v1/auth/login	None	Get JWT
POST	/api/v1/chat	Bearer JWT	Chat with Earl

---

Project Structure

This is a monorepo of two independent services — not a monolith. Each service has its own dependencies, Dockerfile, CI pipeline, and can be deployed, tested, and developed in complete isolation. They share no code and communicate only over HTTP, exactly as they would if they lived in separate repositories.

The shared parent repo (mcp-weather-chat-agent/) exists for one practical reason: a single git clone, a single compose.yaml, and one place to manage local development. The only file that knows both services exist is compose.yaml. Delete it and each project still builds, tests, and deploys independently.

mcp-weather-chat-agent/     ← parent repo (git + docker compose live here)
├── docker-compose.yaml     ← the ONLY file aware of both services
├── mcp-server/             ← independent project 
└── chat-api/               ← independent project

---

Run application

Modes (WEATHER_CHAT_MCP_MODE)

Mode	How It Works	When to Use	Requirements
local_stdio	Spawns the MCP server as a subprocess and communicates over stdin/stdout	Local development, interviews, offline testing	Just configure the path to the MCP server
local_http	Connects to an MCP server running on localhost over HTTP	Testing HTTP-based MCP servers locally	MCP server must already be running separately
remote	Anthropic's cloud service connects directly to the MCP server	Production and staging environments	Publicly accessible URL (deployed service or ngrok)

Mode: local_stdio (local dev)

• The chat-api spawns the MCP server automatically as a subprocess. No separate process to manage, no network port, one command starts everything.

1. cd chat-api
   • update .env
     • WEATHER_CHAT_MCP_MODE=local_stdio
     • WEATHER_CHAT_MCP_SERVER_PATH=../mcp-server
2. run: uv run weather-chat-api

Mode: local_http

• The MCP server runs as a standalone HTTP service on localhost:8000 and the chat-api connects to it directly. Requires two terminals but keeps the two services fully independent at runtime.

1. Terminal 1: start the MCP server
   • cd mcp-server
   • update .env
     • WEATHER_MCP_TRANSPORT=streamable-http
   • run: uv run mcp-server
2. Terminal 2: start the chat API
   • cd chat-api
   • update .env
     • WEATHER_CHAT_MCP_MODE=local_http
   • run: uv run weather-chat-api

Mode: remote

• The Anthropic cloud connects to a publicly reachable MCP server on your behalf. Use this for production deployments or local testing via ngrok.

1. Option A: deployed MCP server
   • cd chat-api
   • update .env
     • WEATHER_CHAT_MCP_MODE=remote
     • WEATHER_CHAT_MCP_SERVER_URL=https://your-deployed-mcp-server.com/mcp
   • run: uv run weather-chat-api
2. Option B: ngrok tunnel for local testing
   • Terminal 1: start MCP server in HTTP mode
     • cd mcp-server
     • update .env
       • WEATHER_MCP_TRANSPORT=streamable-http
     • run: uv run mcp-server
   • Terminal 2: expose it publicly
     • run: ngrok http 8000
       • copy the https://abc123.ngrok.io URL
   • update chat-api/.env:
     • WEATHER_CHAT_MCP_MODE=remote
     • WEATHER_CHAT_MCP_SERVER_URL=https://abc123.ngrok.io/mcp
   • Terminal 3: start the chat API
     • cd chat-api
     • run: uv run weather-chat-api
3. Option C: Cloudflare Tunnel (permanent subdomain)
   • Terminal 1: start MCP server in HTTP mode
     • cd mcp-server
     • update .env
       • WEATHER_MCP_TRANSPORT=streamable-http
     • run: uv run mcp-server
   • Terminal 2: create and run the tunnel
     • run: cloudflared tunnel create weather-mcp
     • run: cloudflared tunnel route dns weather-mcp mcp.yourdomain.com
     • run: cloudflared tunnel run --url http://localhost:8000 weather-mcp
   • update chat-api/.env:
     • WEATHER_CHAT_MCP_MODE=remote
     • WEATHER_CHAT_MCP_SERVER_URL=https://mcp.yourdomain.com/mcp
   • Terminal 3: start the chat API
     • cd chat-api
     • run: uv run weather-chat-api

---

Docker Compose

local_stdio is not supported with Docker Compose. Use local_http or remote.

Prerequisites

From mcp-weather-chat-agent/ — build wheels first (build artifacts):

(cd mcp-server && uv build --wheel)
(cd chat-api && uv build --wheel)

Required in mcp-weather-chat-agent/.env

WEATHER_CHAT_ANTHROPIC_API_KEY=your-key
WEATHER_CHAT_JWT_SECRET=your-32-char-secret

Mode: local_http

1. Update mcp-weather-chat-agent/.env

• WEATHER_CHAT_MCP_MODE=local_http
• WEATHER_CHAT_MCP_SERVER_URL=http://mcp-server:8000/mcp

2. docker compose up --build
   • postgres: localhost:5432
   • mcp-server: localhost:8000
   • chat-api: localhost:9000

Mode: remote

• When the MCP server is running externally (deployed, ngrok, or Cloudflare Tunnel), only postgres and chat-api need to run as containers, starting mcp-server would be redundant and conflict on port 8000. docker compose up --build chat-api postgres targets only the services Docker needs to manage.
• Use one of the Options then run:
  • docker compose up --build chat-api postgres
  • postgres: localhost:5432
  • chat-api: localhost:9000

Option A: deployed MCP server

1. Update mcp-weather-chat-agent/.env

• WEATHER_CHAT_MCP_MODE=remote
• WEATHER_CHAT_MCP_SERVER_URL=https://your-deployed-mcp-server.com/mcp

Option B: ngrok

1. Start MCP server locally: cd mcp-server && uv run mcp-server
   • .env must have: WEATHER_MCP_TRANSPORT=streamable-http
2. Expose it: ngrok http 8000 — copy the https://abc123.ngrok.io URL
3. Update mcp-weather-chat-agent/.env

• WEATHER_CHAT_MCP_MODE=remote
• WEATHER_CHAT_MCP_SERVER_URL=https://abc123.ngrok.io/mcp

Option C: Cloudflare Tunnel

1. Start MCP server locally: cd mcp-server && uv run mcp-server
   • .env must have: WEATHER_MCP_TRANSPORT=streamable-http
2. Run tunnel: cloudflared tunnel run --url http://localhost:8000 weather-mcp
3. Update mcp-weather-chat-agent/.env

• WEATHER_CHAT_MCP_MODE=remote
• WEATHER_CHAT_MCP_SERVER_URL=https://mcp.yourdomain.com/mcp