A full-stack conversational flight assistant built with a Model Context Protocol (MCP) server, a Claude-powered agent backend, and a React chat frontend. Users can search for flights, book tickets, and check in using natural language.
┌─────────────────────────────────────────────────────────────────────┐
│ User (Browser) │
│ React + Tailwind Chat UI │
│ (S3 + CloudFront / localhost) │
└────────────────────────────┬────────────────────────────────────────┘
│ WebSocket (wss://)
┌────────────────────────────▼────────────────────────────────────────┐
│ Agent Backend │
│ Node.js + Express + WebSocket Server │
│ Claude Sonnet 4 (Anthropic API) │
│ (AWS EC2 / localhost:8080) │
└────────────────────────────┬────────────────────────────────────────┘
│ Tool calls (in-process)
┌────────────────────────────▼────────────────────────────────────────┐
│ MCP Server │
│ @modelcontextprotocol/sdk (StdioTransport) │
│ Tools: query_flight · book_flight · check_in │
└────────────────────────────┬────────────────────────────────────────┘
│ HTTPS + JWT Auth
┌────────────────────────────▼────────────────────────────────────────┐
│ Flight API Gateway (AWS App Runner) │
│ https://ipfcssutkw.eu-west-1.awsapprunner.com │
└─────────────────────────────────────────────────────────────────────┘
- User types a message in the chat UI
- Frontend sends
{ type: "chat", message, history }over WebSocket - Agent backend passes the message + history to Claude (with tool definitions)
- Claude decides to call a tool (e.g.,
query_flight) - Backend executes the tool → MCP server → authenticated API call to Flight API
- Tool result is returned to Claude, which formulates a natural language response
- Backend sends
{ type: "message", role: "assistant", content }back over WebSocket - Frontend renders the assistant's reply in the chat
Assigment2/
├── mcp-server/ # Model Context Protocol server
│ ├── src/
│ │ ├── index.ts # MCP server entry — tool definitions
│ │ └── apiClient.ts # Axios instance with JWT auth interceptors
│ ├── package.json
│ ├── tsconfig.json
│ └── .env
│
├── agent-backend/ # WebSocket server + Claude agent loop
│ ├── src/
│ │ ├── index.ts # HTTP health-check + WebSocket server
│ │ ├── agent.ts # Claude agentic loop with tool execution
│ │ └── tools.ts # Tool implementations (HTTP calls to Flight API)
│ ├── Dockerfile
│ ├── package.json
│ ├── tsconfig.json
│ └── .env
│
└── frontend/ # React chat UI
├── src/
│ ├── App.tsx
│ ├── types.ts
│ ├── components/
│ │ ├── ChatWindow.tsx
│ │ ├── MessageBubble.tsx
│ │ ├── ToolCallBadge.tsx
│ │ └── InputBar.tsx
│ └── hooks/
│ └── useWebSocket.ts
├── vite.config.ts
├── tailwind.config.js
├── .env # Development: ws://localhost:8080
├── .env.production # Production: ws://<EC2-IP>:8080
└── package.json
| Layer | Technology |
|---|---|
| Frontend | React 19, Vite 8, TypeScript, Tailwind CSS v3 |
| Agent Backend | Node.js, TypeScript, ws WebSocket library |
| AI Model | Claude Sonnet 4 (claude-sonnet-4-20250514) via Anthropic SDK |
| MCP Server | @modelcontextprotocol/sdk with StdioServerTransport |
| HTTP Client | Axios with request/response interceptors |
| Auth | JWT (auto-login + 401 retry) |
| Containerization | Docker (node:20-alpine) |
| Deployment | AWS EC2 (backend), AWS S3 + CloudFront (frontend) |
Search for available flights between two airports.
| Parameter | Type | Required | Description |
|---|---|---|---|
airportFrom |
string | Yes | Departure airport code (e.g. IST) |
airportTo |
string | Yes | Arrival airport code (e.g. FRA) |
dateFrom |
string | Yes | Start date YYYY-MM-DD |
dateTo |
string | Yes | End date YYYY-MM-DD |
numberOfPeople |
number | Yes | Passenger count |
tripType |
string | No | ONE_WAY (default) or ROUND_TRIP |
page |
number | No | Zero-indexed page (default 0) |
Maps to: GET /api/v1/flights
Book seats on a specific flight for one or more passengers.
| Parameter | Type | Required | Description |
|---|---|---|---|
flightNumber |
string | Yes | Flight identifier (e.g. TK1523) |
date |
string | Yes | Flight date YYYY-MM-DD |
passengerNames |
string[] | Yes | Array of full passenger names |
Maps to: POST /api/v1/tickets
Check in a passenger using their flight number, date, and name.
| Parameter | Type | Required | Description |
|---|---|---|---|
flightNumber |
string | Yes | Flight identifier |
date |
string | Yes | Flight date YYYY-MM-DD |
passengerName |
string | Yes | Full passenger name |
Maps to: POST /api/v1/checkin
API_GATEWAY_BASE_URL=https://ipfcssutkw.eu-west-1.awsapprunner.com
API_USERNAME=claude
API_PASSWORD=claude123ANTHROPIC_API_KEY=<your-anthropic-api-key>
PORT=8080
API_GATEWAY_BASE_URL=https://ipfcssutkw.eu-west-1.awsapprunner.com
API_USERNAME=claude
API_PASSWORD=claude123VITE_WS_URL=ws://localhost:8080VITE_WS_URL=ws://<your-ec2-ip>:8080- Node.js 20+
- npm 9+
cd mcp-server && npm install
cd ../agent-backend && npm install
cd ../frontend && npm installcd agent-backend
npm run dev
# Server starts on http://localhost:8080
# WebSocket available at ws://localhost:8080The agent backend imports the MCP server's apiClient directly at build time — no separate MCP server process needed.
cd frontend
npm run dev
# Open http://localhost:5173User: Find me flights from IST to FRA on May 10
Agent: ⚙ Searching flights...
Here are the available flights from IST to FRA on May 10:
• TK1523 — Duration: 195 min — Available seats: 12
• ...
User: Book TK1523 on May 10 for John Doe
Agent: ⚙ Booking flight...
Booking confirmed!
• Ticket #TK1523-001 — John Doe
User: Check in John Doe for TK1523 on May 10
Agent: ⚙ Checking in...
Check-in successful!
Passenger: John Doe — Seat: 14A
# From the repo root
docker build -f agent-backend/Dockerfile -t agent-backend .
docker run -p 8080:8080 --env-file agent-backend/.env agent-backendThe Dockerfile copies both mcp-server/ and agent-backend/ into the image because the backend imports shared code from the MCP server.
cd frontend
npm run build
# Output in frontend/dist/Deploy to S3:
aws s3 sync dist/ s3://<your-bucket-name> --delete- Launch an EC2 instance (Amazon Linux 2 / Ubuntu, t3.micro or larger)
- Install Docker:
sudo yum install docker -y && sudo service docker start - Copy the repo to the instance (or pull from ECR/DockerHub)
- Build and run the container:
docker build -f agent-backend/Dockerfile -t agent-backend . docker run -d -p 8080:8080 --env-file agent-backend/.env agent-backend - Open port 8080 in the EC2 security group
- Create S3 bucket with static website hosting enabled
- Set
frontend/.env.productionwith the EC2 WebSocket URL - Build and upload:
npm run build aws s3 sync dist/ s3://<bucket> --delete aws s3 website s3://<bucket> --index-document index.html --error-document index.html
- Create a CloudFront distribution pointing to the S3 website endpoint
- Default root object:
index.html - Custom error response: 404 →
/index.html(required for SPA)
- Default root object:
Note: CloudFront does NOT proxy WebSocket connections. The frontend connects directly to the EC2 WebSocket URL — CloudFront only serves the static files.
The Flight API uses JWT. The apiClient in mcp-server/src/apiClient.ts handles this transparently:
- On the first API call, it logs in via
POST /api/v1/auth/login - The JWT is stored in memory and attached as
Authorization: Bearer <token>on all requests - If a 401 is received, it re-authenticates once and retries the original request automatically
No per-user auth is needed — a single shared service account is used for all tool calls.
{
"type": "chat",
"message": "Find flights from IST to FRA",
"history": [
{ "role": "user", "content": "..." },
{ "role": "assistant", "content": "..." }
]
}{
"type": "message",
"role": "assistant",
"content": "Here are the available flights..."
}{
"type": "tool_call",
"tool": "query_flight",
"input": { "airportFrom": "IST", "airportTo": "FRA", ... }
}{
"type": "error",
"message": "Something went wrong..."
}- MCP server as a library, not a process: The agent backend imports
apiClientdirectly frommcp-server/src/rather than spawning a separate stdio process. This simplifies deployment while preserving the MCP tool abstractions. - Stateless sessions: Conversation history is maintained in-memory per WebSocket connection and resets on reconnect. No database needed.
- Client-side history: The frontend sends its full conversation history with every message, allowing the backend to remain stateless across connections.
- Exponential backoff reconnect: The frontend WebSocket hook retries up to 5 times with delays of 1s, 2s, 4s, 8s, 16s before giving up.
- Single shared JWT: All API calls share one service-account JWT token in memory. On 401, it refreshes automatically without any user interaction.