DEV Community: QuietDesk Studio

The MCP Redirect URI Edge Cases Dynamic Client Registration Doesn't Save You From

QuietDesk Studio — Tue, 06 Oct 2026 18:17:23 +0000

Scope of this post

This is not another "what is redirect_uri_mismatch" explainer. I already wrote the desktop-client version of that bug elsewhere on this blog — localhost vs 127.0.0.1, ephemeral local callback servers, the basics.

This post covers a narrower, later-stage problem: the redirect URI and session bugs that show up after you've already implemented Dynamic Client Registration (DCR) correctly. Teams ship DCR, watch the happy path work in testing, and then get paged three weeks later when a client that authenticated fine on day one suddenly can't.

What's explicitly not here:

Basic redirect URI string-matching mistakes (covered already)
PKCE and authorization server discovery mechanics (separate post, already covered)
Full session-store architecture, revocation policy, and multi-tenant client registries — that's the production-hardening layer, and it's dense enough that it lives in the paid pack, not a blog post

If you're still debugging "my redirect_uri doesn't match," stop here and go fix that first. This post assumes DCR is working.

Why DCR doesn't actually solve the redirect URI problem — it relocates it

Dynamic Client Registration feels like it should end redirect URI pain: the client registers itself, the server echoes back an accepted redirect_uris list, done. In practice, DCR just moves the trust boundary from "a human configured this URI once" to "two independent systems have to agree on an exact string, indefinitely, across restarts, redeploys, and port changes." That's a harder problem, not an easier one, and real issue trackers are full of it right now.

Here are five specific failure modes that show up after DCR is "working," ranked by how often they actually page someone.

Gotcha #1: The authorization endpoint disagrees with the registration endpoint

The most confusing version of this bug is when registration succeeds but authorization rejects the exact same URI moments later. One recent report against Tableau's MCP server showed exactly this: client registration succeeds via Dynamic Client Registration, but the authorization endpoint rejects the exact same redirect URI that was previously accepted during registration, even though the redirect URI used during authorization appears to be identical to the redirect URI accepted during dynamic client registration.

That's not a client bug. It's two code paths on the server — the register handler and the authorize handler — validating against different sources of truth (a cache vs. a database, a normalized string vs. a raw one). If you're building the server side, the fix is to make both endpoints read from the same canonical store, not two independently-maintained allowlists.

Gotcha #2: Loopback redirect URIs work for CLIs, except when the provider doesn't trust loopback at all

For native/CLI clients, convention is to register a loopback URI like http://127.0.0.1:<random-port>/callback. Most authorization servers accept this per spec. Some don't. A recent Atlassian MCP integration report shows the authorization server flatly refusing it: loopback (127.0.0.1) redirect URIs registered via dynamic client registration should be accepted for local/CLI OAuth flows, but Atlassian's authorization server rejects the redirect URI as not registered for the dynamically-registered client, blocking authentication entirely.

If you're building an MCP client that targets third-party servers, don't assume loopback-via-DCR is universally supported — some providers require a pre-registered static client with a fixed redirect URI instead, and your fallback path needs to exist before a user hits this in production, not after.

Gotcha #3: Stale client registrations die silently, and nothing tells the client to re-register

This is the one that pages people weeks after launch, not during testing. When an identity provider redeploys, migrates its database, or rotates its OAuth backend, dynamically-registered clients can simply stop existing server-side — while the local cache of that client's credentials looks perfectly healthy. One report against an agent framework described this precisely: when an MCP server's dynamically-registered OAuth client becomes invalid server-side (e.g. IdP redeploy, DB migration, rebrand), the client continues to present the dead client_id indefinitely, and the IdP rejects it with 'Redirect URI Mismatch', and the agent does not detect this condition or re-run dynamic client registration. The giveaway that it's not a token problem: the cached refresh tokens are still valid for years into the future — the breakage is purely the registered client, not the credentials it holds.

The practical fix: your client needs to treat invalid_client / "redirect URI not registered" as a distinct error class from invalid_grant / expired token, and respond by re-running DCR from scratch, not by refreshing a token that was never the problem.

Gotcha #4: `client_uri` origin-matching breaks tools that proxy through a different domain than they authenticate from

Some authorization servers enforce that the optional client_uri metadata field shares an origin with your registered redirect_uri — a reasonable anti-phishing check that quietly breaks tools built for flexibility. One widely-used MCP debugging tool hit this directly: strict OAuth providers reject the configuration with error "client_uri must have the same origin as a redirect_uri," because the redirect_uri uses the current local origin while client_uri points to an unrelated domain.

If you're writing a server that enforces this check, document it loudly in your registration error response — "client_uri origin must match redirect_uri origin" is a one-line fix for integrators once they know it's required. If you're writing a client, default client_uri to the same origin as your redirect URI unless you have a specific reason not to.

Gotcha #5: Session binding that happens after the OAuth handshake, not during it

This is the subtlest one and it's specifically a session issue, not a redirect issue — but it gets mistaken for a redirect bug constantly because the symptom is identical: the user completes auth successfully, gets a valid token, and tool calls still fail. A conformance tooling doc for MCP lists this as its own distinct failure class: token audience mismatch (OAuth flow succeeds but tools/list returns 401 because aud doesn't match the MCP resource URL), scope mismatch (token issued but the tool handler requires different scopes), and session binding, where some servers require a separate session init after auth.

If your MCP server requires a distinct session-initialization call after the OAuth code exchange, a client that treats "got a valid token" as "ready to call tools" will silently fail on its first real request. The redirect URI did its job correctly — the bug is one layer downstream, in session lifecycle, and it's easy to misdiagnose as yet another OAuth config error.

What this post deliberately doesn't solve

Each of these five gotchas has a narrow, specific fix at the code level, which is what I covered above. What none of them answer on their own is the bigger operational question: how do you design a client registration store that survives IdP redeploys, how do you version and rotate client secrets without an outage window, how do you build a test suite that catches "authorize endpoint disagrees with register endpoint" before a real user hits it, and how do you scope session permissions so a stale or hijacked client can't silently reuse another caller's authorization. That's exactly the gap between "I fixed the bug I saw in the logs" and "I'd trust this in front of real traffic" — and it's the part that doesn't compress into a blog post.

If you're building toward that production bar, the AI Agent Incident Postmortem & Permission-Scoping Template Pack gives you a structured way to document exactly these kinds of auth and session failures when they happen, plus the permission-scoping templates to limit blast radius the next time a client registration goes stale or a session gets bound to the wrong caller.

The one-line takeaway

DCR doesn't end your redirect URI problems — it just moves them from "did I type the URI correctly" to "do my registration and authorization code paths agree, does my client know how to tell a dead registration from an expired token, and does my session lifecycle actually match what my OAuth flow assumes it does." Fix those four questions explicitly, and most of what looks like a mysterious OAuth bug turns out to be a one-line diagnosis.

Written with AI assistance and reviewed for accuracy.

The MCP Load & Resilience Checklist: What This Covers, and What It Deliberately Doesn't

QuietDesk Studio — Thu, 01 Oct 2026 21:15:02 +0000

A few weeks back I wrote about rate-limiting and backoff patterns for MCP servers under load. The feedback that came back wasn't "give me more backoff code" — it was "okay, but how do I know when I'm actually done? What's the full list I check before I say this server can take real traffic?"

That's a fair question, and it's also a trap. The honest answer is that "production-ready" isn't one checklist — it's several, covering different failure domains, and the posts that try to cram all of them into one listicle end up shallow on every single item. So this piece does one thing: it covers load and resilience — the specific question of whether your server degrades gracefully or falls over when traffic spikes, retries pile up, or a downstream dependency gets slow.

It does not cover authentication, OAuth token handling, tool permission scoping, or incident response after something breaks. Those are real, separate checklists with their own failure modes, and bolting them onto this one would make all of them worse. If you need that ground covered, that's exactly what our AI Agent Incident Postmortem & Permission-Scoping Template Pack is for — it's the companion piece for the "something went wrong, now what" and "who's allowed to call this tool" questions this post intentionally skips.

Why scope matters here specifically

MCP sits in an unusual spot: the caller isn't a human clicking slowly, it's an agent that can retry a failed call in milliseconds and doesn't get bored. A load checklist for a normal REST API assumes human-paced traffic with occasional bursts. An MCP server has to assume an agent that, on a bad day, will call the same tool in a tight loop because its reasoning told it the first nine calls "almost worked."

That's the specific risk this checklist is built around. It's not a general "is my API fast" checklist — it's "will this server survive an agent that doesn't know when to stop."

The checklist: 10 items, four phases

Phase 1 — Limits (before traffic exists)

1. Per-tool rate limits, not just per-connection. A global rate limit protects your server from one noisy client. It does nothing to stop a single agent from hammering your most expensive tool while staying under the global cap. Set limits per tool, per session.

2. A documented maximum concurrency per session. Decide how many in-flight tool calls one session is allowed to have before you start queuing or rejecting. If you haven't picked a number, the number is "however many the agent sends," which is not a number you want to discover in production.

3. Timeouts on every external call the tool makes, not just the top-level request. A tool that calls three downstream services needs three timeout budgets, not one umbrella timeout that masks which dependency actually hung.

Phase 2 — Backoff and retry behavior (during a spike)

4. Your server returns a retry signal the agent can actually use. A bare 429 or 503 with no Retry-After header just teaches the agent to retry immediately, which is the opposite of what you want under load.

5. You've tested what happens when the agent ignores the backoff signal. Some clients respect Retry-After. Plenty don't, especially home-grown agent loops. Your server's behavior under a client that retries immediately anyway is the real test, not the happy path where everyone cooperates.

6. There's a circuit breaker on your slowest downstream dependency. If one backend call starts timing out, the server should stop sending it traffic for a cooldown window instead of queuing requests behind a dependency that's already failing.

Phase 3 — Degradation (when limits are hit)

7. You've decided what "degraded" looks like, and it's not silence. When a rate limit kicks in, does the agent get a clear, structured error it can reason about, or does the connection just hang until it times out client-side? The second one looks like a bug to whoever's debugging it a week later.

8. Queue depth has a ceiling. An unbounded queue in front of a slow tool doesn't prevent failure, it just delays it and makes the eventual failure bigger. Pick a max queue size and reject past it with a clear error.

