Skip to content
Technical 11 min read

Run One Web Data Agent Across Multiple MCP Servers

Wire one agent to fetch, extraction, and storage MCP servers. Handle tool name collisions, per-server auth scopes, and wrong-tool picks in production.

FE
FineData Engineering · Editorial Policy
|
On this page

The Incident That Looks Like an Extraction Bug

The incident always looks like an extraction bug at first. An agent wired to three MCP servers fetches pages, pulls structured fields out of them, and writes records to storage — except a third of the records are empty, and a couple of fetch attempts somehow landed on the storage server’s search endpoint. Nothing crashed. Every tool call returned success. The agent had been picking the wrong tools, with credentials it should never have held, and the single-server MCP examples everyone copies from never prepare you for it.

Multi-server agents break in three specific places: tool names collide across servers, credentials bleed between connections because everything sits in one flat environment, and the model grabs a semantically close tool from the wrong server. This post builds one agent wired to three MCP servers — fetch, extract, store — and works through each failure mode with runnable code. (When one of these failures does reach production, the companion post on tracing MCP tool calls and agent fetches shows how to read it back out of your traces.)

Architecture: One Agent, Three MCP Servers (Fetch, Extract, Store)

                +--------------------------------------+
                |  agent process (Python)              |
                |  ToolRouter  |  arg validator        |
                |  per-server retry/timeout policy     |
                +------+--------------+-----------+----+
                       | stdio        | stdio     | HTTP
                       v              v           v
             +----------------+ +-----------+ +---------------------+
             | fetch-server   | | extract-  | | store MCP           |
             | scrape API     | | server    | | store.example.com   |
             | wrapper        | | (local)   | | /mcp                |
             +----------------+ +-----------+ +---------------------+

The fetch server is a thin wrapper around a scraping API — FineData in these examples, but any HTTP fetch backend works. The extract server runs locally next to the agent and does schema-driven extraction on HTML already in memory. Storage lives at store.example.com and speaks MCP over HTTP. Two stdio transports, one HTTP transport, one process. All Python below is 3.10+.

Splitting into three servers is not architecture astronautics. Each server gets its own credentials, its own deploy cadence, and its own reuse across agents. The cost is that you now own routing — which is the rest of this post.

Bootstrap config:

mcp_servers:
  fetch:
    transport: stdio
    command: python
    args: ["-m", "fetch_mcp_server"]
    env:
      FETCH_API_KEY: fd_your_api_key
    timeout_s: 120

  extract:
    transport: stdio
    command: node
    args: ["extract-mcp-server/index.js"]
    timeout_s: 30

  store:
    transport: http
    url: https://store.example.com/mcp
    headers:
      Authorization: Bearer st_pages_write
    timeout_s: 20

Load it once at startup, build one client per entry, and never re-read it mid-run:

def build_clients(cfg: dict) -> dict:
    clients = {}
    for name, spec in cfg["mcp_servers"].items():
        if spec["transport"] == "stdio":
            clients[name] = StdioClient(spec["command"], spec["args"], spec["env"])
        else:
            clients[name] = HttpClient(spec["url"], spec["headers"])
        clients[name].connect(timeout_s=spec["timeout_s"])
    return clients

Our fetch server exposes search — an on-site search executed during a live fetch. The store also exposes search — a query over stored records. Flatten both into one tool list and dispatch becomes a coin flip decided by registration order. Best case you get a 400 for unexpected arguments. Worst case the wrong server happily returns an empty result set and your pipeline records “no data found” as a legitimate answer.

StrategyHow it worksProsCons
Server-prefixed namesRewrite every tool to <server>.<tool> at registrationDeterministic, zero extra config, self-documenting in logs and tracesSome clients reject dots in tool names; prefixes must stay stable
Alias mapsStatic dict mapping a friendly alias to (server, tool)The model sees short, natural namesThe map rots as servers add tools; aliases can collide too
Per-server registriesAgent targets a server first, then a tool within itStrongest isolation; natural for multi-tenant setupsThe model must now make two correct choices instead of one — you moved the routing problem, you didn’t remove it

I use prefixes and I’d argue you should too. Aliases are a prompt-level nicety sitting on top of a dispatch-level problem, and per-server registries just relocate the ambiguity. Two sentinel exceptions first, so routing failures never masquerade as tool failures:

class AmbiguousTool(Exception):
    def __init__(self, name: str, matches: list[str]):
        super().__init__(f"ambiguous tool {name!r}: matches {matches}")

class UnknownTool(Exception):
    def __init__(self, name: str, known: list[str]):
        super().__init__(f"unknown tool {name!r}; known tools: {known}")

Here is the resolution layer:

