DEV Community: Marc Gil

I spent a week on OAuth plumbing for an MCP server before writing a single line of actual product logic.

Marc Gil — Tue, 14 Jul 2026 15:40:01 +0000

I spent a week on OAuth plumbing for an MCP server before writing
a single line of actual product logic.

Four hours in I was reading RFC 9728. Not one line of that code
made the server smarter or more useful. I shipped with a static
API key and moved on.

Eventually I went back and built it properly. And the part I
thought would be easy — Stripe billing — turned out to have three
edge cases that nobody documents anywhere.

This is about those three cases.

The setup

You've got an MCP server. Users call it. You want to charge per call.
The obvious path: POST to Stripe's API after each tool call, done.

Except it's not done.

Problem 1: Retries

A client makes a tool call. Your server processes it. Before the
response arrives, the client's network drops. The client retries.

You now have two requests for what is logically one call. Without
protection, you bill twice.

The fix is an idempotency key — a stable identifier for the
logical request, not the HTTP request. The client generates it
once and reuses it across retries. Your server enforces uniqueness
at the database level:

// POST /api/usage
const existing = await prisma.usageEvent.findUnique({
  where: { idempotencyKey: body.idempotencyKey }
})

if (existing) {
  return Response.json({ ok: true, deduplicated: true })
}

The key detail: uniqueness enforced by a DB constraint, not a
SELECT-before-INSERT. The race condition between two simultaneous
retries hitting the server at the same instant is closed by the
constraint, not by application logic.

The client side looks like this:

// In your MCP server — generate once per logical call
const idempotencyKey = `${mcpRequestId}-search_documents`

await fetch(`${APP_URL}/api/usage`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: JSON.stringify({
    idempotencyKey,
    endpoint: 'search_documents',
    units: 1,
    status: 'completed',
  }),
})

Problem 2: Interrupted streaming responses

You're streaming a response. 3,000 tokens in, the user closes
the tab.

Do you bill for those 3,000 tokens? Or nothing?

There's no objectively correct answer — it depends on your cost
structure and what you've promised users. But you have to make
the decision explicitly, and you have to make it before you ship.

The approach I took: register usage once, when the stream finishes.
If it doesn't finish, send a partial status instead of skipping
the call entirely.

// At stream completion
await reportUsage({
  idempotencyKey,
  endpoint: 'generate_text',
  units: totalTokensStreamed,
  status: streamCompleted ? 'completed' : 'partial',
})

partial events are always recorded in Postgres for auditing.
Whether they're reported to Stripe is configurable:

// Default: only 'completed' goes to Stripe
const BILLABLE_STATUSES = ['completed']

// If you want to bill partial calls too:
// const BILLABLE_STATUSES = ['completed', 'partial']

The important thing isn't which option you pick — it's that you
pick one explicitly and document it, because your users will ask.

Problem 3: What "failed" means

Not every failed call should be treated the same way.

A tool call that fails because your server threw an unhandled
exception: probably shouldn't be billed.

A tool call that fails because the user's input was invalid
(and you processed it, returned a 400, and spent compute doing
so): maybe should be billed.

The status field handles this:

type UsageStatus = 'completed' | 'partial' | 'failed'

failed events are always written to Postgres — you want the
audit trail — but never reported to Stripe by default. If you
need to bill for certain failure modes, add them to
BILLABLE_STATUSES.

The failed events in Postgres are also useful for debugging.
If a specific endpoint has a high failure rate, you'll see it
in the usage table before it becomes a support ticket.

The thing Stripe's docs don't say

Stripe's usage-based billing documentation covers the happy path
well. It doesn't cover what to do when:

The same event arrives twice (retries)
The event never fully completes (streaming, disconnects)
The event completes but represents a failure (errors)

These aren't edge cases in practice — they're normal operating
conditions for any MCP server with real users.

I ended up building all of this into a boilerplate
(MCP-Billing) along with OAuth 2.1,
API key management, and rate limiting. But the decisions above
are framework-agnostic — you can apply them to any Stripe
usage-based integration.

The main takeaway: make the decisions explicit, document them in
your README or changelog, and make BILLABLE_STATUSES configurable
from day one. You will change your mind about what's billable
as you learn more about your users' behavior.

Why Most AI Prompts for Developers Don't Work (and How to Fix Them)

Marc Gil — Thu, 09 Jul 2026 17:38:51 +0000

You've seen the lists. "100 ChatGPT Prompts for Developers." "Ultimate Prompt Pack for Coders." You try one, get a generic response that doesn't understand your stack, your codebase, or your actual problem — and go back to writing the prompt yourself from scratch.

The issue isn't the AI. It's that most prompts shared online were written by people who don't actually write code. They're optimized for looking comprehensive, not for producing useful output in a real codebase.

Here's what's actually going wrong, and how to fix it.

The three failure modes of generic dev prompts

1. No context anchoring

A prompt like "review my code and suggest improvements" gives Claude or GPT-4 nothing to work with. The model doesn't know your language, your framework, whether you care about performance or readability, or what "improvement" means in your context. It produces a generic response because it received a generic input.