Phase 4 — Verification (before you trust any of the above)

9. You've actually load-tested with concurrent sessions, not just concurrent requests from one session. These look similar on a chart and behave completely differently in practice — session-level state (locks, in-memory caches, connection pools) often breaks only under genuine multi-session concurrency.

10. You know your p95 latency under load, not just your average. An average that looks fine can hide a long tail where 5% of calls take 10x as long — and that tail is exactly where agent timeouts and retry storms start.

The gotcha that isn't in the generic guides

Here's the one that catches people who've done everything above correctly: backoff signals only work if your transport actually passes them through. If you're running MCP over a reverse proxy or a load balancer with its own retry logic, your carefully-tuned Retry-After header can get stripped or overridden before it reaches the client. Test the full path — agent to proxy to server and back — not just the server's response in isolation. This is the kind of thing that works perfectly in a local test and silently breaks the moment there's infrastructure in between.

What's deliberately out of scope here (and where it lives)

To be specific about the boundary, this checklist does not cover:

Token validation and scope enforcement — that's an auth checklist, not a load one.
What happens after a rate-limit abuse pattern turns out to be a compromised or over-permissioned agent — that's an incident-response and permission-scoping problem, and conflating it with load handling is how teams end up with checklists nobody can actually use as a definition of done.
Logging and tracing setup — necessary for diagnosing load issues after the fact, but it's its own piece of work with its own checklist.

If you're past the load question and into "how do we write down what happened and lock down permissions so it doesn't happen again," that's the gap our permission-scoping and incident postmortem template pack is built to close — it gives you a structured format for the postmortem itself and a worksheet for tightening scopes afterward, rather than starting from a blank doc at 2am.

Using this as a definition of done

Treat the 10 items above as pass/fail, not as "mostly handled." A server that passes 8 of 10 doesn't fail gracefully 80% of the time — it fails exactly the same way, just slightly less often, which is a worse debugging experience because the failure looks rare instead of systemic. Run through all 10 before you call a server load-tested, and keep the list next to your deploy checklist so the next server doesn't start the conversation from zero.

Written with AI assistance and reviewed for accuracy.

Rate-Limiting and Backoff Patterns for MCP Servers That Don't Fall Over Under Load

QuietDesk Studio — Wed, 30 Sep 2026 20:45:01 +0000

A team I talked with last quarter had an agent stuck in a loop calling the same tool for eight hours. By the time someone noticed, it had run up a five-figure cloud bill. That's not a hypothetical — a runaway automation loop making 127,000 API calls in roughly 8 hours has been reported to cost around $47,000 in a single incident. No rate limiter, no circuit breaker, nothing between the agent and the API meter.

This post covers how to design rate limiting and retry/backoff for an MCP server so a stuck agent gets stopped cheaply instead of expensively. It does not cover OAuth token refresh (see my earlier post on that gotcha) or full observability setup — that's a separate piece. Scope here: what layer to rate-limit at, how to return a 429 an agent can actually act on, and the one retry mistake that causes most MCP production outages.

Why "just add exponential backoff" isn't the fix

Most teams stop at client-side retry logic and call it done. That's table stakes, not a solution — it protects against transient blips but does nothing for structural overload, and it can make things worse if you get the placement wrong.

The failure mode that actually takes MCP servers down in production isn't "no backoff." It's cascading retries inside a single agent turn: the model calls a tool, gets a 429, the MCP server retries internally with backoff, and while that retry is still pending, the same agent turn calls a second tool that hits the same upstream bucket. Now you have two retry loops racing on one quota, and bucket recovery ends up taking the longer of the two backoff schedules instead of either one alone.

The fix isn't fancier backoff math. It's not retrying inside the server at all for agent-facing calls — bubble the 429 straight back to the model with a clear, structured error and a wait-time hint, and let the agent decide whether to wait, switch tools, or tell the user. Retrying silently inside the server hides the real signal from the one thing (the agent's reasoning loop) that's actually in a position to stop calling the same tool five more times in the next two seconds.

Pick the layer you're actually rate-limiting

"Rate limit the server" is underspecified. There are at least three layers, and conflating them is how teams end up instrumenting one and getting blindsided by the other two:

Layer	What it controls	Good for
Transport / connection	Requests per second, globally or per-session	Simple, predictable backpressure; easy to reason about
Tool / token budget	Cost-weighted limits per tool call	Tools with wildly different execution cost (a 1-second lookup vs. a 10-second batch job)
Tenant / credential	One bucket per (tenant, upstream API) pair	Multi-tenant setups where one shared OAuth credential serves many customers

The tenant layer matters more than it looks. If one OAuth credential is shared across customers, the first agent to get throttled can trigger a cascade where every other session behind that same credential inherits the block — sometimes within twenty seconds of the first call. Per-tenant token buckets contain the blast radius; the credential model underneath decides how big that radius is in the first place. If you're issuing one shared API key to a backend that serves 40 tenants, your rate limiter needs to know about tenants, not just requests.

A token bucket you can actually reason about

Token bucket is the right primitive for most MCP tool-call limiting because it allows bursts (a legitimate agent batch-processing 10 items) while still capping sustained rate.

import time
import asyncio

class TenantTokenBucket:
    def __init__(self, capacity: int, refill_per_sec: float):
        self.capacity = capacity
        self.tokens = capacity
        self.refill_per_sec = refill_per_sec
        self.last_refill = time.monotonic()
        self.lock = asyncio.Lock()

    async def try_consume(self, cost: int = 1) -> bool:
        async with self.lock:
            now = time.monotonic()
            elapsed = now - self.last_refill
            self.tokens = min(
                self.capacity,
                self.tokens + elapsed * self.refill_per_sec
            )
            self.last_refill = now
            if self.tokens >= cost:
                self.tokens -= cost
                return True
            return False

Two details that matter and are easy to skip:

It's async and lock-guarded. MCP's streaming architecture means a single slow tool call can block the event loop if your limiter isn't async-aware — you'll end up deadlocking clients that are just waiting on a response, which looks like a hang, not a rate limit.
cost is a parameter, not always 1. A tool that fans out into five upstream calls should consume five tokens, not one. Flat per-request limiting wastes budget on cheap calls and underprices expensive ones.

Returning a 429 the agent can act on

A rate limit is only as useful as the signal it sends back. The common failure is a bare 429 with no machine-readable guidance — the client has no idea whether to wait 500ms or 5 minutes, so it does something arbitrary, usually retrying immediately and making things worse.

Structure your rate-limit error so the agent (not a human reading logs) can parse it:

{
  "error": {
    "code": "rate_limited",
    "message": "Tool call rate limit exceeded for this session",
    "retry_after_ms": 4200,
    "scope": "tenant:acme-corp:tool:search_invoices"
  }
}

The retry_after_ms field is doing the real work — it tells the agent's retry logic exactly how long to back off instead of guessing. And if an upstream API sends you a Retry-After header, treat it as a mandatory floor, not a suggestion. Some APIs enforce hard cool-downs (Airtable's 30-second window is a well-known example), and retrying before that window closes just resets the clock.

The backoff schedule itself

For the retries that do belong in your code (agent-to-tool retries, not the cascading server-side kind above), a schedule that shows up consistently in production guidance:

Start at 500ms
Double on each retry, capped at 30 seconds
Add ±20% jitter so multiple sessions recovering from the same outage don't all retry in the same instant (thundering herd)
Never go tighter than 500ms — anything faster just looks like a burst to the very limiter you're trying to respect

Catching stuck agents before they trip the limit

A rate limiter protects your server, but it doesn't fix the agent that's stuck in a loop — it just makes the loop cheaper. Worth adding separately: if a session calls the same tool with identical arguments more than a handful of times in a row, that's a strong signal of a stuck agent, not legitimate traffic. A real agent varies arguments between calls (different IDs, different queries); a stuck one repeats the exact same call. Flagging that pattern and returning a hard stop (not just a slower retry) is cheaper than waiting for the token bucket to catch it call-by-call.

What's in the pack

Rate limiting is one piece of a much longer list — session handling, timeout budgets, error taxonomy, and the pre-launch checks that catch this stuff before it's live. The rest is in the pack: the AI Agent Incident Postmortem & Permission-Scoping Template Pack has the incident-response templates for when a rate limit does get bypassed and something runs away anyway — scoped permission worksheets and a postmortem template built specifically for agent tool-call incidents, not generic infra outages.

If you're shipping an MCP server this month, the combination that actually holds up under load is: tenant-scoped token buckets, structured 429s with retry_after_ms, no server-side retries on agent-facing calls, and a separate stuck-loop detector that doesn't wait for the bucket to empty. Everything else is tuning.

Written with AI assistance and reviewed for accuracy.

The MCP Session Refresh Gotcha: Why "Token Expired" and "Session Expired" Are Not the Same Bug

QuietDesk Studio — Tue, 29 Sep 2026 20:44:00 +0000

The bug report that keeps repeating itself

Scan enough MCP issue trackers and you'll notice the same shape of bug filed against a dozen different clients and servers: Copilot CLI, Gemini CLI, Cursor, Open WebUI, Codex, and several homegrown gateways. The symptom is always some version of "it worked, then it silently stopped working, and the only fix was to log in again."

The root cause is almost never "OAuth is broken." It's that two independent clocks — the access token's expiry and the MCP session's lifetime — get treated as one clock, and the recovery logic for one gets applied to the other.

That distinction is the entire subject of this post.

Scope: what this covers and what it doesn't

This post is narrowly about keeping a connection alive after the initial handshake — refreshing tokens and re-initializing sessions without forcing a user back through a browser. It assumes you already have PKCE, discovery, and initial token validation working (covered in an earlier post in this series). It does not cover setting up dynamic client registration or scopes — that's a separate problem with a separate fix.

Phase 1: Understand that you have two clocks, not one

OAuth token expiry and session expiry are unrelated. An expired token gives you 401 and needs a refresh; an expired session gives you 404 and needs a re-initialize. The session itself, per spec, is a correlation and state handle. It carries no lease, no expiry timestamp and no promise about how long it stays valid. Nothing in the lifecycle specification obliges a server to keep it alive for any period at all.

So you're managing two independent failure modes with two independent recoveries, and most of the bugs above come from collapsing them into one.

Phase 2: Correctly classify the failure before you react

