Bootstrap a service you don't understand and you've shipped a black box you can't debug.

The agent wires up Stripe in four minutes. Webhook endpoint, signature verification, a payment_intent.succeeded handler, the lot. It runs. You merge it. Three weeks later a customer’s card gets declined mid-flow, the webhook fires twice, and you’re staring at a function you’ve never actually read, integrating a service whose retry semantics you couldn’t explain to a colleague. The agent didn’t know your codebase. You didn’t know Stripe. You shipped the intersection of two blind spots and called it velocity.

This is the seductive trap of letting an agent bootstrap an unfamiliar third-party service. Zero-to-one is genuinely fast — and that speed is exactly what mortgages your ability to own the thing later.

The standard advice is reasonable on its face: the agent has read more Stripe integrations than you ever will, so let it drive. For the happy path, that’s true. It’ll scaffold a working integration faster than you could read the quickstart. If the integration never failed, never needed a schema change, never had to reconcile a duplicate webhook, you could merge the black box and move on.

But integrations are nothing but failure modes. Idempotency keys, signature rotation, partial refunds, the difference between payment_intent and charge, what happens when the webhook arrives before your DB write commits. The agent will pick defaults for every one of these and won’t tell you it made a choice. The cost isn’t the code it writes — it’s the decisions it buries. When the page goes off at 2am, the gap you bootstrapped over is still there, and now it’s load-bearing.

So here’s the open question worth holding onto: if you don’t understand the service, how do you supervise an agent that’s confidently integrating it? You can’t review what you can’t read.

The first half of the fix is closing the agent’s gap with primary sources. A model’s training data on a fast-moving API is stale and lossy; it half-remembers three SDK versions blended together. Give it the current docs directly through an MCP server, so it reasons over today’s API surface instead of a fuzzy memory of last year’s.

Stripe ships exactly this. Its remote MCP server lives at https://mcp.stripe.com and, among its tools, exposes search_stripe_documentation — the agent queries the live reference instead of leaning on a half-remembered SDK. Wire it up in a couple of lines:

// .mcp.json — connect the agent to Stripe's own MCP server
{
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com"
    }
  }
}

The server authenticates over OAuth on first connect. It’s the full agent toolkit — it can create charges and refunds too — so scope it with a read-restricted key if all you want is the docs grounding. For a service that publishes an llms.txt instead, point the agent straight at that: same goal, lighter setup.

Now when the agent proposes the webhook set, it’s grounded in the canonical reference, not a hallucinated approximation. That fixes correctness. It does nothing for your understanding — which is the half everyone skips.

The second half is the move that turns the agent from a substitute into a tutor. A rules file is persistent context the agent reads on every turn. Most people use it to encode conventions. Use it here to encode a teaching obligation:

# AGENTS.md — third-party integration protocol

When integrating any service I haven't worked with before:

