Your MCP server is not an API adapter

Wojciech Wentland — Wed, 08 Apr 2026 19:59:13 +0000

A lot of MCP servers I see in the wild look like this:

@mcp.tool()
async def get_thing(id: str):
    resp = await httpx.get(f"https://api.example.com/things/{id}")
    return resp.json()

Fetch, forward, done. A thin HTTP proxy with a JSON Schema wrapper. For some
use cases, that's enough.

The servers I keep coming back to do something different. They hold state and
pre-compute answers. An agent hitting a thin wrapper might need three round
trips and 30 seconds. The same agent hitting a server that does real work gets
its answer in one call, under a millisecond.

Preloaded in-memory index

Here's a failure mode I run into constantly: the agent needs to find something
but doesn't know the exact ID. Most APIs only support exact lookups. No ID, no
result. The conversation dead-ends with "I couldn't find that resource" and the
user gives up.

I built a server that wraps a CDN management API. Hundreds of properties, and
the agent regularly needs to find which one handles a given hostname. The API
has a search endpoint, but it's slow, requires exact matches, and sometimes
returns 403 depending on account permissions.

So the server loads every property into memory at startup:

class PropertyIndex:
    _entries: list[PropertyEntry] = field(default_factory=list)
    _name_index: dict[str, int] = field(default_factory=dict)

    async def load(self, refresh_interval: int = 300):
        await self._build_index()
        self._refresh_task = asyncio.create_task(self._refresh_loop())

    def search_by_name(self, query: str, limit: int = 50):
        names = [e.property_name for e in self._entries]
        matches = process.extract(
            query, names, scorer=fuzz.WRatio,
            limit=limit, score_cutoff=50,
        )
        return [self._entries[idx].to_dict() for _, score, idx in matches]

Builds once by fanning out parallel API calls, deduplicates, refreshes every
five minutes in the background. Lookups take under a millisecond.

Without this, the agent guesses at exact property names, picks the wrong one,
retries, burns three turns. With the index, someone types "the CDN config for
checkout" and gets the right answer first try. That's the kind of difference
that decides whether people keep using the agent or go back to doing it
manually.

I did the same thing for a CI/CD server. The API lets you fetch a build config
by ID, but there's no fuzzy search. If you don't know the ID, you're stuck. The
server caches all build configurations at startup, runs fuzzy matching against
them. The agent says "find the deploy job for the payments service" and gets a
ranked list instantly, even though the CI system itself can't do that.

Embedded analytical database

I have another server that sits in front of a relational database. Some tables
have 20 million rows. The agent needs to answer analytical questions, things
like "which providers have the highest volume in this region?" or "show me the
top performers for a given category."

The database wasn't designed for these queries. It was built for a web UI with
narrow, well-indexed lookups. The agent's access patterns are different: it asks
broad analytical questions that require joins across tables the application
never joins. Adding indexes wasn't an option either, because the database is
owned by another team and optimizing it for an AI agent's query patterns wasn't
on anyone's roadmap. Some of these queries took 10 to 30 seconds on a read
replica, and in an agent loop where that latency gets multiplied by however many
tool calls the agent needs, the conversation times out before it gets anywhere.

The server embeds DuckDB in-process and loads pre-aggregated views and lookup
tables at startup. Some are straight copies of small reference tables. Others
are materialized summaries that flatten joins the source database was never
designed to run efficiently, the kind of cross-table aggregations that make
sense for an analytical question but would be expensive on a schema built for
transactional web UI lookups:

class DuckDBCache:
    async def start(self):
        self._conn = duckdb.connect(":memory:")
        for key, config in fast_configs.items():
            await self._load_table(key, config)
        self._ready = True
        self._deferred_task = asyncio.create_task(
            self._load_deferred(deferred_configs)
        )
        self._refresh_task = asyncio.create_task(self._refresh_loop())

Each table has a fingerprint query (a cheap COUNT(*) or checksum) that the
refresh loop checks before doing a full reload. Large tables load in the
background after the server is already taking requests. If something asks for a
table that hasn't loaded yet, it falls back to the source database.

The 30-second query now takes under a millisecond. The agent can actually have a
back-and-forth with the user instead of timing out after the first question.

There's a query-result cache on top of this too. It has a prewarm manifest,
basically a list of common queries that run at startup so the first person to
use the agent on Monday morning doesn't sit through a cold start.