The spec's intent is clean: If a server has ended a session, requests carrying the old id must receive HTTP 404. The client's required response is to discard the id and send a fresh initialize. A 401 means something entirely different — the MCP server acts as an OAuth resource server. The client sends a bearer token on each request, the server validates expiry, scope and audience, and an invalid token gets a 401.

In practice, plenty of servers don't respect this. One real-world rmcp-based server was found answering an unrecognized session ID with 401 Unauthorized: Session not found instead of the spec-mandated 404 — and the consequence is severe: OAuth MCP clients (claude.ai, Claude Code) treat a 401 as an invalid credential: they drop the token and demand an interactive re-auth. A perfectly valid, unexpired token gets discarded because the server picked the wrong status code for a session problem.

If you're building the server, this is the single highest-leverage fix in this whole post: return 404 for unknown/expired sessions, 401 (with WWW-Authenticate) only for actual credential problems, and never conflate the two.

If you're building the client, don't treat every 401 as "burn the token and force login." Distinguish an auth failure from a stale session by checking whether WWW-Authenticate is present, and only discard credentials on a genuine 401 with that header.

Phase 3: Refresh the token — but check the provider actually gave you one

This is where a surprising number of teams get stuck before refresh logic even runs. Several identity providers don't issue a refresh token unless you explicitly ask:

Google: Google OAuth issues a refresh token only when the authorization request includes access_type=offline (typically with prompt=consent). This is a Google-specific query parameter, not part of OAuth scope negotiation. Google does not honor offline_access as a scope, so requesting it via the existing scopes config has no effect.
Meta/Facebook-backed servers: one production report found refresh_token is advertised but never issued. Meta's OAuth returns a long-lived access token with no refresh token. So once the client decides the session must be refreshed, there is nothing to refresh with, and the only possible outcome is the message above.
Custom auth servers: a similar bug appeared in the wild where offline_access is required but the engine never tells the client to request it, so every session hard-expires after 7 days.

The fix at the client level: check for a refresh_token field immediately after the initial grant, and fail loudly in development if it's missing — don't wait until a user hits it in production three hours into a session.

Phase 4: Don't let a successful token refresh leave a stale session behind

This is the gotcha most teams never see coming, because the token refresh itself succeeds. A Streamable HTTP transport ties a session ID to the credentials that created it. If you refresh the bearer token but keep reusing the old Mcp-Session-Id, the server sees a mismatch between the session and the token attached to it.

This exact failure was reported against a production MCP integration: after Cursor performs a silent OAuth access-token refresh (near token expiry / refresh flow), the result was Session token does not match bearer token. The only reliable recovery was heavy-handed: Note that only toggling the MCP server off/on, full re-login, or restarting Cursor recovers it. Manual testing confirmed the actual fix is much lighter than a full restart: refreshing the OAuth access token and calling initialize again with the new bearer produces a new Mcp-Session-Id and restores tool calls. Cursor's silent refresh does the token part but skips session re-initialization.

Rule of thumb: a successful token refresh is not a completed recovery on its own. After any refresh, re-run initialize with the new bearer token and accept whatever session ID comes back. Don't assume the old session ID is still valid just because the token now is.

Phase 5: Retry once, with a real circuit breaker — not forever

The last gotcha is about failure discipline. One gateway logged this pattern in production: An MCP server whose credential was never saved is retried forever. Backoff grows to 300 s and then stays there; 18+ failures logged in one session with no circuit breaker, no UI indicator. A 401 caused by a genuinely dead credential is not a transient network blip — retrying it indefinitely just burns cycles and hides the real problem from whoever's on call.

The pattern that actually works, synthesized from several fixes above:

Catch the 401 vs 404 distinction at the transport layer.
On 401 with a refresh token available: refresh once, then re-run initialize, then retry the original call once.
On 404: discard the session ID, re-run initialize with the existing (still-valid) token, retry once.
If refresh itself fails (invalid_grant, no refresh_token, or repeated 401 after a fresh refresh): stop retrying, surface a "needs reauthorization" state, and don't touch the retry loop again until the credential changes.
Log which of these four paths fired. When a session breaks in production, that log line is the difference between a five-minute diagnosis and an hour of guessing.

Why this is worth getting right before launch

None of these five phases are exotic — they're each a handful of lines. But they interact, and the bug reports above show that even mature clients (Cursor, Gemini CLI, Copilot CLI) shipped with at least one of these five phases missing or wrong, and the resulting incident always looked the same to the end user: "the MCP server just stopped working."

If you're running MCP servers in production, this class of failure — auth working perfectly for hours, then a session or refresh edge case taking the whole integration down with a vague error — is exactly the kind of incident worth documenting before it happens, not after. Our AI Agent Incident Postmortem & Permission-Scoping Template Pack gives you a structured way to capture root cause, blast radius, and the permission/session boundaries involved, so the next time a token refresh gotcha slips through, you're writing a five-minute postmortem instead of re-deriving the timeline from scratch.

Written with AI assistance and reviewed for accuracy.

The Desktop Redirect URI Gotcha That Breaks MCP OAuth (And How to Actually Fix It)

QuietDesk Studio — Mon, 28 Sep 2026 16:45:15 +0000

Scope of this post

This is not a general MCP OAuth tutorial. It covers exactly one thing: why desktop MCP clients (Claude Desktop, Cursor, Claude Code, custom native apps) fail during the redirect step of OAuth, and what to do about each failure.

What's explicitly not here:

PKCE and authorization server discovery — that's its own post, already covered in depth elsewhere on this blog.
Token validation and audience checks — separate concern, separate post.
Full production hardening (rate limiting, client allowlisting policy, session revocation) — that's the checklist-level work, and it's dense enough that it lives in the paid pack, not a blog post.

If you're debugging a redirect_uri error right now, this is the post. If you're trying to figure out your entire auth architecture, read the discovery/PKCE post first.

Why this specific piece breaks so often

Desktop apps aren't web apps. They can't sit at a public URL waiting for a redirect. So every desktop MCP client fakes it: it spins up a short-lived local HTTP server, tells the authorization server "send the code here," and tears the server down once the callback lands. MCP clients like Claude Desktop and Cursor are desktop apps, not web apps, so the standard approach is to start a temporary local HTTP server, use that as the redirect URI, and shut it down after receiving the callback.

That handoff — client picks a port, registers it, then has to send back the exact same string later — is where almost every desktop OAuth bug in MCP actually lives. Here are the four that show up over and over in real issue trackers, not hypotheticals.

Gotcha #1: `localhost` vs `127.0.0.1` are not the same string

This is the single most common desktop redirect failure. OAuth redirect matching is exact-string, not semantic. Some MCP clients register redirect URIs with localhost, but then send 127.0.0.1 during the OAuth flow (or vice versa), and according to the OAuth spec these are different strings, so redirect URI validation fails even though they're semantically identical loopback addresses. It's not user error — it's usually a bug in the client's own networking layer. It's usually a client bug: the client might use different network libraries for registration vs. the actual callback, or the OS might resolve localhost differently in different contexts.

Fix on your server: normalize both sides. Don't just normalize at registration time — normalize again at token exchange, because clients can flip-flop between the two calls independently. One team building MCP OAuth against Clerk found that normalizing the redirect_uri again at token exchange (always to localhost) to match what was registered was necessary because clients can be inconsistent at different steps — some register with localhost but send 127.0.0.1 during token exchange, or vice versa — and normalizing only at registration wasn't enough.

Gotcha #2: dynamic ports break exact-match validation against a fixed document

