Four things that bit us shipping a remote MCP server with OAuth

Tolga Cakular — Sat, 15 Aug 2026 17:31:23 +0000

We recently shipped a remote MCP server so people can verify email addresses from inside Claude, ChatGPT and Cursor. (Disclosure: I work on ClearBounce, the service behind it.) The protocol itself is pleasant to implement. What cost us time was everything around it — the parts that are not in the spec, or are in the spec but that clients and directories disagree about.

Here are four of them, with what we actually observed.

1. Echo the client's protocol version. Do not force your own.

Our initialize handler proudly returned the newest protocol version we supported. Claude Code refused to connect:

Server's protocol version is not supported: 2026-07-28

The client sends the version it wants in params.protocolVersion. If you answer with something it has never heard of, it bails — even when your version is newer. The fix is to accept any sane date-shaped version the client asks for and echo it back:

const SUPPORTED = ['2026-07-28', '2025-11-25', '2025-06-18', '2025-03-26'];

function negotiateProtocolVersion(requested) {
  if (typeof requested === 'string' && /^20\d{2}-\d{2}-\d{2}$/.test(requested)) {
    return requested;
  }
  return SUPPORTED[0];
}

Think of it as content negotiation, not as advertising your capabilities.

2. Return 401, not 403 — and accept that one directory will call you unhealthy for it

For OAuth-protected servers, the discovery trigger is an unauthenticated request answered with 401 plus a WWW-Authenticate header pointing at your protected-resource metadata:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource/mcp"

This is what makes claude.ai and ChatGPT offer to connect an account instead of just failing. Return 403 and the client has nothing to discover.

We learned this the hard way in the other direction. An earlier version exposed an anonymous tools/list as a friendly "here is what I can do" response. Because nothing ever returned 401, no client ever started the OAuth flow. Removing the anonymous showcase fixed it.

The irony: after doing the correct thing, one directory's health checker connects without credentials, receives our correct 401, and marks the server Unhealthy on its public listing. Meanwhile another directory's scanner documents the opposite requirement — its docs explicitly say servers should return 401 rather than 403 so OAuth can be discovered — and passed us cleanly.

Same behaviour, two verdicts. Do the spec-correct thing, and be ready to explain the red badge.

3. Instrument the endpoint, or you are flying blind

We added a small table that records one row per JSON-RPC request: method, tool name, client name, auth type, ok/error, duration. Fire-and-forget, so a failed insert can never break a tool call.

The first day of data was not what we expected. Roughly 200 unauthenticated initialize calls, from clients we had never heard of:

mcpbeat 0.1                  every ~15 minutes
smithery-probe
agent-tools.cloud 0.1
zdi-well-wirer 1.0
agentic-resource-search 0.4
trimtab-verifier 0.1
glama-mcp-inspector 1.0.0

We did not submit to most of these. There is an active crawler ecosystem discovering MCP endpoints on its own, and it is far busier than the human traffic. Someone also called this/method/does/not/exist, presumably checking whether our error handling was sane.

One practical detail: MCP is stateless, so only initialize carries clientInfo. Every other request would be anonymous. We fall back to the first token of the User-Agent and keep it raw rather than mapping it to friendly product names — a guess would quietly produce wrong statistics. That is how we know a real call came from claude-code/2.1.231 rather than "probably Claude".

If you are adding OAuth, also put the client id into the access token as a claim. Then every later call tells you which client it came from without any session state.

4. Cursor's one-click install link is broken below 3.15.12

We added the usual install deeplink to our docs page:

cursor://anysphere.cursor-deeplink/mcp/install?name=NAME&config=BASE64_CONFIG

where the base64 payload for a remote server is simply:

{ "url": "https://example.com/mcp" }

On an older Cursor build, clicking it brings the app to the front, opens the settings pane, and shows no install card at all. Nothing is added; nothing errors. It looks like your link is malformed.

It is not. There is a bug report on Cursor's own forum describing exactly this, and a team member confirming it was fixed in 3.15.12+. If you ship one of these buttons, add a line telling people on older builds to add the server URL manually — otherwise the silent failure reads as your bug.

The small stuff that also helped

Add outputSchema and the readOnlyHint / destructiveHint / idempotentHint / openWorldHint annotations to every tool. Directory scanners read them, and reviewers notice when they are missing.
resources/list and prompts/list will be probed even if you never declared those capabilities. Returning -32601 is spec-legal, but it shows up as a warning in scanner logs.
If a tool costs the user money, say so in the tool description and tell the model to ask first. Ours returns a candidate list plus an explicit note about the per-check cost, and instructs the assistant to verify one at a time and stop at the first good result. Models follow that instruction well, and it is the difference between a useful tool and one that burns a stranger's credits.

None of this is hard once you know it. It just is not written down in one place, which is why I wrote it down.

How to verify email addresses in real time with a Node.js API

Tolga Cakular — Thu, 23 Jul 2026 15:25:47 +0000

Every signup form is a magnet for bad email addresses — typos like jhon@gmial.com, throwaway inboxes, and addresses that simply don't exist. Let them into your list and you pay for it later: bounces, a wrecked sender reputation, and your real emails landing in spam.

The fix is to verify an address before you trust it. Here's how to do it in real time from Node.js.

What "verifying" actually means

A good check goes well beyond a regex. It looks at:

Syntax — is it a well-formed address?
MX records — does the domain actually accept mail?
SMTP — does the specific mailbox exist?
Disposable — is it a 10-minute throwaway?
Role-based — info@, support@ (low engagement)
Catch-all — the domain accepts everything, so you can't be 100% sure
Typos — gmial.com should probably be gmail.com

Calling the API

// verify.js
const API_KEY = process.env.CLEARBOUNCE_API_KEY;

async function verifyEmail(email) {
  const res = await fetch("https://api.clearbounce.net/api/v1/verify", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify({ email }),
  });

  if (!res.ok) throw new Error(`Verify failed: ${res.status}`);
  return res.json();
}

A response looks like this:

{
  "status": "deliverable",
  "score": 98,
  "isDeliverable": true,
  "checks": {
    "syntax": true,
    "mxRecords": true,
    "smtpValid": true,
    "isDisposable": false,
    "isRoleBased": false,
    "isCatchAll": false,
    "hasTypo": false
  }
}

status is one of deliverable, undeliverable, risky, or unknown, and score (0–100) tells you how confident the result is.

Gating a signup with it

app.post("/signup", async (req, res) => {
  const { email } = req.body;
  const result = await verifyEmail(email);

  if (result.status === "undeliverable") {
    return res.status(400).json({ error: "That inbox doesn't exist — please double-check it." });
  }

  if (result.checks?.isDisposable) {
    return res.status(400).json({ error: "Please use a permanent email address." });
  }

  // "risky" (catch-all / role) → let them in, but flag it for a later re-check
  await createUser({ email, emailRisk: result.status === "risky" });
  res.json({ ok: true });
});

Two habits that keep your list clean

Verify at the point of entry (real time, like above) so junk never gets in.
Re-clean the whole list periodically (bulk) — even good addresses go stale over time.

Full disclosure: I build ClearBounce, the verification API I used in the examples (it has a free tier if you want to try it). But the ideas matter more than the vendor — the same flow works with any real-time verification API.

DEV Community: Tolga Cakular