·

Best Practices For Multi-MCP Architectures

Learn the guardrails that keep multi-MCP agents reliable: scoping permissions, managing tool overlap, and avoiding runaway tool calls.

The workflows in this module each combined two or three servers for a specific job. In practice, teams that adopt this pattern tend to keep adding servers to the same session — Confluence for docs, Slack for notifications, Datadog for metrics — until the original well-scoped setup has quietly become a dozen connected servers with overlapping credentials and no one who could explain the full permission surface from memory. This closing topic is about the decisions that keep a multi-MCP setup from decaying into that state: which servers actually belong together, how to keep API usage and cost under control as tool-calling volume grows, how to apply least privilege per connection rather than per session, and how to actually observe and test a system built this way.

None of this is theoretical caution. Every pattern below responds to a specific failure mode that shows up within weeks of a team scaling from "one MCP server for a demo" to "five MCP servers in daily use."


Choosing Which MCP Servers to Combine for a Given Workflow

The temptation once you've connected two servers successfully is to connect everything you might conceivably need, "just in case," in one long-lived session. Resist it — every additional connected server is context-window overhead (Topic 1 of this module covers the mechanics) and additional attack surface, whether or not it gets used this session. The right question isn't "could this server be useful here" but "does this specific workflow's data actually need to cross this specific boundary."

A useful filter: combine servers when the workflow genuinely requires information or actions to cross a system boundary — GitHub's diff informing a Jira ticket's description, Sentry's stack trace informing a GitHub fix. Don't combine servers just because both happen to be relevant to the same broad domain. A "customer support" session doesn't need Slack, Zendesk, GitHub, Datadog, and Confluence all connected simultaneously just because a support engineer's job touches all five systems over the course of a week — it needs whichever two or three are relevant to the specific ticket in front of them right now.

claude --mcp-config sentry-github.mcp.json

claude --mcp-config everything.mcp.json

Maintaining multiple scoped MCP config files — one per workflow shape, rather than one config with every server your team has ever connected — costs a small amount of setup discipline and pays for itself in both context budget and blast radius every single session. Project-scoped .mcp.json files can also be workflow-specific and checked into different directories or invoked explicitly, rather than one team-wide config everyone inherits regardless of task.

// sentry-github.mcp.json — scoped to the bug-fix workflow specifically
{
  "mcpServers": {
    "sentry": { "command": "npx", "args": ["-y", "@sentry/mcp-server"] },
    "github": { "command": "npx", "args": ["-y", "@github/mcp-server"] }
  }
}

Also weigh server maturity and maintenance status before adding one to a standard workflow — this course covers official or well-maintained community servers, but the MCP ecosystem has plenty of early-stage or single-maintainer servers with thin test coverage. A server you'd hesitate to depend on for a personal project is a worse candidate for a workflow other engineers on your team will run unsupervised.

Tips
- Combine servers based on genuine cross-system data dependency in the specific workflow, not general domain relevance — "support engineers use five systems" doesn't mean a support session should have five servers connected at once.
- Maintain multiple scoped MCP config files per workflow shape instead of one config with every server ever adopted — the discipline cost is small, and it caps both context overhead and blast radius per session.
- Weigh a candidate server's maturity and maintenance status before standardizing on it for team workflows — an official server backed by the vendor is a different risk profile than a single-maintainer community project, even if both expose similar tools today.


Rate Limiting, API Quotas, and Cost Management in Multi-MCP Setups

Every MCP server call is a real API call against the underlying service's own rate limits, and those limits don't know or care that the caller is an AI agent rather than a human clicking through a UI. GitHub's REST API caps authenticated requests at 5,000/hour per token by default; Jira Cloud's rate limits vary by endpoint and plan but commonly sit in the low thousands per hour; Sentry and Figma each have their own ceilings. An agent looping through a batch operation — triaging 200 issues, snapshotting a dozen pages repeatedly during a Playwright debugging session — can burn through an hourly quota fast enough to lock out human use of the same token for the rest of the hour.

> for every open issue in this repo, check for duplicates against
  every other open and closed issue