If you're using Client ID Metadata Documents (CIMD) instead of per-client dynamic registration, your redirect_uris list is static — but the client's actual callback port is not. Claude Code, for example, picks a random port every run. Claude Code uses dynamic ports for its OAuth callback server (e.g., http://localhost:8080/callback or http://localhost:60351/callback). If your CIMD document only lists a bare http://localhost/callback, that doesn't match a port-bearing URI at all, because http://localhost:8080/callback does not match http://localhost/callback because no-port defaults to port 80 per RFC.

Fix: use wildcard ports in your CIMD redirect_uris, which the spec explicitly supports: the CIMD document should use wildcard ports to match Claude Code's actual callback behavior — "http://localhost:*/callback", "http://127.0.0.1:*/callback" — and this wildcard syntax is supported by the CIMD spec and by FastMCP's redirect_validation.py. If your server framework doesn't support wildcard matching yet, your fallback is forcing Dynamic Client Registration instead, since server operators can disable CIMD support so the client falls back to Dynamic Client Registration, which works because the client registers its own redirect URIs.

Gotcha #3: custom URI schemes get rejected outright

Some desktop clients skip the loopback server entirely and register an app-specific scheme like myapp://oauth-callback instead of an http://localhost address. This looks fine until you hit an authorization server that enforces the stricter native-app rules. One real-world report showed a desktop app sending a custom scheme, claude://claude.ai/mcp-auth-callback/sdk to a server whose authorization endpoint accepts only https:// or loopback redirects — meaning the exact same client worked fine against one host and failed against another with no code change on the client side at all.

Fix: if you're building the server, decide upfront and document which redirect schemes you accept — loopback, HTTPS, or a specific custom scheme allowlist — and reject silently-different behavior between hosts. If you're building the client, prefer loopback over custom schemes unless you have a specific platform reason not to; it's the pattern every major authorization server actually tests against.

Gotcha #4: registering `localhost`, sending `127.0.0.1` at the platform-policy level

This isn't just a client quirk — some identity platforms have opinions about which loopback form is even valid, and those opinions can silently break dynamic-port native apps. Microsoft Entra, for instance, only does port-agnostic matching for localhost, not 127.0.0.1: Entra's port-agnostic loopback matching works only for localhost; dynamic-port native apps therefore require localhost. A client that defaults to 127.0.0.1:52446 against an Entra-backed MCP server will hit a hard rejection — the browser lands on the Entra error AADSTS50011, that the redirect URI specified in the request does not match the redirect URIs configured for the application — even though the exact same client works fine against a server that uses standard RFC 8252 loopback matching.

Fix: if you're behind Entra or a similarly strict IdP, standardize on localhost for your loopback redirect, not 127.0.0.1, and test both forms in CI against your actual authorization server before shipping — don't assume RFC 8252 behavior is universal.

Quick reference: which fix goes where

Symptom	Root cause	Fix location
`redirect_uri_mismatch` on otherwise-correct flow	localhost vs 127.0.0.1 string mismatch	Server: normalize at registration and token exchange
CIMD rejects a valid dynamic-port callback	Static redirect_uris list, dynamic client port	Server: wildcard port syntax in CIMD, or force DCR
Client works against one server, fails against another	Custom scheme accepted inconsistently	Server: explicit scheme allowlist, documented
AADSTS50011 or similar IdP-specific rejection	Loopback host policy differs per IdP	Server: standardize on IdP's supported loopback host

Where this fits into the bigger picture

Fixing these four gotchas gets your desktop OAuth flow working. It does not tell you whether your redirect validation is safe — that's a different question, and a more consequential one, because loose redirect validation is a real attack surface: if your validation is too loose (wildcards, broad localhost rules, arbitrary custom schemes), a malicious client can register a redirect that routes sensitive data somewhere unsafe, and OAuth history is full of "slightly wrong redirect validation → stolen codes → stolen tokens."

That's the part this post deliberately leaves out: how tight is "too tight," what to log when a redirect gets rejected, and how to scope what a compromised or misconfigured OAuth client can actually reach once it does get a token. If you've had an agent or MCP client misbehave — or you just want a structured way to think through blast radius before it happens — that's exactly what the AI Agent Incident Postmortem & Permission-Scoping Template Pack is built for: a template for writing the postmortem and tightening scopes after something goes wrong, so the next redirect URI bug doesn't turn into a token leak.

For now: fix your loopback string matching, wildcard your CIMD ports, pick one redirect scheme and stick to it, and test against your actual IdP's loopback policy instead of assuming RFC 8252 is universal. That's the whole gotcha, scoped tight on purpose.

Written with AI assistance and reviewed for accuracy.

A Go/No-Go Rubric for Evaluating MCP Servers Before They Touch Production Traffic

QuietDesk Studio — Sat, 26 Sep 2026 22:44:18 +0000

Most MCP "readiness checklists" are really just a list of things that would be nice to have. They tell you to add logging, add auth, add tests — true, but not decision-grade. None of them answer the question a lead engineer actually asks before a release: given everything we know right now, do we ship this server to production agents or not?

This post is a rubric, not a wishlist. It's built to produce a number and a decision, the way a real go/no-go review works. It won't re-teach OAuth flows or walk through building a server from scratch — we've covered both of those in depth already. This is specifically about evaluation: how you score a server you (or someone else) already built, before it gets wired into an agent that real users depend on.

Why "it passed my manual tests" isn't an answer

Protocol-level tests (does tools/list return valid schemas, does the server respond to initialize) tell you the server speaks MCP correctly. They don't tell you what happens when an agent is calling it. Those are two different failure surfaces, and conflating them is the single most common mistake teams make when they say a server is "tested."

Server tests validate implementation behavior against known requirements, and MCP evals measure agent performance across realistic tasks. A server can pass every unit and conformance test and still fall apart the moment a non-deterministic agent has to choose between five similar-sounding tools, or retries a call that already partially succeeded. An MCP server can pass every protocol and handler test and still break down once an agent has to pick a tool, fill in valid arguments, and work through errors on the way to finishing a task. A scorer that reads only the final response misses silent failures and duplicate records left behind by a retry.

So the rubric below has two tiers, and you need both before you can call a server production-ready:

Tier 1 — Protocol and handler correctness. Does the server do what its schema says, deterministically, every time?
Tier 2 — Agent-facing behavior. When a real (or simulated) agent drives the server through a task, does it pick the right tool, construct valid arguments, and leave the system in a sane state afterward?

Tier 1: Protocol and handler checklist (score each 0/1)

Run these against the raw protocol, no LLM involved. They should be fast, deterministic, and part of CI — not something you eyeball once before a release.

#	Check	Why it matters
1	Every tool's JSON schema is valid and matches the runtime handler's actual accepted inputs	Schema drift is invisible until an agent sends a payload the handler silently mishandles
2	Malformed input returns a structured error, not a stack trace or empty 200	Agents parse error text to decide their next move; garbage in, garbage reasoning out
3	Every documented tool has at least one negative test (bad auth, missing field, out-of-range value)	Happy-path-only test suites are the norm, and it shows in production incident logs
4	Timeouts and partial failures are distinguishable from success	An agent that can't tell "still running" from "failed" will duplicate side effects
5	Token/session validation happens on every call, not just at connection time	Long-lived sessions with front-loaded auth checks are a common gap once bearer tokens get forwarded
6	p95 latency under realistic load is measured, not assumed	A tool that's 200ms in dev and 5s under load stalls the agent's reasoning loop and can trigger retries that compound the problem

If you're scoring under 5/6 here, stop — don't move to Tier 2 yet. Agent-level evals on top of a shaky protocol layer just produce noisy, non-repeatable results.

Tier 2: Agent-facing eval checklist

This is the part almost nobody automates, because it requires actually running an agent against the server rather than curling endpoints.

#	Check	Why it matters
7	Harness uses the same transport, auth path, and tool list as production	The eval harness acts as an MCP client, so it should use the same transport, authentication path, and exposed tools as the client used in production. A harness that skips OAuth or substitutes a shortened tool list is measuring a different configuration, and its scores say nothing about how reliably agents will use the production server.
8	Tool selection is scored separately from argument construction and outcome	A single pass-or-fail score shows a run failed but does not identify the cause. Effective agent evaluation separates tool use, arguments, execution, and outcome into distinct measurements.
9	Every task is run multiple trials, not once	Repeated trials: Multiple runs of the same task that reveal how consistently the agent completes it. A repeatable MCP eval ties each task-level pass rate to the agent behavior and system state behind it.
10	Adversarial and near-miss prompts are included, not just the intended use case	Test with adversarial prompts first. Don't just test the happy path. Try prompts that are similar to the intended use case but shouldn't activate the server.
11	System state after a run is checked, not just the final agent message	A trajectory can "look" successful while leaving duplicate writes or half-completed operations behind
12	Recovery behavior is tested, not just failure detection	Being observable isn't the same as being recoverable — check whether state can actually roll back or resume after a partial failure

Score Tier 2 the same way: 0/1 per row, and treat anything under 5/6 as "not yet," not "close enough."

What "fine, it's not ready" actually looks like

A server that scores 4/6 and 3/6 isn't broken — it's early. The honest move is to say so publicly (or at least in your internal docs): note what's covered, what isn't, and what an integrator should assume is their responsibility until it's fixed. If the server has no concept of budgets, quotas, or side-effect governors, then it is asking the orchestrator to do all the defensive work. Sometimes that's acceptable. But then be honest: the server is not production-complete on its own. That kind of scoped honesty is more useful to the next engineer than a README that just says "production ready" with no evidence behind it.

Turning this into a repeatable process

The table above is something you can run once for a demo. The harder part — and the part that actually matters eight weeks from now when the server has changed twelve times — is making it repeatable: fixed task sets, versioned scorers, a way to diff "did this get better or worse after the last deploy" instead of re-litigating the whole checklist from memory every release.

That's exactly the gap our MCP Production Checklist + Eval Templates pack is built to close. It's the scored version of everything above, packaged as reusable YAML task definitions and a minimal harness scaffold you can point at any server — plus the Production Checklist itself as a standalone document your team can actually use in a release review instead of reconstructing it from a blog post every time.

If you're evaluating a server you didn't build — a community package, a vendor's offering, or a teammate's first attempt — running both tiers above before it touches real traffic is the difference between finding the gaps in a review meeting and finding them in an incident channel at 2am.

Written with AI assistance and reviewed for accuracy.

MCP OAuth 2.1 in Practice: Authorization Server Discovery, PKCE, and Token Validation That Actually Works

QuietDesk Studio — Fri, 25 Sep 2026 14:42:56 +0000

Most MCP OAuth guides stop at "point your client at an authorization server and get a token." That's the easy 20%. The other 80% — the part that decides whether a compromised client can impersonate every user on your server — is discovery, audience binding, and token validation. This post walks through that part with actual code.

Why MCP OAuth isn't "just OAuth"

The MCP authorization spec is built on OAuth 2.1, but it adds constraints that a lot of implementations skip:

The MCP server acts as an OAuth resource server, not the authorization server itself in most production setups. It validates tokens; it doesn't issue them.
Clients must discover the authorization server via protected resource metadata (RFC 9728) rather than hardcoding endpoints.
Tokens must be audience-restricted to the specific MCP server — a token minted for Server A must not work against Server B, even if both trust the same identity provider.
PKCE is mandatory, not optional, because MCP clients are often public clients (CLI tools, desktop apps) that can't hold a client secret safely.

Skip any of these and you get a server that "works" in a demo with one client and one user, and quietly becomes a multi-tenant data leak in production.

Step 1: Publish protected resource metadata

Your MCP server needs to tell clients which authorization server to use. This is a static JSON document at a well-known path:

// GET /.well-known/oauth-protected-resource
{
  "resource": "https://mcp.yourcompany.com",
  "authorization_servers": ["https://auth.yourcompany.com"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://mcp.yourcompany.com/docs"
}

The resource field matters more than it looks — it's what you'll check against the token's aud claim later. If you skip this document, every client has to be manually configured with your auth server's URL, which is exactly the kind of hardcoded assumption that breaks the first time you rotate identity providers.

Step 2: PKCE, end to end

Your client generates a code verifier and challenge before redirecting to the authorization server:

import secrets, hashlib, base64

code_verifier = secrets.token_urlsafe(64)
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode()).digest()
).decode().rstrip("=")

auth_url = (
    f"{auth_server}/authorize"
    f"?response_type=code&client_id={client_id}"
    f"&redirect_uri={redirect_uri}"
    f"&code_challenge={code_challenge}"
    f"&code_challenge_method=S256"
    f"&resource={mcp_server_url}"  # RFC 8707 resource indicator
)

That resource parameter is the piece most tutorials leave out. It's what tells the authorization server which audience to bake into the token, so the token it issues can't be replayed against a different MCP server. Without it, a user who authorizes your MCP server today could have that same token work against a malicious server tomorrow if the auth server doesn't scope tokens per-resource.

Step 3: Validate the token like you mean it

This is where most "production" MCP servers fall short. Validating a token means checking four things, not one:

Check	What it catches	What happens if you skip it
Signature / introspection	Forged tokens	Anyone can mint a fake token
`aud` claim matches your resource URL	Tokens issued for a different service	Cross-server token replay
`exp` / `nbf`	Expired or not-yet-valid tokens	Sessions that never die
Scope sufficiency for the requested tool	Over-privileged calls	A read-only token deleting records

def validate_token(token: str, expected_audience: str) -> TokenClaims:
    claims = jwt.decode(token, key, algorithms=["RS256"], audience=expected_audience)
    if claims["exp"] < time.time():
        raise TokenExpired()
    if expected_audience not in claims.get("aud", []):
        raise AudienceMismatch()
    return TokenClaims(**claims)

Teams almost always get the signature check right — libraries do that for you. They almost as often skip the audience check, because it requires knowing what "your own identity" is as a resource server, which means you actually have to do the metadata step from Step 1.

Step 4: Sessions are not the same thing as tokens

A valid OAuth token proves who the caller is. It doesn't tell you what state their MCP session is in. Conflating the two is how you get bugs where a token refresh silently resets an agent's in-progress multi-step workflow.

Keep them separate:

Token: short-lived (15–60 min), carries identity and scopes, validated on every request.
Session: server-side state keyed by a session ID the client sends alongside the token, holding conversation/tool-call context, with its own TTL and idle timeout independent of the token's lifetime.

When a token expires mid-session, refresh the token without invalidating the session. When a session expires, require a fresh authorization handshake even if the token is technically still valid — an idle session is a bigger risk surface than a rotated token.

The failure mode that actually happens in the wild

The most common real-world break isn't a missing signature check — it's audience confusion in multi-tenant setups where one authorization server issues tokens for several MCP servers under the same organization. A team validates the signature, checks expiry, and calls it done. Six months later, a token minted for the internal analytics MCP server also works against the customer-facing one, because nobody checked aud. That's not a hypothetical; it's the exact gap the resource indicator in Step 2 and the audience check in Step 3 exist to close.

Where this fits with what we've already covered

If you haven't seen the walkthrough on wiring up auth, sessions, and error recovery in a minimal server, that post covers the end-to-end request lifecycle this one zooms into. And if you're deciding whether you need any of this OAuth machinery at all, the piece on MCP vs. simple scripts has the decision framework for when a stateless script beats a full MCP server with session management.

If you'd rather start from code that already implements this correctly than assemble it from blog posts, the AgentKitLab MCP Production Checklist pack includes a minimal working server with the discovery document, PKCE flow, and audience-validated token handling shown above already wired up, plus a checklist to audit an existing server against and agent-eval test templates to catch regressions before they ship. It's $9–$29 depending on the tier.

Quick reference: the four checks before you ship

Do you publish /.well-known/oauth-protected-resource with a correct resource field?
Does your client send a resource parameter (RFC 8707) during authorization?
Does your validation logic check aud, not just signature and expiry?
Are sessions tracked independently of token lifetime, with their own idle timeout?

If you can't answer yes to all four, that's your next PR — not a nice-to-have, but the difference between an OAuth flow that looks done and one that's actually safe to point real users at.

Written with AI assistance and reviewed for accuracy.

MCP Tool Poisoning: How Malicious Tool Descriptions Hijack Your Agent (And How to Stop It)

QuietDesk Studio — Fri, 25 Sep 2026 12:41:46 +0000

If you've shipped an MCP server or connected an agent to a few community servers, you've probably read the words "tool poisoning" somewhere and moved on. It sounds like theoretical security-blog fear-mongering. It isn't. It's the single most distinctive attack class in the MCP ecosystem, and it works because of how MCP is designed to work, not because of a bug someone will eventually patch.

This post explains what tool poisoning actually is, why your existing auth and network security don't stop it, and the specific controls you can add to a production MCP server or client this week.

What tool poisoning actually is

MCP Tool Poisoning is an indirect prompt injection attack targeting AI agents that connect to external tool servers via the Model Context Protocol. The attacker runs a malicious MCP server whose tools look normal, but their responses contain hidden instructions. When an AI agent calls one of these tools, the injected instructions land in the LLM's context window and get treated as trusted input. The LLM follows them – calling restricted tools, leaking data, or bypassing its own system prompt.

The root cause isn't a missing patch — it's architectural. The root cause is a trust gap between connect-time and runtime: tool descriptions are reviewed once, when the agent first connects to a server, but tool responses go straight into the LLM context with no equivalent check. That unguarded runtime channel is what the attacker abuses.

This was first documented publicly by Invariant Labs, who found that a malicious server cannot only exfiltrate sensitive data from the user but also hijack the agent's behavior and override instructions provided by other, trusted servers, leading to a complete compromise of the agent's functionality. They also named a closely related pattern, tool shadowing: a malicious server injects a tool description that modifies the agent's behavior with respect to a trusted service or tool, leading to malicious behavior. The danger compounds the more servers you connect — the problem of malicious MCP servers becomes even more severe when multiple MCP servers are connected to the same client, because the LLM can't tell which server "owns" an instruction once it's in context.

Why it's so hard to catch

Three properties make this attack class nastier than a typical vulnerability:

It hides in plain sight. Because MCP tool poisoning hides malicious logic inside trusted MCP tool metadata, traditional code review or UI inspection won't catch it.
It's conditional. Most attacks operate silently and conditionally—only triggering when the right sequence of actions or prompts occurs. A tool can behave normally for weeks and only poison the context under a specific trigger phrase.
It can arrive after the fact. This is the "rug pull" variant: a server passes your initial review, gets adopted, and is modified later. Attackers first deploy a seemingly trustworthy, fully functional MCP service with comprehensive documentation to attract integrations and build user dependency. Once users have established stable usage patterns, the attacker silently injects backdoors, steals credentials, or redirects communications through remote updates. The lack of mandatory mechanisms for version signing, change auditing, or update source verification in current MCP implementations makes such stealthy modifications extremely difficult for end users to detect.

If you only vetted a third-party MCP server once, at integration time, you have no idea what it's serving your agent today.

The architectural tension underneath all of this

It helps to understand why MCP is built this way. The intense research focus on tool poisoning attacks reflects a deeper architectural tension in MCP: the protocol treats natural language tool metadata as authoritative input for LLM decision-making, yet provides no mechanisms to verify the provenance, integrity, or semantic safety of this metadata. Tool descriptions, JSON schemas, enum values, and parameter examples aren't just documentation — they're part of the model's planning input, and nothing in the protocol distinguishes "documentation for humans" from "instructions the model will act on."

That distinction matters for how you write your own tool descriptions too, not just how you consume someone else's. In MCP tool poisoning, trusted-looking metadata changes planning, tool choice, or argument construction, and tool descriptions, JSON schemas, enum values, parameter examples, and remote MCP resources can all steer behavior early.

Defenses that actually hold up

None of these are exotic. They're the kind of thing you can add to a server or gateway in an afternoon.

1. Treat metadata as untrusted input, not config.
The fastest way to catch this class of issue is to stop treating tool metadata as harmless configuration — treat it like untrusted prompt input that sits on a privileged path. That means running the same kind of injection screening on tool descriptions and tool responses that you'd run on raw user input.

2. Scope tools tightly.
Each MCP tool should expose only what it needs to function, nothing more — broad or loosely defined tools dramatically increase the blast radius of a poisoned description, while tight boundaries contain the potential damage if malicious metadata fires.

3. Lock down JSON schemas.
Use strict JSON Schema for tool parameters: set additionalProperties: false and use pattern (or similar) on string fields so only declared parameters and valid formats are accepted. This closes off a common channel for smuggling extra instructions through loosely typed fields.

4. Kill silent auto-approval.
This is the single highest-leverage control in the research so far. Research shows 84.2% attack success rates when AI agents auto-approve tool calls versus less than 5% with human-in-loop approval, so best practices recommend disabling auto-approval for any tools accessing credentials, filesystems, or external networks. If your agent framework lets you require confirmation for a subset of high-risk tools, use it — it's the cheapest fix on this list.

5. Allowlist servers, don't blocklist behavior.
Maintain an allowlist of approved MCP servers, don't let users connect to arbitrary servers, vet and approve servers before they can be used, and require explicit user confirmation for sensitive operations. A default-deny approach using an allowlist of specific tools works better than blocklisting patterns, because you can't enumerate every malicious phrasing in advance.

6. Pin and hash-check what you trust.
For servers you don't control, guard against the rug-pull scenario directly. Use a signed catalog or approved registry for MCP tools and servers, so agents only load tools from an allowlist, and the catalog records the expected metadata hash for each tool definition and remote resource. If a hash changes, that's your signal to re-review before the agent uses the tool again.

7. Scan before you connect.
Don't rely purely on manual review. Use tools like mcp-scan to automatically detect poisoned descriptions and cross-server shadowing. Snyk's MCP-Scan tool provides free static analysis for immediate tool poisoning detection during evaluation — run it as a CI step whenever you add or update a server dependency, not just once at onboarding.

8. Remember it's a credential problem too.
Tool poisoning itself isn't an authentication flaw, but it often creates authentication vulnerabilities by causing agents to expose or misuse credentials, so strong auth limits downstream damage if an agent is manipulated by poisoned metadata. Your session and OAuth hygiene (short-lived tokens, scoped permissions, no long-lived credentials in tool responses) is a real mitigation, not a separate concern.

A minimal pre-deployment checklist

Before you connect any third-party MCP server to a production agent, run through this:

Check	Why it matters
Server is on an explicit allowlist	Prevents arbitrary connections from untrusted sources
Metadata hash pinned and diffed on update	Catches rug-pull style changes after initial vetting
Tool schemas use `additionalProperties: false`	Blocks smuggled parameters and malformed injection payloads
High-risk tools require human confirmation	Cuts attack success rate from ~84% to under 5%
Static scan (e.g., mcp-scan) run in CI	Catches known poisoning patterns automatically, continuously
Tool scopes minimized to single responsibility	Limits blast radius if a description is compromised
No credentials ever appear in tool descriptions/responses	Prevents silent credential exfiltration through poisoned output

Where this fits with everything else you've already hardened

If you've already worked through session handling, observability, or the production readiness checklist for your MCP servers, tool poisoning is the piece that sits on top of all of it — it's specifically about what the model is allowed to believe from tool metadata and responses, independent of whether your auth and transport layer are solid. A server can have perfect OAuth and still poison an agent through its tool descriptions.