2. No output structure

When the AI doesn't know what format you need, it invents one — and it's usually a wall of text that mixes critical issues with stylistic suggestions with refactoring ideas. You end up reading the whole thing to find the one insight you actually needed.

3. No variables to customize

A prompt that works for a Python FastAPI backend won't work unchanged for a TypeScript monorepo. Generic prompts treat all codebases as equivalent. They're not.

What a prompt that actually works looks like

Here's a concrete example. This is the code review prompt I use in my daily workflow:

You are a senior software engineer conducting a thorough code review.

Context:
- Language/Framework: [LANGUAGE_AND_FRAMEWORK]
- Project type: [PROJECT_TYPE]
- Review focus: [FOCUS: security / performance / readability / all]

Code to review:
[PASTE_CODE_HERE]

Additional context (optional):
[CONTEXT: recent changes, known constraints, team conventions]

Provide:
1. A severity-labeled issue list (Critical / Major / Minor / Suggestion)
2. For each Critical and Major issue: explain why it's a problem and provide corrected code
3. A summary score (1–10) with one-sentence justification
4. Top 3 actionable improvements for the next iteration

The differences from a generic prompt:

[LANGUAGE_AND_FRAMEWORK] forces you to specify context before pasting anything — which also forces the model to apply language-specific knowledge
The severity labels structure the output before it's generated, so you get a scannable list instead of paragraphs
"For each Critical and Major issue: provide corrected code" means you get working code, not a description of what to change
The summary score gives you a baseline to track improvement across PRs

Here's what this produces with a real piece of code — a Python FastAPI endpoint with a SQL injection vulnerability:

CRITICAL [SQL Injection] — Line 12
The query uses direct string interpolation with user input:
query = f"SELECT * FROM users WHERE email = '{email}'"
This allows arbitrary SQL execution. Fix:
result = db.execute(
    text("SELECT * FROM users WHERE email = :email"),
    {"email": email}
)

MAJOR [Missing authentication] — Line 8
The endpoint has no authentication decorator. Any unauthenticated request 
can access user data. Add @require_auth or equivalent middleware.

MINOR [No input validation] — Line 6
Email input is not validated before use. Add:
if not re.match(r"[^@]+@[^@]+\.[^@]+", email):
    raise HTTPException(status_code=422, detail="Invalid email format")

Summary score: 4/10 — Critical security vulnerability makes this 
unshippable in current state.

Top 3 next steps:
1. Migrate all raw queries to parameterized statements
2. Add authentication middleware at router level
3. Implement Pydantic input validation models

That's directly actionable. The "review my code" prompt wouldn't get you there.

The pattern that makes prompts reusable

Every prompt that actually holds up in daily use has three components:

Role + context — Tell the model who it is and what it's looking at. "You are a senior software engineer" isn't fluff — it activates a different response distribution than "help me with this code." Adding framework and project type narrows it further.

Structured variables — Anything that changes between uses goes in [BRACKETS]. This turns a one-time prompt into a reusable template. You fill in the variables, paste your code, and get consistent output structure every time.

Output specification — Define the format before the model generates it. Numbered lists, severity labels, score, corrected code — specify exactly what you need. If you don't, the model optimizes for completeness, not usability.

A second example: debugging with stack trace context

This one saves the most time in practice. Instead of "why is this failing," you give the model everything it needs to diagnose:

You are debugging a production issue in a [LANGUAGE] application.

Error and stack trace:
[PASTE_FULL_STACK_TRACE]

Relevant code section:
[PASTE_CODE]

Environment context:
- Runtime version: [VERSION]
- Recent changes: [WHAT_CHANGED_RECENTLY]
- Frequency: [always / intermittent / under specific conditions]

Provide:
1. Most likely root cause (with confidence: high / medium / low)
2. Why this error occurs at this specific point in the stack
3. Fix with code, not just description
4. One test to verify the fix works

The "recent changes" and "frequency" fields are what make this work. Intermittent errors that only happen under load have different root causes than errors that happen every time. Without that context, the model guesses. With it, the diagnosis is usually right on the first try.

Why this matters more now than six months ago

Models have gotten significantly better at following structured instructions. GPT-4o and Claude 3.5+ will reliably produce the exact output format you specify if your prompt is precise enough. The ceiling on prompt quality has gone up — which means the gap between a well-structured prompt and a generic one is now larger, not smaller.

Developers who invest in building reusable, structured prompts for their specific workflows are getting qualitatively better AI assistance than those using prompts from generic lists.

Where to go from here

The two prompts above are from a larger set I built for my own dev workflow: 38 prompts covering code review, debugging, documentation, git workflows, architecture decisions, and testing — each with the same structure: role, variables, output spec, and a real output example generated from actual code.

If you want the full set: DevPrompt Pro on Gumroad — $19.

If you want to build your own, the pattern in this article is the starting point. The most important habit: every time you write a prompt that produces a genuinely useful output, turn it into a template before you close the tab.

Built this for my own use as a developer. Happy to discuss specific prompt structures in the comments — if you have a workflow that's hard to prompt for, drop it below.