Lessons Learned: Building a Stateless Kiksasa MCP Server

The Kiksasa Vision: Beyond the Dashboard

The Kiksasa platform aggregates rich data across multiple ecosystems, providing deep insights into organizations, their members, and the news and events most critical to their success. As our platform grows, we’ve faced a classic data provider challenge: we cannot always predict how our customers will want to visualize or utilize this information.

Instead of building an endless array of customizable dashboards and complex filtering UIs that may never quite meet every unique need, we decided on a more flexible approach. By providing Model Context Protocol (MCP) access, we empower our customers to use powerful AI models like Claude or OpenAI to build their own "dashboards" on the fly. Whether they need a custom report, a unique data visualization, or a structured query across multiple datasets, they can use their preferred AI interface to populate it directly with Kiksasa data.

What is MCP, and why Kiksasa?

The Model Context Protocol (MCP) is an open standard that enables AI models to connect directly to external data sources. At its core, MCP allows data providers like Kiksasa to expose their data through Tools—structured functions that the AI can discover and execute.

For Kiksasa, this means our MongoDB datasets are no longer locked behind a specific UI. We implement the tool logic, handling structured requests and complex queries, and the AI model simply calls these tools when the user asks a question. This creates a seamless "context bridge" between the model's reasoning and Kiksasa's live data.

Challenge 1: The "Stateless vs. Persistent" Conflict

The standard MCP-over-HTTP transport relies on two distinct methods to maintain a session:

1. GET: Used to establish a persistent Server-Sent Events (SSE) stream. This connection is intended to stay open indefinitely so the server can push updates to the client.

2. POST: Used by the client to send specific commands or "tool calls" to the endpoint provided during the GET handshake.

   
   

Why this breaks with Lambda: AWS Lambda is inherently stateless and execution-bounded. It is designed to process a request and exit immediately. When the MCP SDK tried to maintain that persistent GET stream, the Lambda would hang, eventually hitting its timeout or crashing with a Runtime.NodeJsExit error because the process never settled its promises.

The Solution: The Hybrid Handler & Pseudo-SessionIDs We refactored the Lambda to handle the handshake manually. When a GET request arrives, we return a single event: endpoint message and immediately terminate the connection.

To satisfy the SDK’s requirement for session continuity across these stateless hits, we implemented a Pseudo-SessionID. We generate a unique ID during the GET handshake, return it in an Mcp-Session-Id header, and bake it into the tool-call URL. This "tricks" the client into seeing a cohesive stateful session, even though every subsequent POST request hits a fresh, stateless Lambda instance.

Challenge 2: Aggressive Polling & Infrastructure Noise

Once we started closing the connection early, the MCP client (Claude Desktop) became "over-helpful." It assumed the connection had dropped unexpectedly and began reconnecting every 1-2 seconds to restore the "missing" stream.

The Symptom: Lambda logs were spammed with constant --- GET /mcp --- requests, driving up costs and creating a noisy denial-of-service loop.

The Solution: The SSE retry Event Trick In the standard SSE specification, a server can tell a client how long to wait before attempting to reconnect. By including retry: 86400000 (24 hours) in our manual handshake, we effectively told the client: "I've given you the endpoint you need. Now, please don't call me again for a day." Because the actual tool calls happen over independent POST requests, they remain unaffected, while the idle background noise drops to zero.

Challenge 3: Supporting Restricted Environments (ex: Claude Desktop)

Claude Desktop is a powerful interface, but it's a "walled garden." It only supports Stdio (local processes) and has no built-in way to connect to a remote URL with custom API key headers.

The Symptom: Users were often forced into complex OAuth flows or insecure URL parameters just to connect to their own data, creating a poor user experience for non-technical clients.

The Solution: The Silent Stdio-to-SSE Bridge We built a dedicated Node.js bridge script using the most modern transport available: StreamableHTTPClientTransport. This script runs locally on the user's machine, listens to Claude via Stdio, and pipes those messages to our remote Lambda. By managing the connection locally, we can securely inject the customer's API Key into the HTTP headers, keeping the user's credentials off the wire and out of the logs.

Challenge 4: Zero-Dependency Distribution with Bun

Asking a non-technical client to install Node.js, configure NVM, or set up WSL just to use an MCP server is a major barrier to adoption.

The Solution: Standalone Binaries We utilized Bun’s native compilation engine to eliminate the Node requirement entirely. By running bun build --compile, we packaged our bridge script, all its dependencies, and a tiny JS runtime into a single, standalone executable.

Now, a Kiksasa client simply downloads kiksasa-mcp-bridge.exe (Windows) or the Mac equivalent, points Claude to it, and they are live. No Node, no WSL, no configuration headaches.

Conclusion

Building the Kiksasa MCP Server was about more than just tool implementation; it was about understanding the lifecycle of the infrastructure it runs on. By combining Manual SSE Handshaking, Stateless Session Management, and Compiled Binary Bridges, we’ve created an architecture that realizes our vision: giving customers the data they need, in the interface they choose, without the overhead of custom dashboards.

The "plug" icon is green, the logs are quiet, and the Kiksasa ecosystem is open for AI-driven exploration. 🚀