If you're building out the incident-response side of this — what to do when a poisoned tool actually fires, and how to scope permissions so the blast radius is contained next time — the AI Agent Incident Postmortem & Permission-Scoping Template Pack walks through structured postmortems and permission-scoping worksheets built for exactly this kind of agent-security incident.

Tool poisoning isn't going away — it's a structural feature of how MCP passes natural language into the model's decision loop. The teams shipping safely aren't the ones waiting for the protocol to fix it; they're the ones treating every tool description and every tool response as untrusted input, today.

Written with AI assistance and reviewed for accuracy.

MCP Server Observability: A Practical Logging and Tracing Setup You Can Ship This Week

QuietDesk Studio — Fri, 25 Sep 2026 11:40:45 +0000

The problem: your MCP server is a black box the moment it leaves your laptop

Here's a scenario that plays out for almost every team building agents: an autonomous workflow runs overnight, a few tool calls succeed, one fails silently, and the agent reports something vague like "I wasn't able to retrieve that." No stack trace, no tool name, no timing. You're left guessing which of your five MCP servers dropped the ball.

This isn't a hypothetical edge case — it's the default experience once you move past mcp dev and local testing. The server side of MCP is where visibility disappears first: a slow tool call, a tools/list response that quietly grew to dozens of entries, a downstream API returning a 500 wrapped in a polite isError result — none of it shows up unless you deliberately put it there.

There's also a spec-level wrinkle worth knowing about if you've been relying on MCP's built-in logging capability: the protocol has been moving away from protocol-level logging as a first-class feature, which means you shouldn't build your production debugging story around it. The safer bet is to own your logging and tracing at the application layer, independent of what the spec guarantees.

This post walks through a setup you can add to an existing MCP server in an afternoon — no observability vendor, no OpenTelemetry collector cluster, just structured logs and a correlation ID pattern that will save you hours the next time something breaks at 2am.

Why standard API debugging tools don't apply cleanly

If you've operated a REST API before, you already have instincts for this: instrument the HTTP layer, log request/response pairs, ship to your logging stack, query when something breaks. MCP breaks those instincts in a few specific ways:

Protocol wrapping. Tool calls happen over JSON-RPC or HTTP, but a single tool invocation can chain multiple operations inside the server. One "call" in the trace might represent five internal steps.
Session state. MCP servers often maintain state across a session, so observability needs to capture state transitions, not just discrete request/response pairs.
Compound side effects. A tool that loops — say, calling create_issue repeatedly due to an agent retry bug — doesn't fail loudly. It just creates duplicate issues. "Did the call succeed" is the wrong question; "how many downstream effects occurred, and are they recoverable" is the right one.
Credential opacity. If your server supports multiple auth modes (service account, bring-your-own-token, delegated), your logs need to capture which identity actually executed a given call, not just that a call happened.

None of this is exotic engineering. It just means the logging you'd bolt onto a typical REST service isn't quite enough here.

Step 1: Give every request a correlation ID, end to end

The single highest-leverage change you can make is attaching a request ID the moment a tool call enters your server, and threading it through every log line, downstream API call, and error message tied to that request.

import contextvars
import uuid

request_id_var = contextvars.ContextVar("request_id", default="")

async def handle_tool_call(request):
    request_id = str(uuid.uuid4())
    token = request_id_var.set(request_id)
    try:
        # ... your existing tool dispatch logic
        pass
    finally:
        request_id_var.reset(token)

A few implementation traps to watch for:

Don't rely on a server-level "on request" decorator that may not exist in your framework version — inject the ID directly at the top of your tool dispatch function or via a transport-layer wrapper instead.
If you're running concurrent coroutines and logging the same ambient request ID from both, you'll get log lines that look correlated but aren't — scope the context var narrowly to a single tool invocation, not a whole session.
When you serialize the ID into JSON logs, guard against None explicitly (request_id_var.get() or ""), otherwise a default value can quietly break downstream log parsers that expect a string.

Step 2: Log tool calls as structured events, not print statements

print() statements don't survive process or subprocess boundaries cleanly, and they make your logs unsearchable. Instead, log every tool call as a single structured JSON event with a consistent shape:

{
  "timestamp": "2026-09-25T14:02:11Z",
  "request_id": "a1b2c3d4",
  "tool": "create_issue",
  "agent_id": "agent-42",
  "args_hash": "sha256:...",
  "duration_ms": 812,
  "status": "error",
  "error_code": "UPSTREAM_500",
  "auth_mode": "server-managed"
}

Two design choices matter more than they seem:

Hash or redact arguments instead of logging them raw. MCP tools frequently pass user data, tokens, or business-sensitive payloads. Avoid collecting authentication data, credentials, and personally identifiable information in your logs — if you need to correlate calls back to a user later, use the correlation ID plus a lookup table you control, not raw PII in the log line itself.
Log the auth mode that actually fired. If your server supports more than one credential path, the calling agent often has no idea which one executed. Capturing that explicitly is the difference between a five-minute incident review and a half-day one.

Step 3: Set latency baselines per tool, not a universal number

Don't reach for an industry-standard latency table — there isn't a meaningful one. A tool that calls an external API has a fundamentally different latency floor than one that reads from local memory, and initialize/tools/list calls should be near-instant regardless. The practical approach:

Capture p50/p95/p99 latency per tool method over a few days of normal traffic to establish your own baseline.
Alert on regressions against that baseline, not an arbitrary fixed threshold.
Treat a sudden spike in tools/list size or a previously-fast tool crossing its p95 as an early warning sign, not just outright errors.

Step 4: Distinguish "it failed" from "it lied"

The most expensive failure mode in agent systems isn't the loud error — it's the tool call that returns a technically well-formed response that's wrong. The server logs a success. The agent moves on confidently. Nobody notices for a week. Structured logging alone won't catch this; you need a lightweight assertion layer that checks tool outputs against expected shapes or value ranges before treating a call as "successful," and logs a distinct status: "suspicious" event when something looks off. This is a smaller cousin of the eval-style testing you'd run in CI, applied at runtime.

Where this fits with the rest of your production checklist

Logging and tracing are one piece of a larger production-readiness picture — alongside session handling, auth scoping, error recovery, and test coverage for tool behavior. Piecing these patterns together yourself, as outlined above, is entirely doable in an afternoon and gives you a solid foundation to build on as your MCP server matures.

Takeaways

Don't depend on protocol-level logging guarantees — own structured logging at the application layer.
Thread a correlation ID through every tool call, scoped narrowly to avoid concurrency bugs.
Log tool calls as structured JSON events with hashed/redacted arguments, never raw credentials or PII.
Build latency baselines per tool from your own traffic, not generic thresholds.
Add a lightweight runtime check for "successful but wrong" responses — this is often the costliest failure mode and the hardest to see in raw logs.

Small, deliberate investment here pays off the first time you have to explain to a teammate exactly which tool call failed, why, and what it touched before it did.

Written with AI assistance and reviewed for accuracy.

The MCP Production Readiness Checklist: What We Learned Shipping Real Servers

QuietDesk Studio — Fri, 25 Sep 2026 01:43:02 +0000

If you've built more than one MCP server, you've probably noticed a pattern: the first version takes an afternoon, and the second version — the one that actually has to survive real traffic, real auth flows, and real agent behavior — takes weeks. That gap is where most of the "MCP is overhyped" complaints come from. It's not that MCP is bad. It's that most public examples stop exactly where production work begins.

This post pulls together the lessons from two things we've built recently: a full minimal production-ready MCP server walkthrough covering auth, sessions, and error recovery, and a testing pyramid for MCP servers covering how to actually verify tool behavior instead of just eyeballing it. Rather than repeat either in detail, this is the condensed checklist — the thing you'd actually tape to the wall before a release.

Why a checklist instead of another tutorial

Tutorials show you one path through one server. A checklist works differently: it's a list of things that will bite you regardless of which framework, transport, or model you're using, because they're structural, not implementation details. If you can check every box below, you're in materially better shape than 90% of the MCP servers currently sitting in public repos.

Section 1: Authentication and identity

Every tool call carries a verified identity, not just a token. Bearer tokens get forwarded; make sure your server validates scope and expiry on every call, not just on connection.
Session tokens are short-lived and rotate. Long-lived sessions are the single most common way an MCP server turns into a standing liability.
You have a clear answer for "what happens when auth expires mid-task." Does the agent get a clean, actionable error, or does it silently retry into a wall?
Credentials never appear in tool descriptions, logs, or error messages returned to the model. This one gets missed constantly because error messages are usually the last thing anyone reviews before shipping.

Section 2: Session and state management

Sessions are scoped per-connection, not global. A shared in-memory dict keyed by nothing is fine for a demo and a data leak in production.
You've decided what happens on reconnect. Does the agent resume where it left off, or start clean? Both are valid — but only one should be true, deliberately.
Idle sessions get cleaned up. Memory leaks in long-running MCP servers are almost always orphaned session state, not the tool logic itself.
Concurrent calls from the same session are handled safely. Agents parallelize tool calls more than people expect; race conditions in session state are a quiet, nasty bug class.

Section 3: Error recovery

Errors returned to the model are structured, not raw stack traces. The model has to use this information to decide what to do next — a Python traceback is not decision-useful.
Retryable and non-retryable errors are distinguishable. Without this, agents either give up too early or retry forever on something that will never succeed.
Partial failures in multi-step tools are handled explicitly. If a tool does three things and the second one fails, what state is the world left in, and does the model know?
You have timeouts on every external call the tool makes. An MCP server is only as reliable as its slowest downstream dependency.

Section 4: Testing

This is the section most public MCP examples skip entirely, which is a shame because it's also the highest-leverage one.

Layer	What it checks	Typical tooling
Unit	Tool logic in isolation, no protocol involved	Standard test framework for your language
Contract	Tool schemas match what the server actually returns	Schema validation against real responses
Integration	Server behaves correctly over the actual MCP transport	A real client hitting a real running server
Agent-eval	The agent, given the tool, produces correct outcomes	Scripted agent runs with known tasks and expected results

The last layer is the one people underrate. A tool can pass every unit and integration test and still be unusable in practice because the model consistently misuses it — wrong argument shapes, wrong assumptions about return values, wrong retry behavior. You find that out by actually running an agent against the tool with realistic tasks, not by testing the tool in a vacuum.