class ToolRouter:
    """Namespaces every tool as <server>.<tool>, dispatches to the right client."""

    def __init__(self, clients: dict):
        self.clients = clients
        self.registry: dict[str, tuple[str, str]] = {}
        for server, client in clients.items():
            for tool in client.list_tools():
                exposed = f"{server}.{tool.name}"
                if exposed in self.registry:
                    raise RuntimeError(f"tool collision: {exposed}")
                self.registry[exposed] = (server, tool.name)

    def resolve(self, name: str) -> tuple[str, str]:
        if "." not in name:
            matches = [t for t in self.registry if t.endswith("." + name)]
            raise AmbiguousTool(name, matches)
        if name not in self.registry:
            raise UnknownTool(name, sorted(self.registry))
        return self.registry[name]

    def call(self, name: str, args: dict, **kw):
        server, tool = self.resolve(name)
        return self.clients[server].call_tool(tool, args, **kw)

Before and after:

# BEFORE -- one flat tool list, no router. Registration order decides:
# the fetch server registered "search" first, so this call runs an
# on-site search during a live fetch. "collection" is silently ignored,
# the result set comes back empty, and the pipeline records
# "no data found" as fact.
call_tool("search", {"q": "pricing", "collection": "docs"})

# AFTER -- explicit namespace; dispatch is deterministic
router.call("store.search", {"collection": "docs", "q": "pricing"})
# -> 3 records from store.example.com
router.call("fetch.search", {"url": "https://example.com", "q": "pricing"})
# -> on-site search executed during a live fetch of example.com

And if a bare name ever does reach the router, resolve() raises AmbiguousTool with the full match list — ['fetch.search', 'store.search'] — instead of guessing. The silent wrong-server dispatch you saw in BEFORE becomes impossible to miss.

The collision check at registration is deliberate. Fail loudly at boot, while the offending server config is one stack trace away — not three weeks later, when a server update quietly introduces a second search and empty results start leaking into storage as legitimate answers.

Isolating Credentials So the Fetch Server Never Holds a Storage Token

The second failure mode is quieter than a collision. With stdio transports, every server is a child process, and a child process holds whatever environment you hand it. The default bootstrap reads like this:

# WRONG -- one flat environment, every secret in every child
load_dotenv()  # FETCH_API_KEY, STORE_TOKEN, everything, into os.environ
for name, spec in cfg["mcp_servers"].items():
    clients[name] = StdioClient(spec["command"], spec["args"], os.environ)

Now the extract server holds the storage bearer token, and so does the fetch wrapper — the one process that talks to the public internet on your behalf. A prompt-injected page, or one over-helpful debug tool, and the storage token leaves the building. This is the incident’s “wrong tools, with credentials it should never have held,” replayed in slow motion.

The fix is construction, not convention. Build each child’s environment from its own spec and nothing else:

import os

def build_env(spec: dict) -> dict:
    """A child gets PATH/LANG plus exactly the env block from its spec."""
    env = {"PATH": os.environ.get("PATH", ""), "LANG": "C.UTF-8"}
    env.update(spec.get("env", {}))
    return env

# in build_clients, replace spec["env"] with:
#   StdioClient(spec["command"], spec["args"], build_env(spec))

Then enforce it at boot, because YAML gets edited by humans:

def assert_no_shared_secrets(cfg: dict) -> None:
    """A credential may live in exactly one server's env block."""
    owner: dict[str, str] = {}
    for server, spec in cfg["mcp_servers"].items():
        for key in spec.get("env", {}):
            if key in owner:
                raise RuntimeError(
                    f"{key} is configured for both {owner[key]!r} and {server!r}; "
                    "each server gets its own credentials or none"
                )
            owner[key] = server

Note what the YAML already does for you: the store server speaks HTTP, so its bearer token rides in headers on the agent side and never enters a child process at all. The rule of thumb is that a server’s environment should contain exactly what that server needs, and nothing you’d mind seeing quoted back from a fetched page.

Stopping the Model From Grabbing a Semantically Close Tool From the Wrong Server

Namespacing fixes dispatch. It does nothing for selection. Asked to “get the current pricing,” the model sees two tools whose descriptions are near-neighbors — fetch.search (“search during a live fetch”) and store.search (“search stored records”) — and “stored records” is close enough when you’re three prompts deep. The call succeeds. The answer is yesterday’s cache, delivered with the same confidence as a live scrape. That’s the third failure mode: no crash, no error, semantically wrong tool.

Two defenses. First, description hygiene — say the negative space explicitly:

TOOL_HINTS = {
    "fetch.search": "On-site search during a live fetch. Current content. Args: url, q.",
    "store.search": "Queries records already written to storage. Never fetches pages. Args: collection, q.",
}

The stronger defense is making wrong arguments cheap to recover from. An exception unwinds the run and the model never sees the message. A structured error is an ordinary tool result: the model reads it, fixes the arguments (or switches tools), and retries. Hook validation into ToolRouter.call:

ARG_SCHEMAS = {
    "fetch.scrape":   {"required": ["url"], "types": {"url": str}},
    "fetch.search":   {"required": ["url", "q"], "types": {"url": str, "q": str}},
    "extract.fields": {"required": ["html", "schema"], "types": {"html": str, "schema": dict}},
    "store.search":   {"required": ["collection", "q"], "types": {"collection": str, "q": str}},
    "store.upsert":   {"required": ["collection", "record"], "types": {"collection": str, "record": dict}},
}