> for issues opened in the last 7 days only, check for duplicates
  against open issues from the last 90 days

Bounding batch operations explicitly in the prompt — a date range, a max count, a "stop after N calls and report progress" instruction — isn't just about correctness (Topic 2's smaller-batch reasoning applies here too), it's a rate-limit safety measure. A model given free rein to "check everything" will make as many calls as the task seems to require, with no innate sense of your account's hourly ceiling.

Cost compounds in a second, less visible way in multi-MCP sessions specifically: every tool result that comes back gets folded into context and re-sent to the model on every subsequent turn until it's compacted out. A verbose Sentry stack trace, a large Playwright accessibility snapshot, and a full GitHub diff all sitting in context simultaneously — because a five-server workflow pulled all three in the same session — multiplies your per-turn token cost, not just your one-time tool-call cost. This is a real line item at scale, not a rounding error, once a team runs these workflows dozens of times a day.

> get just the top 3 frames of the stack trace, not the full trace —
  that's enough to locate the culprit file

Track actual usage, not assumed usage, especially in the first weeks of standardizing a multi-MCP workflow across a team:

> what's my current GitHub API rate limit status?
Rate limit: 4,213 / 5,000 remaining, resets in 34 minutes

Several MCP servers (Sentry, Jira Cloud) bill or throttle based on API call volume as part of your existing plan — a team enthusiastically automating five workflows across MCP can shift usage patterns enough to matter for capacity planning on the underlying service, independent of anything Claude-specific. Loop in whoever owns those platform relationships before scaling a workflow from "one engineer's experiment" to "the whole team's default."

Tips
- Bound every batch or loop-shaped operation explicitly in the prompt — a date range, a max item count, an instruction to report progress and stop — rather than trusting the model to self-limit against a rate ceiling it has no visibility into.
- Ask for scoped, summarized tool results instead of full dumps wherever the workflow allows it — a full stack trace or full diff sitting in context for the rest of a long session is a real per-turn cost multiplier, not a one-time expense.
- Check actual rate-limit and quota status rather than assuming headroom, and loop in whoever owns the underlying platform relationship (GitHub, Jira, Sentry) before scaling a multi-MCP workflow from one engineer's habit to a team-wide default.


Applying Least-Privilege Security to Each MCP Connection

Every workflow in this module scoped its credentials to one repo, one project, one Jira site — that discipline gets harder to maintain, not easier, as the number of connected servers grows, because it's tempting to reach for one broad token that "just works everywhere" instead of provisioning a scoped one per server per workflow. Resist that temptation specifically because multi-MCP sessions are where a single over-broad credential does the most damage — a token compromised or misused in a five-server session has five servers' worth of blast radius instead of one's.

The concrete practice, restated per credential type across this module's servers:





Permission-layer discipline (the allow/ask/deny structure from Topic 1) needs the same treatment scaled across every server, not just the one you set up first. It's common to see a team's .claude/settings.json carefully lock down GitHub's merge_pull_request while leaving Jira's delete_issue or transition_issue completely unrestricted, simply because GitHub was the first server they hardened and Jira was added later without revisiting the pattern.

{
  "permissions": {
    "deny": [
      "mcp__github__merge_pull_request",
      "mcp__github__delete_repository",
      "mcp__jira__delete_issue",
      "mcp__sentry__delete_project",
      "mcp__figma__delete_file"
    ],
    "ask": [
      "mcp__github__create_pull_request",
      "mcp__jira__create_issue",
      "mcp__jira__transition_issue",
      "mcp__sentry__resolve_issue"
    ]
  }
}

Audit this list explicitly every time a new server joins a shared config — treat it as a checklist item in the same PR that adds the server, not a follow-up task that gets deprioritized once the new integration is "working."

Tips
- Scope every credential — GitHub PAT, Jira token, Sentry auth token — to the single repo, project, or org the specific workflow needs, and revisit that scope explicitly whenever the workflow's actual needs change, rather than widening a token preemptively "to be safe."
- Extend the same allow/ask/deny rigor to every newly added server's destructive or high-consequence tools, not just the first server you hardened — an unreviewed default-allow on a newer server is the same risk as a wide-open PAT, just less visible.
- Treat Playwright MCP's browser context as carrying real credential-equivalent state (session cookies) even though it's not a token — never let a session mix production auth state with non-production testing without an explicit reset in between.


