# ADR-0004: Remote MCP Server with SSE Transport
**Date:** 2026-01-22
**Status:** Accepted
**Deciders:** Architecture team
## Context
The Jana MCP Server needs to be deployable to cloud infrastructure (AWS) while maintaining development parity with local Docker environments. MCP (Model Context Protocol) supports two transport mechanisms:
1. **stdio** — Server runs as a subprocess spawned by the MCP client, communication via stdin/stdout
2. **SSE (Server-Sent Events)** — Server runs as a hosted HTTP service, communication via SSE over HTTPS
For a production cloud deployment where the MCP server runs alongside the Jana backend in AWS (ECS, Fargate, etc.), the stdio transport is not suitable. The SSE transport allows the MCP server to be a standalone HTTP service that MCP clients connect to over the network.
## Decision Drivers
- **Cloud deployment:** Must deploy to AWS as a containerized service
- **Development parity:** Same architecture in local Docker and production AWS
- **Client simplicity:** Users configure a URL, same for local and production
- **Internal communication:** MCP server needs fast access to Jana backend (same network)
- **Scalability:** Ability to scale MCP server independently
- **Production-grade:** Proper containerization, health checks, logging
## Considered Options
### Option 1: Local MCP Server (stdio transport)
**Description:** Users install the MCP server locally. Cursor spawns it as a subprocess.
**Pros:**
- Simpler MCP server implementation
- No hosting infrastructure needed for MCP server
- Lower latency for MCP protocol
**Cons:**
- Users must install and update MCP server locally
- MCP server → Jana backend calls go over public internet
- Can't leverage internal network between MCP and backend
- Different architecture for dev vs. production
### Option 2: Remote MCP Server (SSE transport)
**Description:** MCP server runs as a hosted HTTP service with SSE endpoints.
**Pros:**
- Same architecture for Docker (local) and AWS (production)
- Users just configure a URL
- MCP server and Jana backend on same network (fast internal calls)
- You control deployment, updates, scaling
- Proper production infrastructure patterns
**Cons:**
- More complex MCP server (HTTP framework needed)
- Must host and scale MCP server
- SSE connection management
### Option 3: Hybrid (Support both transports)
**Description:** Build MCP server to support both stdio and SSE.
**Pros:**
- Maximum flexibility
- Users can choose deployment model
**Cons:**
- More complex implementation
- More testing surface
- Unclear which to recommend
## Decision
**We will build a Remote MCP Server using SSE transport.**
### Technology Stack
| Component | Technology |
|-----------|------------|
| HTTP Framework | FastAPI |
| MCP Protocol | Official MCP Python SDK with SSE transport |
| Container | Docker |
| Local Orchestration | docker-compose (extends Jana stack) |
| Production Deployment | AWS ECS/Fargate (future) |
### Architecture
```
┌─────────────────────────────────────────────┐
│ User's Machine │
│ ┌─────────────────────────────────────┐ │
│ │ Cursor / Claude Code │ │
│ │ Config: http://localhost:8080/sse │ │
│ └──────────────────┬──────────────────┘ │
└─────────────────────┼───────────────────────┘
│ HTTP + SSE
▼
┌─────────────────────────────────────────────────────────────┐
│ Docker Network (local) / AWS VPC (production) │
│ │
│ ┌───────────────────────────────────────┐ │
│ │ jana-mcp-server │ │
│ │ - FastAPI + MCP SDK (SSE) │ │
│ │ - Port 8080 │ │
│ └──────────────────┬────────────────────┘ │
│ │ HTTP (internal) │
│ ┌──────────────────▼────────────────────┐ │
│ │ Jana Backend (web) │ │
│ │ - Django + DRF │ │
│ │ - Port 8000 │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Client Configuration
Users configure their MCP client with the server URL:
**Local Development:**
```json
{
"mcpServers": {
"jana": {
"url": "http://localhost:8080/sse"
}
}
}
```
**Production:**
```json
{
"mcpServers": {
"jana": {
"url": "https://mcp.jana.example.com/sse"
}
}
}
```
### Docker Integration
The MCP server integrates with the existing Jana docker-compose stack:
```yaml
# docker-compose.override.yml (in jana-mcp-server repo)
services:
mcp:
build: .
ports:
- "8080:8080"
environment:
- JANA_BACKEND_URL=http://web:8000
- JANA_USERNAME=${JANA_USERNAME}
- JANA_PASSWORD=${JANA_PASSWORD}
depends_on:
- web
networks:
- default
networks:
default:
external:
name: jana_default
```
## Consequences
### Positive
- Consistent architecture across development and production
- Users only need to configure a URL
- Fast internal communication between MCP server and Jana backend
- Full control over deployment, updates, and scaling
- Proper production infrastructure patterns from day one
- Can add authentication, rate limiting, monitoring at MCP server level
### Negative
- More complex than stdio transport
- Must host MCP server infrastructure
- SSE connection management adds complexity
- Additional service to monitor and maintain
### Neutral
- Need to implement health check endpoints
- Need to handle SSE reconnection on client side (MCP SDK handles this)
- May want to add API key authentication for MCP server in production
## Implementation Notes
### FastAPI Application Structure
```python
from fastapi import FastAPI
from mcp.server.sse import SseServerTransport
from starlette.responses import EventSourceResponse
app = FastAPI(title="Jana MCP Server")
mcp_server = create_mcp_server()
sse_transport = SseServerTransport("/messages")
@app.get("/sse")
async def sse_endpoint(request: Request):
async with sse_transport.connect_sse(
request.scope, request.receive, request._send
) as streams:
await mcp_server.run(streams[0], streams[1])
@app.get("/health")
async def health():
return {"status": "ok"}
```
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `JANA_BACKEND_URL` | Jana backend API URL | `http://web:8000` |
| `JANA_USERNAME` | Auth username | (required) |
| `JANA_PASSWORD` | Auth password | (required) |
| `MCP_SERVER_PORT` | Server port | `8080` |
## References
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/anthropics/mcp-python-sdk)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [SSE Specification](https://html.spec.whatwg.org/multipage/server-sent-events.html)