def validate(args: dict, schema: dict) -> dict | None:
    """Return a structured error dict, or None when args conform."""
    missing = [f for f in schema["required"] if f not in args]
    if missing:
        return {
            "error": "invalid_arguments",
            "message": f"missing required field(s): {', '.join(missing)}",
            "required": schema["required"],
        }
    for field, expected in schema["types"].items():
        value = args.get(field)
        if value is not None and not isinstance(value, expected):
            return {
                "error": "invalid_arguments",
                "message": f"field {field!r} must be {expected.__name__}",
                "required": schema["required"],
            }
    return None

class ValidatedRouter(ToolRouter):
    """ToolRouter that validates args and returns structured errors."""

    def __init__(self, clients: dict, schemas: dict[str, dict]):
        super().__init__(clients)
        self.schemas = schemas

    def call(self, name: str, args: dict, **kw):
        server, tool = self.resolve(name)
        schema = self.schemas.get(name)
        if schema is not None:
            err = validate(args, schema)
            if err is not None:
                return {"tool": name, **err}
        return self.clients[server].call_tool(tool, args, **kw)

In practice, the wrong-server calls from the incident get caught right here, on the first retry:

router = ValidatedRouter(clients, ARG_SCHEMAS)

# the model reached for the live fetch but sent the store's argument shape
router.call("fetch.search", {"collection": "docs", "q": "pricing"})
# -> {'tool': 'fetch.search', 'error': 'invalid_arguments',
#     'message': "missing required field(s): url", 'required': ['url', 'q']}

The End-to-End Pipeline: Fetch, Extract, Store

The three fixes compose into one function. Fetch a page through the scraping wrapper, extract price fields locally, validate against a schema, and upsert to storage — with every failure mode handled at its choke point. The extraction schema, verbatim Python:

PRICE_SCHEMA = {
    "type": "object",
    "properties": {
        "url":      {"type": "string"},
        "title":    {"type": "string"},
        "price":    {"type": "number"},
        "currency": {"type": "string"},
    },
    "required": ["url", "title", "price", "currency"],
}

TYPE_MAP = {"string": str, "number": (int, float)}

def check_record(record: dict, schema: dict) -> dict | None:
    """Validate an extracted record against a JSON-style schema."""
    missing = [f for f in schema["required"] if f not in record]
    if missing:
        return {"error": "extraction_incomplete",
                "message": f"missing field(s): {', '.join(missing)}"}
    for field, spec in schema["properties"].items():
        expected = TYPE_MAP.get(spec.get("type", ""))
        if expected and not isinstance(record[field], expected):
            return {"error": "extraction_invalid",
                    "message": (f"field {field!r} expected {spec['type']}, "
                                f"got {type(record[field]).__name__}")}
    return None

The pipeline itself is three calls and a schema:

def run_pipeline(router: ValidatedRouter, url: str) -> dict:
    """fetch -> extract -> validate -> store for one page."""
    page = router.call("fetch.scrape", {"url": url})
    if "error" in page:
        return {"stage": "fetch", **page}

    extracted = router.call(
        "extract.fields", {"html": page["html"], "schema": PRICE_SCHEMA}
    )
    if "error" in extracted:
        return {"stage": "extract", **extracted}

    record = {"url": url, **extracted["record"]}
    problem = check_record(record, PRICE_SCHEMA)
    if problem is not None:
        return {"stage": "validate", **problem}

    return router.call("store.upsert", {"collection": "prices", "record": record})

Wire it up and run it:

cfg = load_config()                 # the YAML from the architecture section
assert_no_shared_secrets(cfg)
clients = build_clients(cfg)
router = ValidatedRouter(clients, ARG_SCHEMAS)

print(run_pipeline(router, "https://example.com"))

Happy path:

{'status': 'stored', 'id': 'rec_01J9XQ2W',
 'record': {'url': 'https://example.com', 'title': 'Example Domain',
            'price': 12.0, 'currency': 'USD'}}

And when something is wrong, the result says which stage and which field, instead of storing an empty record as fact:

# extractor came back short -- pipeline stops before storage
{'stage': 'validate', 'error': 'extraction_incomplete',
 'message': 'missing field(s): price'}

Each failure from the incident now has a choke point. Collisions die at boot, in the registry. Credentials never cross server boundaries, because no child environment contains another server’s keys. Wrong-tool calls come back as structured errors with the required arguments attached, so the model corrects itself on the next turn instead of writing “no data found” into storage. Three servers, three transports, one routing layer — and none of the servers needs to know the others exist. Copy the blocks in order — config, build_clients, exceptions, ToolRouter, build_env, validate, ValidatedRouter, PRICE_SCHEMA, run_pipeline — and it runs as written.

#mcp #ai-agents #tool-routing #multi-server #agent-architecture #slot:mcp-agent

Related Articles