Remote MCP Server
Deploy @flowrag/mcp as a centralized HTTP server so multiple AI assistants can share a single knowledge base.
Architecture
Section titled “Architecture”┌──────────────┐ ┌──────────────┐│ Kiro (user A)│ │Claude (user B)│└──────┬───────┘ └──────┬───────┘ │ HTTPS │ └────────┬───────────┘ ▼ ┌───────────────┐ │ MCP Server │ Fargate / ECS │ (HTTP) │ └───────┬───────┘ │ VPC ┌───────────┼───────────┐ ▼ ▼ ▼┌───────┐ ┌──────────┐ ┌───────┐│ Redis │ │OpenSearch │ │Bedrock│└───────┘ └──────────┘ └───────┘Server Configuration
Section titled “Server Configuration”Create flowrag.config.json:
{ "data": "./data", "docs": "./content", "schema": { "entityTypes": ["SERVICE", "DATABASE", "PROTOCOL"], "relationTypes": ["USES", "PRODUCES", "CONSUMES"] }, "storage": { "kv": { "provider": "redis", "url": "redis://redis.internal:6379" }, "vector": { "provider": "opensearch", "node": "https://os.internal:9200", "dimensions": 1024 }, "graph": { "provider": "opensearch", "node": "https://os.internal:9200" } }, "embedder": { "provider": "bedrock" }, "extractor": { "provider": "bedrock" }, "namespace": "team-docs", "transport": "http", "port": 3000, "auth": { "token": "${FLOWRAG_AUTH_TOKEN}" }}Set the token in .env:
FLOWRAG_AUTH_TOKEN=your-secret-tokenAWS_REGION=eu-central-1Client Configuration
Section titled “Client Configuration”Clients just need a URL and token — no local config, no command/args:
Kiro (mcp.json)
Section titled “Kiro (mcp.json)”{ "mcpServers": { "flowrag": { "url": "https://flowrag.internal.company.com/mcp", "headers": { "Authorization": "Bearer ${FLOWRAG_TOKEN}" } } }}Claude Desktop
Section titled “Claude Desktop”{ "mcpServers": { "flowrag": { "url": "https://flowrag.internal.company.com/mcp", "headers": { "Authorization": "Bearer my-secret-token" } } }}Storage Backends
Section titled “Storage Backends”Each storage type can be configured independently. Omitted types fall back to local storage.
KV Storage
Section titled “KV Storage”| Provider | Config | Package |
|---|---|---|
redis |
{ "url": "redis://..." } |
@flowrag/storage-redis + redis |
s3 |
{ "bucket": "...", "prefix": "...", "region": "..." } |
@flowrag/storage-s3 |
Vector Storage
Section titled “Vector Storage”| Provider | Config | Package |
|---|---|---|
lancedb |
{ "path": "./data/vectors" } |
@flowrag/storage-lancedb |
sqlite |
{ "path": "./data/vectors.db", "dimensions": 384 } |
@flowrag/storage-sqlite + sqlite-vec |
opensearch |
{ "node": "https://...", "dimensions": 1024 } |
@flowrag/storage-opensearch + @opensearch-project/opensearch |
redis |
{ "url": "redis://...", "dimensions": 384 } |
@flowrag/storage-redis + redis |
Graph Storage
Section titled “Graph Storage”| Provider | Config | Package |
|---|---|---|
sqlite |
{ "path": "./data/graph.db" } |
@flowrag/storage-sqlite |
opensearch |
{ "node": "https://..." } |
@flowrag/storage-opensearch + @opensearch-project/opensearch |
Authentication
Section titled “Authentication”Bearer token authentication protects all MCP endpoints. The token supports environment variable interpolation:
{ "auth": { "token": "${FLOWRAG_AUTH_TOKEN}" } }Requests without a valid Authorization: Bearer <token> header receive a 401 response.
Endpoints
Section titled “Endpoints”| Method | Path | Purpose |
|---|---|---|
| POST | /mcp |
MCP requests (initialize, tool calls) |
| GET | /mcp |
SSE stream for server-initiated messages |
| DELETE | /mcp |
Session termination |
| GET | /health |
Health check ({ "status": "ok" }) |
Docker
Section titled “Docker”A complete example is available in examples/fargate/.
Dockerfile
Section titled “Dockerfile”Multi-stage build, no secrets in the image:
FROM node:24-slim AS buildWORKDIR /appCOPY package.json package-lock.json* ./RUN npm ci --omit=dev
FROM node:24-slimWORKDIR /app
COPY --from=build /app/node_modules ./node_modulesCOPY flowrag.config.json .
ENV NODE_ENV=productionEXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s \ CMD node -e "fetch('http://localhost:3000/health').then(r=>{if(!r.ok)throw r})" || exit 1
ENTRYPOINT ["node", "node_modules/@flowrag/mcp/dist/index.mjs"]CMD ["--config", "flowrag.config.json"]Build and run
Section titled “Build and run”docker build -t flowrag-mcp .docker run -p 3000:3000 \ -e FLOWRAG_AUTH_TOKEN=my-secret \ -e AWS_REGION=eu-central-1 \ flowrag-mcpFargate Deployment
Section titled “Fargate Deployment”The MCP server is a good fit for Fargate/ECS:
- Always-on: No cold starts for users
- Long-running indexing: No Lambda 15-minute timeout
- Connection pooling: Persistent connections to Redis/OpenSearch
- SSE streaming: Native support for progress notifications
Use the health check endpoint (/health) for your load balancer target group.
Graceful Shutdown
Section titled “Graceful Shutdown”The server handles SIGINT and SIGTERM signals:
- Stops accepting new connections
- Closes all active MCP sessions
- Exits cleanly
ECS sends SIGTERM before stopping a task, so sessions are cleaned up properly.
Namespace
Section titled “Namespace”Use the namespace field to isolate data for different teams or projects sharing the same storage backends:
{ "namespace": "team-payments", "storage": { ... }}See Multi-Tenancy for details on how namespacing works.