Taming the firehose: A spooling architecture for large MCP tool responses

As organisations integrate large language models with external tools through the Model Context Protocol (MCP), a practical but undiscussed problem emerges: what happens when a tool returns more data than the LLM can usefully consume?

Third-party APIs frequently return large JSON payloads containing hundreds or thousands of records. Vulnerability scanners, SIEM query results, asset inventories, and cloud resource listings are common examples in Cyber Security operations. When passed directly back through an MCP tool, these responses consume a significant portion of the LLM’s context window, degrading reasoning quality, increasing token costs, and often causing outright failures. The LLM receives a wall of data it cannot meaningfully process, and the user gets a degraded or incomplete answer.

This workshop introduces a spooling architecture that sits between the raw API response and the MCP tool return value. The Response Spooler detects large arrays in API responses, flattens and stores the data in an ephemeral SQLite database, and returns a compact summary to the LLM containing record counts, column names, data types, basic statistics, and a small sample of representative records. The LLM receives just enough to understand what data is available, then uses generic spooler tools, including filtering, sorting, pagination, aggregation, and free-text search, to retrieve exactly what it needs.

Participants will work through the complete design pattern. The session begins with the detection logic that determines whether a response should be spooled or returned inline, based on configurable item count and token thresholds. It then covers the flattening algorithm that handles nested JSON structures common in security tool outputs, and the parameterised SQL query engine that prevents injection while supporting ten filter operators.

The workshop demonstrates three integration patterns: a single-line decorator for the simplest retrofit of existing MCP servers, a middleware class for finer-grained control, and direct manual invocation for complex workflows. Participants will see how the containerisation strategy uses ephemeral storage to eliminate data retention concerns, making the pattern suitable for sensitive Cyber Security data.

The framework is open-source and designed to be dropped into any MCP server implementation. Attendees will leave with working code they can integrate into their own environments, along with an understanding of the broader design challenge of managing context window consumption in tool-augmented AI systems.

Prerequisite

Attendees should come prepared with the following:

• A laptop you can install software on, whose security controls permit outbound HTTPS to github.com, pypi.org and astral.sh, running local Python processes, and editing application configuration files. Locked-down corporate laptops are the most common cause of setup failure on the day.
• uv installed (the Python package runner from Astral; the workshop launches everything via its uvx command). Installation takes one command: see docs.astral.sh/uv. Python 3.10+, pip and git are useful but not strictly required, as uv supplies its own interpreter.
• An MCP client that supports local stdio MCP servers, installed and signed in with an active account: Claude Desktop (recommended) or Visual Studio Code 1.99 or later with Copilot agent mode. You will edit the client's JSON configuration to add a local stdio server executed via uvx, so bring a laptop where you have permission to do that. Please note the ChatGPT desktop and web products support remote MCP connectors only and cannot launch local stdio servers; the workshop repository includes an appendix for Codex CLI users.
• Strongly recommended before the day: run the one-line smoke test in the README at github.com/Cognisn/spindl-workshop. It confirms your laptop can run the workshop server and pre-caches all dependencies, so conference wifi is not in your critical path. Cloning the repository is optional; uvx fetches it for you.
• Working familiarity with Python (the ability to read and modify a small script).
• Prior exposure to the Model Context Protocol (MCP) is helpful but not essential; a brief primer is provided at the start of the session.

No GitHub account is required, as the repository is public. No specific Cyber Security tools or commercial products are required. All sample data, the simulated firewall MCP server, and the spindl framework source code are publicly available ahead of the session. The exercises intentionally consume a large volume of model context in your client, so an active paid plan on your chosen client is recommended to avoid quota interruptions mid-exercise.