Section 5: Observability

Every tool call is logged with enough context to reconstruct what happened, without logging sensitive payloads.
You can answer "how many times did this tool fail last week, and why" without grepping raw logs by hand.
Latency per tool is tracked, because a slow tool doesn't just annoy users — it changes agent behavior, since models sometimes abandon or retry slow calls in ways that compound.

Section 6: Scope and permissions

Tools expose the minimum surface area needed, not a general-purpose API wrapped in MCP clothing. The more a tool can do, the more damage a confused or manipulated agent can do through it.
Destructive actions are gated — behind confirmation, behind a narrower scope, or behind a separate approval tool entirely.
You've written down, explicitly, what the worst-case action this server can take is, and whether that's acceptable given who can reach it.

Using this as an actual pre-release gate

The realistic way to use this list isn't as an aspirational document — it's as a gate. Before a server goes anywhere near production traffic, someone (even just you, alone, with coffee) should go through each section and either check the box or write down why it's explicitly out of scope for this release. "We're not handling reconnect gracefully yet, and here's the ticket" is a fine thing to ship with. Silently not knowing is not.

If Sections 3 and 6 above are the ones that keep you up at night — figuring out what actually happened after a tool misbehaves, and deciding what an agent should and shouldn't be allowed to touch — we put together a related resource: the AI Agent Incident Postmortem & Permission-Scoping Template Pack. It's meant to give you a starting structure for both, rather than reinventing one from scratch after your first bad incident.

The honest summary

None of this is exotic engineering. It's the same discipline you'd apply to any service that takes untrusted input and takes real actions — auth, scoping, timeouts, structured errors, and tests that check outcomes, not just responses. The reason it feels new is that MCP made it very easy to skip straight to "it works in my terminal" and call that done. It's a good starting point. It's not a production system yet, and the gap between the two is exactly the six sections above.

Written with AI assistance and reviewed for accuracy.

A Minimal Production-Ready MCP Server Walkthrough (Auth, Sessions, Error Recovery)

QuietDesk Studio — Fri, 25 Sep 2026 00:41:54 +0000

Most MCP server examples you'll find online are 40 lines long, have no auth, and crash the moment a tool call throws an exception. That's fine for a demo. It's not fine for something a real agent will call thousands of times a day on behalf of real users.

This walkthrough builds up a minimal but genuinely production-ready MCP server, piece by piece, focusing on the three things toy examples always skip:

Authentication — so random clients can't call your tools
Session handling — so state doesn't leak between users or die on restart
Error recovery — so one bad tool call doesn't take down the whole server

If you're still deciding whether you need MCP at all versus a simple script, that's a separate question worth answering first — this post assumes you've already decided MCP is the right shape for your problem and now you need to ship it safely.

The bare-minimum server (what most tutorials stop at)

A typical "hello world" MCP server looks like this:

from mcp.server import Server
from mcp.server.stdio import stdio_server

app = Server("demo-server")

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_weather":
        return [{"type": "text", "text": f"Sunny in {arguments['city']}"}]

async def main():
    async with stdio_server() as (read, write):
        await app.run(read, write, app.create_initialization_options())

This works great locally over stdio with one trusted client. It has no concept of who is calling, no memory between calls, and if arguments['city'] is missing it just crashes the process. Let's fix all three.

1. Authentication: don't trust the transport

If you're exposing your MCP server over HTTP/SSE (which you need to do the moment more than one client or a hosted agent talks to it), stdio's implicit trust disappears. Every request needs to prove who it is.

The simplest production-safe pattern is a bearer token checked on every request, validated against a store you control (not hardcoded):

from fastapi import FastAPI, Header, HTTPException
import hashlib, hmac

VALID_TOKEN_HASHES = {
    # store hashed tokens, never raw tokens
    "a3f8...": {"client_id": "agent-prod-1", "scopes": ["read:tools"]},
}

def verify_token(token: str) -> dict:
    token_hash = hashlib.sha256(token.encode()).hexdigest()
    client = VALID_TOKEN_HASHES.get(token_hash)
    if not client:
        raise HTTPException(status_code=401, detail="invalid token")
    return client

app = FastAPI()

@app.post("/mcp/call")
async def call_tool_endpoint(
    payload: dict,
    authorization: str = Header(None),
):
    if not authorization or not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="missing bearer token")
    token = authorization.removeprefix("Bearer ")
    client = verify_token(token)
    # client["scopes"] now gates which tools this caller can invoke
    return await dispatch_tool_call(payload, client)

Two things matter here that toy examples never mention:

Hash tokens at rest. If your token store leaks, raw tokens are game over. Hashed tokens are not.
Scope tokens per client, not per server. A CI agent and a customer-facing agent should not share a token with identical permissions. This is exactly the kind of permission-scoping gap that causes real incidents when an agent gets access it was never meant to have.

If you need real user-level auth (not just service-to-service), OAuth 2.1 with PKCE is becoming the de facto standard for hosted MCP servers — but bearer tokens are a completely legitimate starting point for most internal or B2B agent deployments, and you can add OAuth later without rearchitecting the tool layer.

2. Session handling: state that survives more than one request

Toy servers keep everything in a global dict or, worse, in-process variables that reset the moment the server restarts. In production you need sessions that:

are isolated per client/user
survive a server restart or redeploy
expire automatically so old sessions don't pile up

import time
import json
import redis

r = redis.Redis(host="localhost", port=6379, decode_responses=True)
SESSION_TTL_SECONDS = 60 * 30  # 30 minutes

def get_session(session_id: str) -> dict:
    raw = r.get(f"session:{session_id}")
    if raw is None:
        return {"created_at": time.time(), "history": []}
    return json.loads(raw)

def save_session(session_id: str, session: dict):
    r.setex(
        f"session:{session_id}",
        SESSION_TTL_SECONDS,
        json.dumps(session),
    )

async def dispatch_tool_call(payload: dict, client: dict):
    session_id = payload.get("session_id") or f"{client['client_id']}-{int(time.time())}"
    session = get_session(session_id)

    session["history"].append({"tool": payload["tool"], "args": payload["arguments"]})
    result = await run_tool(payload["tool"], payload["arguments"], session)

    save_session(session_id, session)
    return {"result": result, "session_id": session_id}

Redis here is a stand-in — a small SQLite table works fine at low volume. The point isn't the storage engine, it's the pattern: session state lives outside the process, has a TTL, and is keyed so one client can never read another's session. That last part is easy to get wrong when you're moving fast, and it's the kind of thing worth putting on a checklist rather than trusting memory to catch.

3. Error recovery: one bad tool call shouldn't kill the server

This is the gap that hurts the most in practice. An agent will eventually call a tool with malformed arguments, a downstream API will time out, or a tool will throw an unhandled exception. A toy server crashes. A production server catches it, logs it usefully, and returns something the calling agent can actually reason about.

import logging
import traceback

logger = logging.getLogger("mcp-server")

class ToolExecutionError(Exception):
    def __init__(self, message: str, retryable: bool = False):
        self.message = message
        self.retryable = retryable
        super().__init__(message)

async def run_tool(name: str, arguments: dict, session: dict):
    try:
        tool_fn = TOOL_REGISTRY.get(name)
        if tool_fn is None:
            raise ToolExecutionError(f"unknown tool: {name}", retryable=False)

        return await tool_fn(arguments, session)

    except ToolExecutionError as e:
        logger.warning(f"tool_error tool={name} retryable={e.retryable} msg={e.message}")
        return {
            "error": True,
            "message": e.message,
            "retryable": e.retryable,
        }

    except Exception as e:
        # unexpected error — log full trace, return a safe generic message
        logger.error(f"unexpected_error tool={name}\n{traceback.format_exc()}")
        return {
            "error": True,
            "message": "internal error, try again",
            "retryable": True,
        }

Two design choices here matter more than they look:

retryable is part of the response contract. An agent orchestrator can decide to auto-retry a timeout but not auto-retry a bad-arguments error. Without this flag, agents tend to either retry everything (wasteful, sometimes dangerous) or nothing (brittle).
Never leak stack traces to the caller. Log them server-side, return a generic message to the client. Stack traces in tool responses are a surprisingly common accidental information leak.

Putting it together

The full request path now looks like: bearer token verified → session loaded from durable storage → tool executed inside a try/except that classifies errors → session saved → structured response returned. None of this is exotic engineering — it's the same auth/session/error-handling discipline you'd apply to any API. MCP just makes it easy to skip because the demos never show it.

Where to go from here

Writing this layer from scratch for every new MCP server is exactly the kind of repeated setup work that's easy to get subtly wrong under deadline pressure — a missing TTL here, an unscoped token there. If the permission-scoping gaps discussed above (the CI agent vs. customer-facing agent scenario) sound familiar, the AI Agent Incident Postmortem & Permission-Scoping Template Pack is built specifically around auditing and documenting those failure modes before they turn into incidents: check it out here.

If you're building agent tooling more broadly and want a second pair of eyes on where things tend to break, the failure-mode patterns in autonomous coding agents are worth a read too — a lot of the same "it worked in the demo" gaps show up there.

Written with AI assistance and reviewed for accuracy.

How to Test MCP Servers: A Practical Testing Pyramid for Agent Tools

QuietDesk Studio — Fri, 25 Sep 2026 00:41:53 +0000

Most MCP tutorials stop at "here's a tool that returns weather data." Almost none of them answer the question that actually matters once you ship: how do you know your MCP server still works after the next change?

If you've built a production MCP server, you already know the failure modes are weird. A tool schema drifts and the model starts calling it wrong. A session token expires mid-conversation and the agent silently gets empty results instead of an error. A refactor changes a return type from a string to an object and every downstream agent breaks in a way no pytest unit test catches.

This post gives you a concrete testing pyramid for MCP servers, with what to test at each layer and why the layer above it isn't enough on its own.

Why MCP testing is different from normal API testing

A regular REST API has one consumer type: code that calls it with fixed, known inputs. An MCP server has two:

Deterministic clients — your own test harness, CI, health checks.
A non-deterministic client — the LLM itself, which decides when to call a tool, what arguments to pass, and how to interpret the response.

That second consumer means schema correctness isn't optional polish — it's the interface contract the model reasons over. A tool description that's technically valid JSON Schema but ambiguous in plain English will get called wrong in production even if every unit test passes.