- Pull the current behavior from the service's MCP docs. Do not rely on training memory.
- Before writing code, list the decisions you're about to make and the
  alternative for each (e.g. "verifying signatures with the raw body, not
  parsed JSON — the alternative loses the bytes needed to verify").
- For anything on the critical path — money, auth, data integrity —
  explain the failure mode the chosen approach guards against.
- Flag every place a default could bite us later. Name it, don't bury it.

That last clause is the whole game. The agent already knows these things; left to itself it just won’t say them. The rule forces the buried decisions to the surface where you can actually see them — and reading the why behind ten choices teaches you the service faster than any tutorial, because every explanation is anchored to code you’re about to ship.

Tie it together with plan mode: the agent researches and proposes, but writes nothing until you approve. The plan becomes your lesson. You read the proposed handler set and its reasoning before a single line lands:

PLAN — Stripe webhook integration

1. Verify signatures against the raw request body (not parsed JSON).
   Why: Stripe signs the exact bytes; a JSON parser that runs before
   verification re-serializes them and the check fails. This is the
   single most common webhook bug.

2. Make the handler idempotent on event.id.
   Why: Stripe guarantees at-least-once delivery — it retries any
   non-2xx with exponential backoff for up to three days, and can
   deliver duplicates even on success. Without a dedupe key (a UNIQUE
   constraint on the stored event.id), you double-fulfill orders.

3. Return 200 fast; defer fulfillment to a queue.
   Why: Stripe waits ~10 seconds for a 2xx. A slow handler blows
   that window, gets marked failed, and triggers the retry storm
   from line 2.

Decision flagged: storing the full event payload vs. just the ID.
Recommend full payload for replay/debugging. Your call.

You don’t have to be a Stripe expert to evaluate that. You have to be able to read three claims and ask one good question. The plan converts “I’m trusting a black box” into “I’m reviewing a proposal I understand the shape of.” That’s the entire difference between owning a critical path and renting one until it breaks.

Stripe makes the pattern vivid because money makes failures expensive, but the technique isn’t about payments. Swap in any service whose internals you don’t carry in your head and the three primitives do the same work.

Take verifying a third-party’s signed tokens — an identity provider handing you JWTs. Left alone, an agent will happily decode the token, read the claims, and trust them. That code runs. It also accepts forged tokens, because decoding is not verifying. The buried decisions here are a minefield: validate the signature against the provider’s published JWKS, reject the none algorithm outright, check the aud and iss claims actually match your service, honor exp. Every one is a default the agent picks silently, and every one is a hole if it picks wrong.

The teaching clause drags those choices into the plan before any code lands:

PLAN — verify inbound identity tokens

1. Fetch the provider's signing keys from its JWKS endpoint and cache
   them; verify each token's signature against the matching key id.
   Why: a JWT is base64, not encryption. Anyone can read and rewrite
   the claims. Only the signature proves the issuer wrote it.

2. Pin the accepted algorithm to the asymmetric one the provider uses.
   Reject "alg": "none" and any symmetric algorithm.
   Why: the classic JWT bypass is swapping the header to none (no
   signature checked) or to HS256 keyed off the public key.

Decision flagged: validating "aud" strictly vs. accepting any audience.
Recommend strict — a token minted for another app shouldn't open yours.
Your call.

You don’t need to have memorized the JWT spec to weigh that. You need to read three claims and notice that point two is guarding against an attack you can now name. The agent knew the alg: none trap the whole time — the rule is what made it say so out loud instead of shipping a decoder and calling it auth. That’s the portability of the move: the service changes, the protocol doesn’t.

Two honest caveats, because a technique you can’t see the edges of is just another black box.

First, the failure mode: a confident explanation is not a correct one. The teaching clause guarantees the agent states a rationale; it does not guarantee the rationale is true. A model can produce a fluent, plausible “why” for a choice that’s subtly wrong — explanation theater that reads like understanding. This is exactly why the MCP grounding is load-bearing rather than optional: you want the agent reasoning over the live reference, not narrating a confident memory. And it’s why you still spot-check the single highest-stakes claim in the plan against the actual docs. The protocol shrinks the surface you have to verify from “all the code” to “the few load-bearing claims” — it doesn’t shrink it to zero.

Second, when to skip the ceremony entirely: the overhead only earns its keep on a path you’ll have to own. A throwaway prototype you’ll delete next week, a non-critical-path call to a service that can fail without anyone paging you, a one-off script — let the agent bootstrap the black box and move on. The teaching clause buys you the ability to supervise a load-bearing integration; spend it where something is actually load-bearing. Demanding a decision-by-decision tutorial for a feature flag you’ll rip out tomorrow is just friction cosplaying as rigor.

Step back and the pattern is pure context engineering. The agent is broad and contextless — it doesn’t know your codebase, and its memory of the service is stale. You are narrow and contextless in the opposite direction — you know your codebase but not the service. MCP closes the agent’s gap with live docs. The rules file’s teaching clause closes your gap by forcing the agent to externalize what it already knows. Plan mode is the checkpoint where the two of you actually meet.

Each primitive does one job; together they convert a knowledge asymmetry into a transfer. You end up understanding enough of the critical path to own it, and the agent ends up grounded in the real API instead of a guess. Neither of you stayed blind.

Skip the teaching clause and you’ve just automated the production of black boxes — faster, which is worse. An agent that integrates a service for you is a contractor. An agent that integrates it and explains every load-bearing choice is a tutor who leaves you able to run the thing it built. Ask for the second one. It costs you one rule and a plan you have to read.

For the per-tool mechanics, see MCP servers for wiring live docs into the agent, Rules for the persistent teaching protocol, and Plan mode for the review gate that turns a proposal into a lesson.