class QueryCache:
    async def get_or_compute(self, cache_key, compute_fn, ttl=None):
        cached = self.get(cache_key)
        if cached is not None:
            return cached

        result = await compute_fn()
        if "error" not in result:
            self._put(cache_key, result, ttl or self._default_ttl)
        return result

It skips caching error responses. If a query fails because the database is
temporarily overloaded, you don't want that failure served for the next hour.
That one took a production outage to figure out.

Data transformation

Every server I build strips the upstream API response before returning it.
Token usage scales with response size, and most APIs return 10x more data than
the agent will ever look at.

One API I work with returns objects with 60+ fields. The server keeps maybe 8:

def _slim_record(r: dict):
    return _strip_nulls({
        "id": r.get("id"),
        "name": r.get("name"),
        "total_value": _cents_to_major(r.get("total_value_cents")),
        "annual_value": _cents_to_major(r.get("annual_value_cents")),
        "start_date": r.get("start_date"),
        "end_date": r.get("end_date"),
        "status": _effective_status(r),
    })

_cents_to_major converts cents to dollars. The raw API stores monetary values
in cents. Before I added this conversion, 100% of the reports the agent
generated had wrong numbers. Every dollar amount was off by a factor of 100. A $2,000 contract showed up as
$200,000 in the report because the agent treated cents as dollars. No amount of prompt engineering fixed it reliably. Moving the conversion
into the server did.

_effective_status is the other one worth mentioning. The API's status field
can say "active" on a record that ended three months ago. The platform's own UI
derives the real status from multiple fields, so the MCP server does the same:

def _effective_status(r: dict) -> str:
    stage = r.get("stage")
    if stage in ("terminated", "not_renewed"):
        return "inactive"

    if r.get("end_date_not_applicable") or r.get("renewal_type") == "perpetual":
        return r.get("status", "undetermined")

    end_date = r.get("end_date")
    if end_date:
        if date.fromisoformat(end_date) < date.today():
            return "inactive"

    return r.get("status", "undetermined")

Now the agent gives the same answer a human would get looking at the UI.
Stripping nulls across a list of 50 records also saves a few thousand tokens
per response, which adds up.

A log aggregation server I built does something similar: auto-appends
| json auto to queries that don't have a field extraction operator, truncates
raw log lines to 500 characters, converts epoch-millisecond timestamps to
ISO 8601. Small fixes that add up to the agent not wasting turns fighting the
format.

Download once, serve from cache

Some data is expensive to fetch. PDF documents. Code bundles in tgz archives.
The pattern: download on first access, extract the text, build a line offset
index, serve everything from memory after that.

class CachedFile:
    def __init__(self, content: str):
        self.content = content
        offsets = [0]
        pos = 0
        while True:
            pos = content.find("\n", pos)
            if pos == -1:
                break
            pos += 1
            if pos < len(content):
                offsets.append(pos)
        self._offsets = offsets

    def get_lines(self, start: int, end: int) -> str:
        return self.content[self._offsets[start-1] : self._line_end_offset(end)]

I use this for CDN edge function code bundles and PDF documents (extracted with
PyMuPDF). After the first download, the agent reads by line range, searches
with regex, lists the file tree. No repeat downloads. Reading through a
200-page document becomes "just read" instead of "download, extract, read" on
every question.

When thin is fine

Not everything needs this treatment. A server that translates natural language
to a query language and passes it to an API is fine as a thin wrapper. The
translation is the value there. Same for simple lookup tools.

The question I ask: does the agent hit the same data twice? Does the API return
more than the agent needs? Is the API response time slow enough that the agent
loop feels broken? If yes, the server should be doing work.

The multiplier

When a person uses a web UI, they look at a page, think, click something else.
One request at a time, processed by a human brain. An agent works differently.
It makes five tool calls, stuffs all five responses into its context window, and
reasons over them at once. A slow response gets multiplied by every call. A
60-field JSON blob gets multiplied by every call. It adds up fast.

I've measured the difference. CDN property lookups went from three agent turns
to one once the fuzzy index was in place. Analytical queries went from timing
out at 30 seconds to returning in under a millisecond from DuckDB. And every
single dollar amount in every report was wrong until the server started
converting cents for the agent.

You can try to fix that last one with prompt engineering. I tried for weeks. The agent still got it wrong often enough that I couldn't trust the output.