Trip Planner — MCP Server + LangGraph Agent

A journey-planning MCP server built with FastMCP, plus a LangGraph agent thatconnects to it alongside two public MCP servers. The agent manages atraveller's itinerary: journeys (trips as a whole), the city stops within ajourney, and the plan items (sights, meals, activities) within each stop.

Architecture

The user asks a question. The LangGraph agent thinks: if it needs a tool, itcalls one, gets the result, and thinks again — repeating until it has enoughto answer. MultiServerMCPClient connects to all three MCP servers when theagent starts and hands every discovered tool to the agent. One server isours; two are public.

Data model, tools, resource, prompt

SQLite, three tables, one nesting level each:

Table	Holds
`journeys`	A trip as a whole — title, home city, dates, budget
`stops`	A city leg within a journey — city, country, arrival date, nights, transport mode
`plan_items`	A sight/meal/activity within a stop — title, category, time window, priority, status

Tools (backend/mcpserver/TripPlannerServer.py) — full CRUD plus a live weather lookup:

Tool	CRUD
`create_journey`	Create
`add_stop`	Create
`add_plan_item`	Create
`list_stops`	Read
`update_plan_status`	Update
`delete_stop`	Delete (cascades to its plan items)
`get_destination_weather`	Calls the free Open-Meteo API (geocoding + current weather), no key needed

Resources:

journeys://all — one-line summary of every journey
journey://{journey_id}/itinerary — templated resource, a day-by-day itinerary for one journey (each stop with its plan items underneath)

Prompt:

suggest_itinerary(stop_id) — a reusable template that turns a stop's saved plan items into an hour-by-hour day plan

Public servers used, and why

time (uvx mcp-server-time, stdio) — official reference MCP server fortimezone/local-time lookups. Trivial, zero-risk, no genuine remotealternative exists for this, so stdio is the right call here.
tavily (Streamable HTTP, https://mcp.tavily.com/mcp) — a genuinelyhosted remote MCP server (no local process at all) from Tavily, areputable company in the LLM tooling space (the same search backendLangChain's own community tools use). It needs a free API key(tavily.com, no credit card). Picked over a plain page-fetch serverbecause it does real-time, ranked web search (attractions, traveladvisories, local facts) rather than fetching one raw page — a muchstronger fit for a trip planner. Deliberately avoided pulling a serverfrom the public MCP registries (registry.modelcontextprotocol.io,Smithery, Glama) directly — those directories are unvetted, and searchingthem turned up entries with suspicious names during development. Tavily isa known, reputable company with a real product, not an anonymous registrylisting.

Extras beyond the core CRUD flow

get_destination_weather calls the free Open-Meteo API from inside a tool(geocoding + current weather, no key required).
backend/integrations/fastapimcp_integration.py serves REST(/health, /journeys) and MCP (/mcp) from one FastAPI ASGI app.
add_stop logs via ctx.info(...), visible live in the MCP Inspector'snotification panel.
A browser console (backend/api/app.py + frontend/) — see below.

Console UI (bonus)

A small React console for driving the agent from a browser instead of theCLI: pick one of the 12 test questions (or type your own), watch each toolcall and its result stream in live, tool by tool, as the agent runs.

backend/api/app.py wraps the same LangGraph agent frombackend/client/langgraphagent.py in a long-lived FastAPI process. Itconnects to all three MCP servers once at startup, then streams eachquestion's step-by-step trace back to the browser as newline-delimited JSON.

Three processes, three terminals:

uv run backend/mcpserver/TripPlannerServer.py     # :8000 — the MCP server
uv run python -m backend.api.app                  # :8010 — streaming console API
cd frontend && npm install && npm run dev          # :5173 — the UI

Open the printed localhost URL. The left rail shows live server/toolcounts from /api/servers; the question list is the same 12-question set asDocsAndDemo/question.md.

How to run it

Install dependencies (uses uv):
```
uv sync
```

Copy .env.example to .env and fill in:

OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...      # free key at https://tavily.com

Start the server (terminal 1):
```
uv run backend/mcpserver/TripPlannerServer.py
```
Live at http://127.0.0.1:8000/mcp (note the required /mcp suffix).

Optional — run the combined REST+MCP app instead:
```
uv run python -m backend.integrations.fastapimcp_integration
```

Run the agent (terminal 2):

uv run backend/client/langgraphagent.py "Add a 3-night stop in Kyoto to journey 1 and tell me the local time there"

Optional — test the server directly in the MCP Inspector before running the agent:
```
npx @modelcontextprotocol/inspector
```
Transport: Streamable HTTP, URL: http://127.0.0.1:8000/mcp.

Requires uv (Python/uvx) and Node.js (npx, for the Inspector) installed.

Example runs

Full tool-call traces are in screenshots/demo.txt.Summary:

Write-only — "Create a new journey called 'Bali Getaway' fromMumbai, budget 1500, dates 2026-09-01 to 2026-09-10. Then add a 5-nightstop in Bali, Indonesia to it." → Created journey #3 and stop #4 on ourserver.
Write + public time — "Add a 4-night stop in Reykjavik, Iceland tojourney 3, and tell me the current local time there." → Added stop #5,and called get_current_time (both tool calls fired in parallel in oneturn) → 11:03, Saturday, Atlantic/Reykjavik (UTC+0).
Public tavily research — "What are the top attractions to see inReykjavik right now, and are there any current travel advisories forIceland?" → Real-time web search returned 8 ranked attractions and 3current government travel advisories, with live sources.

Why an MCP server instead of plain Python functions in the agent?

Putting tools in an MCP server decouples what a tool can do from whichagent uses it. The same trip_planner server can be called by thisLangGraph agent, tested by hand in the MCP Inspector, or plugged into acompletely different agent or client later, all without touching the toolcode — because the server exposes a stable, self-describing contract(schemas generated straight from function signatures and docstrings) over astandard protocol, instead of being tangled into one agent's Python process.It also means the server can run, scale, and fail independently of theagent: if the trip-planner logic needs a different host, a differentlanguage, or its own deployment schedule, that's an infrastructure change,not a rewrite. Writing the same logic as inline Python functions works finefor a single throwaway script, but it locks the tool to that one agent andgives up all of that reuse, isolation, and discoverability for no benefit.

Video walkthrough

DocsAndDemo/12.07.2026_22.51.20_REC.mp4 — demo, architecture walkthrough, MCP connection config, and live tool calls across the local and public servers.

Trip Planner — MCP Server + LangGraph Agent