Observability and Testing Strategies for Multi-MCP Agent Workflows

A single-server session's failure mode is usually visible immediately — a tool call errors, you see it. A multi-MCP workflow's failure mode is often silent and compounding: a wrong Jira key propagates into a GitHub PR body, which propagates into a Sentry comment, and by the time anyone notices, three systems have a slightly wrong cross-reference that's now part of the historical record. Observability for these workflows means catching that kind of propagated error early, not just catching outright tool-call failures.

Build a verification checkpoint into every workflow at the point where data crosses from one server into another — this is worth treating as a standing pattern across every workflow in this module, not a one-off caution:

> before creating that Jira comment, show me exactly what PR URL and
  PR number you're about to reference — I want to confirm it matches
  the PR we just opened

For workflows run repeatedly rather than once, an external audit trail (Topic 1's suggestion of a log file or webhook) becomes a genuine testing asset, not just a debugging convenience — it lets you spot-check a sample of runs after the fact for the kind of subtle cross-reference drift that's hard to catch in the moment but easy to catch in aggregate:

> after this workflow completes, append a line to
  ./workflow-audit.jsonl with: timestamp, workflow name, every
  cross-referenced ID involved (Jira key, PR number, Sentry issue ID),
  and a boolean for whether each reference was verified before use
{"ts":"2026-08-20T11:02:00Z","workflow":"sentry-to-github","jira_key":null,"pr_number":231,"sentry_id":"WEBAPP-PROD-2C4F","verified":true}

Periodically reviewing a sample of these logs — even ten minutes a week — surfaces drift patterns a single session's spot-check never would: maybe transitions to "Done" are consistently happening before deploy confirmation despite the prompt saying otherwise, or a particular server's results are getting truncated in a way that's silently producing incomplete PR descriptions.

For testing before rollout, treat a new multi-MCP workflow the same way you'd treat a new piece of production automation — because that's what it is. Dry-run it against a low-stakes target (a scratch repo, a test Jira project, a non-production Sentry project) before turning it loose on real tickets and real code, and have a second person review the first few real runs rather than trusting the design alone.

> run the full Sentry-to-GitHub workflow against
  acme/webapp-sandbox and a test Sentry project first,
  using a seeded error, before we point this at real production alerts

Be honest about the limits of this kind of testing, too: a dry run in a sandbox repo won't surface every failure mode a real production alert with real breadcrumb complexity will. Treat the first several real runs as still being under a closer degree of human review than you'll eventually settle into, and loosen that review cadence deliberately as the workflow proves itself — not by default inertia.

Tips
- Insert an explicit verification checkpoint at every point where one server's output feeds into another server's call — this is where silent, compounding errors (a wrong ID propagated across three systems) actually originate, and it's cheap to catch there and expensive to catch later.
- Log cross-referenced IDs to an external audit trail for repeated workflows, and actually review a sample of it periodically — the value is in catching drift patterns that no single session's spot-check would reveal.
- Dry-run any new multi-MCP workflow against sandbox resources before production use, then keep closer human review on the first several real runs than you expect to need long-term, and relax that cadence deliberately once the workflow has actually earned the trust.


Tips

Tips
- Connect servers per workflow based on genuine cross-system data need, not general domain relevance — maintain scoped configs per workflow shape rather than one config carrying every server the team has ever adopted.
- Bound batch operations explicitly and ask for scoped tool results to manage both real API rate limits and the compounding context-token cost of running several servers in one long session.
- Apply least-privilege scoping to every credential across every connected server, and extend the same allow/ask/deny rigor to each new server as it joins — this discipline degrades by default as server count grows, not by accident.
- Build verification checkpoints where data crosses server boundaries, maintain an external audit trail for repeated workflows, and dry-run new multi-MCP automation against sandbox resources with closer human review before trusting it at production scale.