So your test suite needs to answer four separate questions:

Does the tool do what it claims when called with valid arguments?
Does it fail safely and informatively when called with bad arguments?
Does the session/auth layer behave correctly across the lifecycle (expiry, revocation, refresh)?
Would a model, given only the tool's description and schema, actually call it correctly?

Most teams only test the first one.

Layer 1: Schema and contract tests

Before anything touches an LLM, validate that your tool definitions are internally consistent and haven't silently drifted.

def test_tool_schema_matches_handler_signature():
    for tool in registered_tools:
        schema_props = set(tool.input_schema["properties"].keys())
        handler_params = set(inspect.signature(tool.handler).parameters.keys())
        assert schema_props == handler_params, (
            f"{tool.name}: schema/handler mismatch — "
            f"schema has {schema_props}, handler expects {handler_params}"
        )

def test_all_required_fields_are_documented():
    for tool in registered_tools:
        for field in tool.input_schema.get("required", []):
            assert tool.input_schema["properties"][field].get("description"), (
                f"{tool.name}.{field} has no description — the model can't reason about it"
            )

This catches the single most common regression: someone adds a required parameter to the handler and forgets to update the schema. It's boring, it's fast, and it should run on every commit.

Layer 2: Handler behavior tests (unit + integration)

These are close to normal unit tests, but with an MCP-specific twist: test the MCP response envelope, not just the underlying business logic.

def test_tool_returns_structured_error_on_bad_input():
    result = call_tool("get_invoice", {"invoice_id": "not-a-real-id"})
    assert result.is_error is True
    assert "invoice_id" in result.content[0].text  # error is specific, not generic
    assert result.content[0].text != ""             # never return an empty error body

def test_tool_handles_upstream_timeout_gracefully():
    with mock_upstream_timeout():
        result = call_tool("get_invoice", {"invoice_id": "INV-100"})
        assert result.is_error is True
        assert "timeout" in result.content[0].text.lower()

A pattern worth stealing: write one test per failure mode you've actually seen in production (timeout, malformed upstream response, rate limit, auth expiry), not just the happy path. If you keep an incident log, each entry should turn into a regression test.

Layer 3: Session and auth lifecycle tests

This is the layer almost everyone skips, and it's the one that causes the scariest production bugs, because failures here are silent — the agent doesn't crash, it just gets wrong or stale data.

Minimum test set for any MCP server with auth:

Scenario	Expected behavior
Valid session, first call	Succeeds, returns fresh data
Session expired mid-conversation	Tool returns explicit "session expired" error, not empty/stale data
Token refresh in-flight during concurrent calls	No duplicate refresh requests, no dropped calls
Revoked session	Immediate rejection, not a delayed 200 with garbage
Session reused across two different agent contexts	Explicit isolation — no data leakage between conversations

def test_expired_session_returns_explicit_error_not_stale_data():
    session = create_session(ttl_seconds=1)
    time.sleep(2)
    result = call_tool("list_documents", {}, session=session)
    assert result.is_error is True
    assert "expired" in result.content[0].text.lower()
    # the dangerous version of this bug: result.content has stale cached data instead

If you only test one thing from this post, test the expired-session case. It's the difference between an agent that says "I need you to re-authenticate" and one that confidently reports numbers from three hours ago.

Layer 4: LLM-in-the-loop evaluation tests

This is the layer that's genuinely new compared to normal software testing, and it's where "agent-eval" testing lives. The question isn't "does the code work," it's "given only the tool description, does the model call it the way you intended?"

A minimal eval harness:

EVAL_CASES = [
    {
        "prompt": "What's the status of invoice INV-4471?",
        "expected_tool": "get_invoice",
        "expected_args_contains": {"invoice_id": "INV-4471"},
    },
    {
        "prompt": "Cancel my subscription",
        "expected_tool": "cancel_subscription",
        "expected_args_contains": {},
        "must_not_call": ["delete_account"],  # guard against dangerous over-reach
    },
]

def run_eval_case(case, model_client):
    response = model_client.run(case["prompt"], tools=registered_tools)
    tool_calls = [c.name for c in response.tool_calls]
    assert case["expected_tool"] in tool_calls
    for forbidden in case.get("must_not_call", []):
        assert forbidden not in tool_calls, f"Model incorrectly called {forbidden}"

Run this against your actual model provider on a schedule (weekly, or on every schema change), not just once at launch. Model providers update their models, and a tool description that worked perfectly with one model version can start getting misinterpreted after a silent upgrade. This is the test layer that catches "the model started calling delete_account when the user said 'cancel my subscription'" before your users do.

Putting it together: a CI pipeline that actually catches regressions

A sane ordering, fastest and cheapest first:

Schema/contract tests — milliseconds, run on every save.
Handler unit tests — seconds, run on every commit.
Session/auth lifecycle tests — seconds to low minutes, run on every PR.
LLM-in-the-loop evals — costs real API tokens, run on every PR to main and on a nightly schedule, not on every keystroke.

Gate merges on layers 1–3. Treat layer 4 as a monitored signal — alert if the pass rate drops, but don't necessarily block every PR on it, since model non-determinism means occasional flakes are expected. Track the pass rate as a trend, not a single number.

Where to go from here

Writing all four layers from scratch for your first MCP server takes longer than it should — mostly because there's no standard scaffold for the schema/contract tests or the eval harness, so everyone reinvents it slightly differently.

If the session/auth layer and incident-driven test cases in this post resonated with you, I put together the AI Agent Incident Postmortem & Permission-Scoping Template Pack — templates for turning production incidents (like the expired-session and over-reach cases above) into structured postmortems and tighter permission scopes for your tools. It won't write your test suite for you, but it gives you a structured way to capture the failures that should become regression tests in the first place.

Either way — even just adding the expired-session test and one LLM-in-the-loop eval case this week will catch bugs your current test suite is currently blind to.

Written with AI assistance and reviewed for accuracy.

DEV Community: QuietDesk Studio

The MCP Redirect URI Edge Cases Dynamic Client Registration Doesn't Save You From

Scope of this post

Why DCR doesn't actually solve the redirect URI problem — it relocates it

Gotcha #1: The authorization endpoint disagrees with the registration endpoint

Gotcha #2: Loopback redirect URIs work for CLIs, except when the provider doesn't trust loopback at all

Gotcha #3: Stale client registrations die silently, and nothing tells the client to re-register

Gotcha #4: client_uri origin-matching breaks tools that proxy through a different domain than they authenticate from

Gotcha #5: Session binding that happens after the OAuth handshake, not during it

What this post deliberately doesn't solve

The one-line takeaway

The MCP Load & Resilience Checklist: What This Covers, and What It Deliberately Doesn't

Why scope matters here specifically

The checklist: 10 items, four phases

Phase 1 — Limits (before traffic exists)

Phase 2 — Backoff and retry behavior (during a spike)

Phase 3 — Degradation (when limits are hit)

Phase 4 — Verification (before you trust any of the above)

The gotcha that isn't in the generic guides

What's deliberately out of scope here (and where it lives)

Using this as a definition of done

Rate-Limiting and Backoff Patterns for MCP Servers That Don't Fall Over Under Load

Why "just add exponential backoff" isn't the fix

Pick the layer you're actually rate-limiting

A token bucket you can actually reason about

Returning a 429 the agent can act on

The backoff schedule itself

Catching stuck agents before they trip the limit

What's in the pack

The MCP Session Refresh Gotcha: Why "Token Expired" and "Session Expired" Are Not the Same Bug

The bug report that keeps repeating itself

Scope: what this covers and what it doesn't

Phase 1: Understand that you have two clocks, not one

Phase 2: Correctly classify the failure before you react

Phase 3: Refresh the token — but check the provider actually gave you one

Phase 4: Don't let a successful token refresh leave a stale session behind

Phase 5: Retry once, with a real circuit breaker — not forever

Why this is worth getting right before launch

The Desktop Redirect URI Gotcha That Breaks MCP OAuth (And How to Actually Fix It)

Scope of this post

Why this specific piece breaks so often

Gotcha #1: localhost vs 127.0.0.1 are not the same string

Gotcha #2: dynamic ports break exact-match validation against a fixed document

Gotcha #3: custom URI schemes get rejected outright

Gotcha #4: registering localhost, sending 127.0.0.1 at the platform-policy level

Quick reference: which fix goes where

Where this fits into the bigger picture

A Go/No-Go Rubric for Evaluating MCP Servers Before They Touch Production Traffic

Why "it passed my manual tests" isn't an answer

Tier 1: Protocol and handler checklist (score each 0/1)

Tier 2: Agent-facing eval checklist

What "fine, it's not ready" actually looks like

Turning this into a repeatable process

MCP OAuth 2.1 in Practice: Authorization Server Discovery, PKCE, and Token Validation That Actually Works

Why MCP OAuth isn't "just OAuth"

Step 1: Publish protected resource metadata

Step 2: PKCE, end to end

Step 3: Validate the token like you mean it

Step 4: Sessions are not the same thing as tokens

The failure mode that actually happens in the wild

Where this fits with what we've already covered

Quick reference: the four checks before you ship

MCP Tool Poisoning: How Malicious Tool Descriptions Hijack Your Agent (And How to Stop It)

What tool poisoning actually is

Why it's so hard to catch

The architectural tension underneath all of this

Defenses that actually hold up

A minimal pre-deployment checklist

Where this fits with everything else you've already hardened

MCP Server Observability: A Practical Logging and Tracing Setup You Can Ship This Week

The problem: your MCP server is a black box the moment it leaves your laptop

Why standard API debugging tools don't apply cleanly

Step 1: Give every request a correlation ID, end to end

Step 2: Log tool calls as structured events, not print statements

Step 3: Set latency baselines per tool, not a universal number

Step 4: Distinguish "it failed" from "it lied"

Where this fits with the rest of your production checklist

Takeaways

The MCP Production Readiness Checklist: What We Learned Shipping Real Servers

Why a checklist instead of another tutorial

Gotcha #4: `client_uri` origin-matching breaks tools that proxy through a different domain than they authenticate from

Gotcha #1: `localhost` vs `127.0.0.1` are not the same string

Gotcha #4: registering `localhost`, sending `127.0.0.1` at the platform-policy level