DEV Community: Yonyon

Elicitation didn't die in the MCP stateless rewrite. It's the only one that survived.

Yonyon — Thu, 06 Aug 2026 18:07:59 +0000

Most people I've talked to since the 2026-07-28 MCP specification landed believe
elicitation was killed along with the rest of the bidirectional surface. It wasn't. It's
the one that got invested in, and the asymmetry tells you something real about how to
think about safety primitives in a protocol.

What actually happened

The 2026-07-28 revision turned MCP from a stateful, bidirectional protocol into plain
request/response. Every request is self-describing, so any request can land on any
instance behind a round-robin load balancer.

That rewrite had to do something about the features that assumed an open connection:

feature	fate	SEP
Roots	deprecated	SEP-2577
Sampling	deprecated	SEP-2577
Logging	deprecated	SEP-2577
Elicitation	redesigned onto MRTR	SEP-2322

Deprecated does not mean gone. A formal deprecation policy (SEP-2596) guarantees a
twelve-month minimum window, so the first three still work.

But only one of the four was rebuilt.

Why elicitation got the different treatment

Roots and sampling are capabilities. They let a server do more.

Elicitation is a control. It lets a server do less, on purpose, until a human says
otherwise.

A protocol can drop a capability and leave users with a smaller feature set. If it drops
the control, every tool that guards an irreversible operation loses its guard, and the
failure is silent, because the tool just starts succeeding. That asymmetry is why elicitation
was worth the cost of a redesign.

What elicitation is

A server, mid tool call, pauses and asks the user a question.

Without it, a tool either runs or refuses. With it, a tool can stop halfway and say
"this will delete 40 records, confirm?" and block until answered.

In a production MCP deployment this typically guards the operations a retry cannot
undo: outbound messaging, content publishing, record deletion.

Old mechanism vs MRTR

Before. The server pushes a request down an open bidirectional stream to the client
and blocks waiting for the answer. This requires a persistent connection, precisely what
the stateless core removes.

After (MRTR, SEP-2322). The server returns an ordinary response:

{ "resultType": "input_required", "requests": [ ... ] }

The client collects answers from the user, then retries the original tool call with
them attached in inputResponses. Each leg is a complete request/response cycle.

The 4.x implementation states the philosophy directly in its own docstring:

The protocol is stateless: each MRTR leg is a complete request→response cycle. When a
guard tool returns an InputRequiredResult from its body to ask the client for input,
that ask is the legitimate result of this tool call — not a pause, not an error, not
a third control-flow outcome.

That framing matters for implementers. The ask flows through the middleware chain as an
ordinary return value. Middleware completes normally. You identify one with a plain
isinstance check rather than a special control path.

The trap: an empty schema is not a confirmation

Here is the part worth acting on today, regardless of which protocol version you're on.

FastMCP's Context.elicit takes a response_type. Passing None produces this schema:

{ "type": "object", "properties": {} }

The library documents it: "When response_type is None, the accepted elicitation will
contain an empty dict."

An empty dict means the accept payload carries no data. And that means a client that
auto-accepts produces bytes indistinguishable, on the wire, from a human clicking
approve.

I confirmed this against a running system. A delete tool executed its full delete path
with confirm=False. The gate existed in the code, was reached at runtime, and stopped
nothing.

The fix is not "add a confirmation step." It is to stop treating acceptance as the
signal and require an affirmative value:

CONFIRM: Final[list[str]] = ["cancel", "confirm"]
result = await ctx.elicit(message, response_type=CONFIRM)

Now approval carries information. An empty or absent response is not approval.

The part where two bugs turned out to be one bug

That corrected call needs the list[str] overload of elicit.

Under mypy, that overload did not exist.

Context.elicit declares six @overload stubs. Each stub's explanatory string sat
after the stub body rather than inside it, making it a bare expression statement rather
than a docstring. A statement between overloads terminates the overload series for mypy,
so mypy registered stub one and ignored the rest.

pyright and ty both tolerate it and see all six. Fixed upstream in
PrefectHQ/fastmcp#4774.

So the safest available call shape was the one the type checker reported as
nonexistent. The type bug and the security bug were the same bug, one layer apart.

Two things I verified that you may want to check yourself

response_type: None is removed in 4.0.0b1. In 3.x it was overload one and marked
deprecated. In the 4.x beta the first overload is response_type: type[T] and the None
variant is gone. The unsafe default deleted itself. If you already hardened to an
explicit value list, you are on the 4.x-correct shape ahead of the migration.

The overload fix is not in any release. Read from the PyPI JSON API:

latest stable      3.4.6     uploaded 2026-08-05    still has all six
newest 4.x         4.0.0b1   uploaded 2026-07-28    predates the fix, has five
4.0.0 stable       does not exist

The fix is on main. There is no 3.x maintenance branch. If you pin below the major, you
do not have it.

What to do this week

Grep for response_type=None in anything that gates an irreversible operation. That is the empty-schema path.
Add a second type checker as a non-blocking advisory job. Not to gate on. Just so something in your pipeline is capable of seeing what your primary checker cannot.
Write your dual-protocol contract tests now. The confirm gate has to hold on both an old-protocol client and a 2026-07-28 client through the twelve-month runway. The failure mode to test explicitly is a silent fall-through that auto-approves. Writing these before the SDK ships means the migration has a green target instead of being validated afterward.
Prove the gate is reached, not merely present. Revert the wiring, watch the new tests fail, restore. Green tests over unreachable code is the failure this catches.

A note on the scan

I checked whether the overload defect was widespread by AST-scanning a production
dependency tree for the construct: a bare string expression sitting between two
@overload definitions.

13,920 .py files. Six occurrences. All six in one file, all unintentional, all now
fixed upstream.

Worth stating because it cuts against the obvious conclusion. This is not a common
Python footgun you should go hunting for. It is a single localized mistake that survived
into a release because the checker that catches it was not the checker that project ran.

The typing specification, incidentally, does not cover this case at all. It requires only
that overload definitions "be followed by an overload implementation, which does not
include an @overload decorator", and says nothing about intervening statements. So
mypy is not right and ty is not wrong. Each picked a behavior in a gap, and a bug lived
in the gap between them.

The takeaway

A green gate proves that the checker you ran agrees with you. It does not prove the code
is right.

Three type checkers looked at that file. One saw the bug. The project shipped it running
one of the two that did not.

Upstream issue: PrefectHQ/fastmcp#4773
Upstream fix: PrefectHQ/fastmcp#4774
Spec: the 2026-07-28 MCP specification announcement, SEP-2322 / SEP-2577 / SEP-2596

The bug FastMCP's own CI could not see

Yonyon — Thu, 06 Aug 2026 18:07:57 +0000

I opened a pull request to FastMCP (27k stars) at 23:12:32 UTC. A bot closed it at 23:12:47. Fifteen seconds.

A second bot then labeled it too-long, with the comment: "condense this issue. We'll triage it once it's trimmed down."

It was merged the next day, unedited. Nobody condensed anything. The label is still on the merged PR.

That is the funny part. The bug underneath it is the useful part, because it is a failure mode that any project with a type-checking gate can be sitting on right now without knowing.

The bug

Context.elicit is FastMCP's "ask the human a question" primitive. It declares six alternative call signatures as @overload stubs, one per supported response_type.

Each stub's body was ..., and the explanatory prose sat after the body. Verbatim from fastmcp/server/context.py at 3.4.5, lines 1022 to 1061:

    @overload
    async def elicit(
        self,
        message: str,
        response_type: None,
        *,
        response_title: str | None = None,
        response_description: str | None = None,
    ) -> (
        AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation
    ): ...

    """When response_type is None, the accepted elicitation will contain an
    empty dict"""                                          # <-- not a docstring

    @overload
    async def elicit(
        self,
        message: str,
        response_type: type[T],
        *,
        response_title: str | None = None,
        response_description: str | None = None,
    ) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation: ...

    """When response_type is not None, the accepted elicitation will contain the
    response data"""

    @overload
    async def elicit(
        self,
        message: str,
        response_type: list[str],
        *,
        response_title: str | None = None,
        response_description: str | None = None,
    ) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation: ...

    """When response_type is a list of strings, the accepted elicitation will
    contain the selected string response"""

Three more follow the same pattern, six in total.

That string is not a docstring. A docstring has to be the first statement inside a function or class body. Here the body already ended at ..., so the string is a bare expression statement sitting in the class body, between two overloads.

And a statement between overloads terminates the overload chain for mypy.

Why only mypy

Here is the reduced shape. No FastMCP install needed, paste it into a file and run two checkers:

from typing import overload

@overload
def f(x: None) -> str: ...
"""Doc for the None case."""

@overload
def f(x: list[str]) -> int: ...
"""Doc for the list case."""

def f(x):
    return x

f(["a", "b"])   # mypy: error.  pyright: fine.

checker	overloads registered	verdict on the `list[str]` call
mypy	1 of 6	error, no call-site workaround
pyright	6 of 6	fine
ty	6 of 6	fine

pyright and ty tolerate the interleaved statement and keep collecting overloads. mypy stops.

FastMCP's own gate is ty. So the project's CI was green on a file that was broken for a large share of its users, and it stayed that way through a release.

Why it actually bit

Two details turn this from a style nit into a live problem.

First: the one stub mypy could still see is the deprecated one. In the 3.x line the first overload is response_type: None, which the library's own docstring marks as deprecated. So mypy users were being funneled toward exactly the call shape the library is retiring. There is no way out at the call site either. I tried five formulations (explicit annotation, cast, a typed local, a Sequence[str] alias, direct literal). All five fail under mypy. All five pass under pyright.

Second: I needed the invisible signature for a security control.

response_type=None compiles to an empty JSON schema:

{"type": "object", "properties": {}}

The library documents this itself, in the very docstring that broke the overload chain: "When response_type is None, the accepted elicitation will contain an empty dict."

An empty dict means the accept payload carries no data. A client that auto-accepts produces bytes that are indistinguishable, on the wire, from a human clicking approve. I proved that with a live probe a week earlier, when a delete tool ran its full delete path with confirm=False.

The hardening is to stop treating "accepted" as a signal and require an affirmative value:

CONFIRM: Final[list[str]] = ["cancel", "confirm"]
...
result = await ctx.elicit(message, response_type=CONFIRM)

list[str]. One of the five overloads mypy could not see.

The fix

Move each literal inside its stub body, where it becomes an actual docstring:

    @overload
    async def elicit(
        self,
        message: str,
        response_type: None = None,
    ) -> AcceptedElicitation[None] | DeclinedElicitation | CancelledElicitation:
        """The accepted elicitation will contain no data"""

+15 / -24, one file. No runtime change, no API change. The implementation function is byte-identical before and after (I hashed it). The deletion count is larger than the addition count only because dropping the trailing ... let ruff format collapse two return annotations onto fewer lines.

The timeline

Every timestamp below is from the GitHub timeline API.

08-05 22:36:16Z  issue opened
08-05 23:12:32Z  PR opened
08-05 23:12:47Z  auto-CLOSED, 15 seconds later
                 (missing-issue-link: external PRs must reference an
                  issue ASSIGNED to their author)
08-05 23:14:09Z  bot labels it `too-long`
                 "Excessively verbose or unedited LLM output.
                  Condense before triage."
                 ... ~14 hours of silence ...
08-06 13:29:05Z  maintainer assigns the issue
08-06 13:29:17Z  label removed, PR auto-REOPENS
08-06 13:29:30Z  APPROVED, 13 seconds later
08-06 13:34:12Z  a second PR merges, see below
08-06 13:35:50Z  MERGED

The part I did not expect

Twenty-eight seconds after approving my PR, the project lead opened a branch named codex/review-closed-contributor-prs and merged it four minutes later. It adds a line to FastMCP's own CLAUDE.md, the file that instructs their review agents:

Review closed contributor PRs. External PRs may be closed as part of the issue-link workflow, so closure alone is not a negative signal.

Then my PR merged.

I want to be precise about what I am claiming here: there is no explicit cross-reference between those two pull requests. I am reporting the order of events and the twenty-eight second gap. Draw your own conclusion.

It is a good line to add either way. When a repo automates triage, "this PR is closed" stops meaning "a human rejected this" and starts meaning "a bot ran." Anything downstream that reads closure as a signal, human or agent, is now reading a stale convention.

Status, honestly

Merged to main, which is the 4.x line, 289 commits ahead of the latest release. It is not in any release.

v3.4.6   released 08-05   still has all six stray literals   <- PyPI serves this
main     merged   08-06   fixed

There is no 3.x maintenance branch on the repo. If you pin fastmcp>=3.4.5,<4, as I do across eleven packages, you consume the broken version until someone backports it or you move to 4.x.

Also worth saying plainly: this never broke my own CI, because my gate is ty, not mypy. It breaks downstream consumers of my package who run mypy. I found it by running a checker my project does not run.

The takeaway

A green gate proves that the checker you ran agrees with you. It does not prove the code is right.

Three type checkers looked at this file. One saw the bug. FastMCP happened to run one of the two that did not, and shipped it. I happened to run the third, for unrelated reasons, on code I needed for a security fix.

If you maintain a typed Python library, the cheap version of this lesson is: run a second checker in a non-blocking job. You do not have to fix what it finds. You just have to be able to see it.

Issue: PrefectHQ/fastmcp#4773
PR: PrefectHQ/fastmcp#4774

One operator. An army of minds.

Yonyon — Sat, 18 Jul 2026 06:47:34 +0000

One operator. An army of minds.

63 sessions · 5,173 agents · 12,658 tool events — my actual Claude Code telemetry rendered as one comic splash.

The numbers are real. The cape is aspirational.

AI agents shouldn't grade their own homework

Yonyon — Sun, 12 Jul 2026 09:18:52 +0000

Your AI coding agent just said "Done ✅".

Who checked? The same agent that wrote the bug.

This is the structural blind spot of agentic coding, and no amount of "please double-check your work" in the prompt fixes it. An LLM that just wrote the code is the worst-positioned reviewer of it — it shares the exact context, assumptions, and blind spots that produced any bug. A self-graded "done" is a claim, not evidence.

So I stopped letting my agent grade its own homework. Here's the gate I built into Claude Code, and the portable pattern underneath it.

The pattern

claim → independent re-derivation → human ratification → automated trigger

Four parts, each closing a specific failure mode. Nothing here is Claude-specific — it's a template for any agent that reports its own success.

1. Independence beats "check harder"

The fix isn't a better prompt telling the agent to re-read its diff. It's an independence boundary: a fresh, adversarial subagent — explicitly told to disprove the claim — re-verifies from scratch against live running state. Not the diff. Not the plan the author already believed. The actual output of the actual system, right now.

I ran this on a real refactor. The verifier re-ran the tests itself, re-checked the commits were pushed, grepped for dead code the main agent claimed to have removed, and returned a structured verdict:

VERDICT: 6/6 passed

Different context catches what the author is constitutionally blind to. A second cheap pass beats the original agent trying harder — because "harder" still runs through the same blind spot.

2. A verdict is not a decision

The machine verifies; the human ratifies. The verdict surfaces through a sign-off gate with three explicit paths:

✅ accept — close it out
🔍 show-evidence — re-run a specific check live, in front of me, first
❌ reject — treat as a bug report

"Show-evidence" is the one that matters. It turns the operator from a rubber-stamp on a green checkmark into someone the agent has to defend the claim to with artifacts. In Claude Code this is the AskUserQuestion tool; in your stack it's whatever forces a human to say yes on the record.

3. Automate the trigger, or it never fires

A verification step you have to remember to run is a verification step you skip under deadline. So the whole gate is triggered by a Stop hook that fires after the agent edits files:

# verify-done-nudge.py — a Claude Code Stop hook
if payload.get("stop_hook_active"):
    return  # LOOP GUARD: this Stop follows our own block — let it through

# ... only fires if the turn used Edit/Write/MultiEdit
# ... and stays silent if recent text already shows verify/tests/PASS/pushed

print(json.dumps({
    "decision": "block",
    "reason": "You edited files but haven't verified. Run /verify-done "
              "(independent re-check + sign-off) before declaring complete."
}))

Automate the trigger, not the judgment. That's the difference between a gate and a good intention.

4. The engineering that makes it safe

The credibility (and the interesting part) is in the guards. This hook runs on every Stop event, so it has to be bulletproof:

Loop guard. A Stop hook that re-invokes the agent could recurse forever. Claude Code sets stop_hook_active = true on the Stop that follows your own block — check it and bail, so the gate fires at most once per work-cycle.
Fail-open. Any error — missing transcript, malformed JSON, anything — returns cleanly and lets the session end. A broken verifier should never block you from finishing work. It degrades to the old behavior; it doesn't brick your session.
No LLM in the hook. Pure shell, no network, no model call — just a bounded tail-read of the transcript. A hook that calls an LLM bills silently on every turn and can time out. The hook decides whether to nudge; the agent does the thinking.

Where it fits in a workflow

One subtlety if you orchestrate multi-agent workflows: the verify phase can run inside a background workflow (fan out several adversarial verifiers in parallel, return a verdict), but the confirm phase can't — an interactive sign-off has to happen on the main thread. So: the workflow verifies, the main thread confirms with the returned verdict. Keep the human ratification out of the background.

Steal the pattern

claim → independent re-derivation → human ratify → automated trigger

If your agent can say "done," it can say it too soon. Give it a hostile second opinion, make a human ratify, and wire the trigger so the check can't be skipped when it's inconvenient.

Separation of powers — applied to a single agent's workflow.

OrchestKit scored 83/100 on ORA — what "agent-readiness" actually measures

Yonyon — Wed, 17 Jun 2026 06:43:34 +0000

I ran OrchestKit — my open-source Claude Code toolkit — through ORA, an independent audit that scores how agent-ready a product is: how easily an AI agent can discover you, identify itself, authenticate, and actually get work done against your surface.

Result: 83/100, Grade B ("Competitive"), ranked #49 of 12,200.

The breakdown

Layer	Score
Auth & Access	28/30	🟢 Strong
Agent Integration	18/20	🟢 Strong
Identity	18/20	🟢 Strong
User Experience	10/10	🟢 Perfect
Discovery	9/20	🟠 Partial

What I take from it

The foundation is strong: an agent can identify, connect, and use OrchestKit with near-zero friction — exactly what an agent-native toolkit should be.

The one hole is Discovery — presence, not product. The thing is ready; it just needs more people (and agents) to know it exists. Honestly the most fun problem to have, and it's the next focus.

Solo-built. Open-source. Independently verified.

→ https://orchestkit.yonyon.ai

Making your docs site agent-readable: llms.txt, MCP, and the .well-known files that actually matter

Yonyon — Sun, 14 Jun 2026 17:13:20 +0000

AI agents increasingly read your docs instead of a human. If your documentation site only emits HTML for a browser, an agent has to scrape and guess. There's a better surface — and most of it is a handful of small, standard files. Here's the full stack we ship on the OrchestKit docs site, why each piece exists, and how to verify it.

1. `llms.txt` — the agent's table of contents

A plain-text index at /llms.txt: what the product is, its constraints, and a link map to every machine-readable resource. Keep it under ~30k chars; put the exhaustive page list in /docs/llms.txt and the full corpus in /llms-full.txt. The win: an agent gets oriented in one fetch instead of crawling.

2. Markdown content negotiation

Append .md to any page URL (or send Accept: text/markdown) and return the raw Markdown. Agents get clean tokens; humans still get the rendered page.

3. An OpenAPI spec for your read APIs

Even a docs site has an API surface (search, page fetch). Publish an OpenAPI document at a predictable path so an agent can call it without reverse-engineering. Pair it with RFC 9727 — a /.well-known/api-catalog linkset that enumerates every API entry point.

4. An MCP server

The Model Context Protocol lets agents call your tools natively. We expose a read-only MCP server over Streamable HTTP at /api/mcp plus a discovery server-card.json. Two tools — search docs, get a doc by id — are enough to be useful.

5. The `.well-known` identity files

agent-card.json (A2A): declares your agent skills.
agent-skills/index.json: the Agent Skills Discovery RFC, with a SHA-256 digest per skill so a consumer can verify it.
oauth-protected-resource (RFC 9728): if your API is anonymous, say so — an empty authorization_servers is a positive signal, not an omission.

6. JSON-LD that an entity graph can reconcile

Emit a schema.org graph (Organization, SoftwareApplication, WebSite) linked by @id, with sameAs pointing at the registries that already verify you (GitHub, your package registry, Wikidata). One canonical Organization block, reused everywhere, so the graph never sees conflicting identifiers. Never fabricate an aggregateRating — surface real signals (e.g. GitHub stars as an InteractionCounter) instead.

7. Tell crawlers the truth in `robots.txt`

Explicitly allow the named AI crawlers you want (GPTBot, ClaudeBot, OAI-SearchBot, Google-Extended…), and emit a Content-Signal directive. Link your sitemap and a schema-map.

How to verify

curl -s https://yoursite/llms.txt, fetch each .well-known path, and run your JSON-LD through a structured-data validator. If you build on Claude Code, the open-source OrchestKit docs site implements every item above — the source is on GitHub, MIT-licensed, and you can read the route handlers directly.

I maintain OrchestKit (a free, MIT plugin for Claude Code, 111 skills/37 agents/210 hooks). The agent-discovery surface described here is what its docs site ships today.

I made my portfolio readable by AI agents. A scanner found four things that didn't exist

Yonyon — Thu, 11 Jun 2026 16:42:20 +0000

Last week I wrote about making my site fully agent-readable — an MCP server, an NLWeb /ask endpoint, llms.txt, a .well-known/ discovery tree. Shipping those was the easy half.

Then I started scoring the site with an agent-readiness scanner — a prober that visits like a real agent: no JavaScript execution, spec-shaped requests, no goodwill. Every round it found something that worked in my browser and did not exist as far as an agent could tell.

These are the four that stung. All real code from yonyon.ai, all fixed this round.

1. The "helpful" GET that made my endpoint read as missing

My /ask endpoint (Microsoft's NLWeb shape) answered POST { "query": "..." }. For GET, I did what felt like good API manners — return a machine-readable descriptor telling the caller how to use the endpoint:

// GET /ask — the old version
export function GET(): Response {
  return Response.json({
    _meta: { response_type: "nlws", version: NLWEB_VERSION },
    description: 'POST { "query": "..." } for answers...',
    method: "POST",
  });
}

Polite, self-documenting, useless. The NLWeb reference client — and therefore the scanner — issues GET /ask?query=... and expects an answer. It got my descriptor back, which is not an answer, so the endpoint graded as not implemented. My documentation-instead-of-data response was indistinguishable from a stub.

The fix: GET with a query parameter runs the real pipeline (including SSE via ?streaming=true); a bare GET keeps the descriptor.

export async function GET(req: Request): Promise<Response> {
  const url = new URL(req.url);
  const hasQuery = ["query", "q", "question"].some((k) => url.searchParams.get(k)?.trim());
  if (hasQuery) return handleAsk(req); // same pipeline as POST, SSE supported
  return descriptor(); // bare GET still teaches probing agents how to call it
}

Lesson: agents don't read your descriptor and adapt — they call you the way their reference client calls everyone. Implement the spec's client behavior, not your idea of good manners.

2. The WebMCP tools nobody could see

I exposed in-browser tools via WebMCP (navigator.modelContext, Chrome early preview): ask_yonatan, browse_projects, book_intro_call. The natural React implementation is a client component:

"use client";
export function WebMcpTools() {
  useEffect(() => {
    const provide = (navigator as any).modelContext?.provideContext;
    if (typeof provide !== "function") return;
    provide.call(navigator.modelContext, { tools: [/* ... */] });
  }, []);
  return null;
}

Feature-detected, try/caught, tidy. Also invisible. Crawlers and scanners detect WebMCP support by scanning the unhydrated document — they don't run your bundle, and even executing browsers without the experimental API skip the registration entirely. A hydration-gated capability has no static trace. As far as any external observer was concerned, the site had no WebMCP support at all.

The fix is almost embarrassing: a server component that emits the registration as an inline <script>, so it's right there in the raw HTML:

// Server component — no hydration involved
const WEBMCP_REGISTRATION = String.raw`(function () {
  var mc = navigator.modelContext;
  if (!mc || typeof mc.provideContext !== "function") return;
  mc.provideContext({ tools: [ /* same tools, plain JS */ ] });
})();`;

export function WebMcpScript() {
  return <script dangerouslySetInnerHTML={{ __html: WEBMCP_REGISTRATION }} />;
}

(Next.js already requires 'unsafe-inline' in CSP, so this adds no new policy cost. If your CSP is stricter, use a nonce.)

Lesson: a runtime-registered agent capability needs a statically visible twin. If it can't be seen in curl output, it doesn't exist.

3. The status page that 404'd in production only

I added /status — a tiny health page with content negotiation: JSON for Accept: application/json, HTML for humans. It worked in dev. In production: 404.

The culprit was next-intl's middleware. My site is internationalized, and the middleware matches every page-ish path and routes it into the [locale] tree. I'd even left myself a comment claiming route handlers escape the middleware. They don't. Bare /status was being locale-routed into /[locale]/status, which doesn't exist.

// src/proxy.ts — the matcher had to exclude /status explicitly
export const config = {
  matcher: "/((?!api|studio|trpc|_next|_vercel|status|.*\\..*).*)",
};

And there was a second bug hiding behind the first: I'd marked the route force-static for cheapness. Static means Next.js prerenders one variant — with an empty Accept header — and serves that frozen response to everyone. My own content negotiation could never run. It had to be force-dynamic with Vary: Accept.

Lesson: i18n middleware and agent endpoints fight over the same URL space, and the agent endpoints lose silently. Every bare path you promise agents (/ask, /mcp, /status) needs an explicit carve-out — and content negotiation is incompatible with static prerendering by definition.

4. `ai-train=yes`, on purpose

Most advice about AI crawlers is defensive: block GPTBot, block CCBot, opt out of training. My robots.txt does the opposite, explicitly:

# Content Signals (https://contentsignals.org). Discovery is a goal for this
# site, so AI training is allowed — being in training corpora is the point.
Content-Signal: search=yes, ai-input=yes, ai-train=yes

This is a portfolio. Its entire job is to be found when someone — increasingly, someone's agent — asks "who can build a production RAG system?" An assistant that learned about my work during training, or retrieves it at inference time, is doing my marketing. Blocking that to protect content whose value is being known would be self-defeating.

That trade-off is deliberate and it isn't right for everyone — if your content is the product, sell it, don't donate it. But make the choice consciously. The default-deny advice assumes your content's value is captured by humans reading it on your domain. For a personal site optimizing for discovery, the math runs the other way. (The same file blocks Bytespider and other bulk scrapers that offer no assistant or search surface — welcome the tier that cites you, refuse the tier that doesn't.)

The pattern under all four

"Agent-readable" turned out to be two separate properties, and I kept confusing them:

Works when called correctly — the endpoint answers, the tool executes.
Discoverable by something that won't call you correctly — no JS execution, spec-default request shapes, bare paths, raw HTML.

Everything above failed on the second property while passing the first. My browser hydrated the WebMCP component; the scanner read static HTML. My docs explained POST /ask; the prober sent GET. Dev served /status; production's middleware ate it.

The only thing that caught any of this was pointing an external, JS-free, spec-literal scanner at the production domain and treating its score as the truth. Your own browser is the worst possible test client for agent-readability — it's too forgiving.

The full implementation (MCP server, NLWeb endpoint, llms.txt, .well-known tree) is covered in part one. Try the live surfaces: curl -X POST https://yonyon.ai/ask -d '{"query":"what does yonatan build?"}' or GET https://yonyon.ai/status with Accept: application/json.

How I made my website fully agent-readable: an MCP server + NLWeb /ask in Next.js

Yonyon — Tue, 09 Jun 2026 10:13:55 +0000

How I made my website fully agent-readable: an MCP server + NLWeb /ask in Next.js

Most websites are built for humans with browsers. Increasingly, the visitor is an AI agent — Claude, a custom assistant, some autonomous tool — and it doesn't want your hero animation. It wants structured, machine-readable answers and actions it can take.

I rebuilt my own site, yonyon.ai, to be readable and usable by agents end to end: a live /ask endpoint (Microsoft's NLWeb shape), a real MCP server at /mcp, in-browser WebMCP tools, plus llms.txt and a .well-known/ discovery tree. This post is the worked example — the three pieces that did the heavy lifting, with the actual code.

The trap: locale routing eats your agent endpoints

My site is internationalized with next-intl. Its middleware matches every path and routes it into a [locale] segment. So the moment I added a bare /ask route for agents, the i18n middleware grabbed it first and tried to render /[locale]/ask — 404. Same problem would hit /mcp.

Agents expect bare, unprefixed paths (/ask, /mcp) — not /en/ask. The fix is to intercept those paths in the proxy/middleware, before the i18n matcher runs, and rewrite them onto the real API route. rewrite() (not redirect()) preserves the HTTP method and body, so a POST /ask stays a POST:

// src/proxy.ts  (next-intl middleware entrypoint)
import createMiddleware from "next-intl/middleware";
import { NextResponse, type NextRequest } from "next/server";
import { routing } from "./i18n/routing";

const intlMiddleware = createMiddleware(routing);

export default function proxy(request: NextRequest) {
  // Rewrite the bare /ask onto the /api/ask route handler BEFORE next-intl
  // pulls it into the [locale] tree (which would 404). rewrite() keeps the
  // method + body, so POST /ask works.
  if (request.nextUrl.pathname === "/ask") {
    return NextResponse.rewrite(new URL("/api/ask", request.url));
  }
  return intlMiddleware(request) as NextResponse;
}

export const config = {
  // Skip /api, /_next, static files, etc. — only run on page-ish paths.
  matcher: "/((?!api|studio|trpc|_next|_vercel|.*\\..*).*)",
};

That's the whole alias trick: bare agent paths are matched first and rewritten into /api/*, so they never reach the locale router. Add a line per endpoint you want to expose unprefixed.

A dependency-free MCP server

The Model Context Protocol is how agents discover and call your tools. The official SDK is great — but it peer-depends on zod 3, and my repo is on zod 4. Rather than fight the dependency tree, I hand-rolled the handler. MCP's Streamable-HTTP transport is just JSON-RPC 2.0 over POST, and I only needed a handful of methods: initialize, tools/list, tools/call, ping. Zero dependency risk:

// src/app/api/mcp/route.ts
export const dynamic = "force-dynamic";

const SERVER_INFO = { name: "yonyon.ai", version: "1.0.0" };
const PROTOCOL_VERSION = "2025-06-18";

const TOOLS = [
  {
    name: "ask_yonatan",
    description: "Ask about Yonatan Gross's work, projects, or experience.",
    inputSchema: {
      type: "object",
      properties: { question: { type: "string", maxLength: 2000 } },
      required: ["question"],
      additionalProperties: false,
    },
    // Behavioural hints so agents can reason about side effects:
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
  },
  // browse_projects, book_intro_call ...
];

const rpc = (id, result) => Response.json({ jsonrpc: "2.0", id, result });
const rpcError = (id, code, message) =>
  Response.json({ jsonrpc: "2.0", id, error: { code, message } });

export async function POST(req: Request) {
  const { id, method, params } = await req.json();

  if (method === "initialize")
    return rpc(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });

  if (method === "tools/list") return rpc(id, { tools: TOOLS });

  if (method === "tools/call") {
    const { name, arguments: args } = params;
    if (!TOOLS.some((t) => t.name === name))
      return rpcError(id, -32602, `Unknown tool: ${name}`); // structured error, not soft text
    return rpc(id, await callTool(name, args));
  }

  if (method === "ping") return rpc(id, {});
  return rpcError(id ?? null, -32601, `Method not found: ${method}`);
}

Two details that matter for agent ergonomics:

Tool annotations (readOnlyHint, destructiveHint, openWorldHint) let a planner decide whether a tool is safe to call autonomously.
An unknown tool returns a structured JSON-RPC error (code + message), not a friendly text blob — so agents branch on it programmatically instead of string-matching.

Discovery: llms.txt + .well-known

Endpoints are useless if nothing can find them. Two conventions cover it:

/llms.txt — a human- and agent-readable map of the site, modeled on robots.txt but for LLMs: who you are, what an agent can do here, and the exact endpoints:

# yonyon.ai — Yonatan Gross

> AI Platform Engineer & Backend Developer. Builds production AI systems
> end-to-end: RAG pipelines, multi-agent architectures, MCP servers.

## What an agent can do here
- Ask about my work — POST /ask with {"query":"..."}  (NLWeb, no auth)
- Browse projects, book a free 15-min intro call
- MCP server at /mcp (initialize, tools/list, tools/call)

The .well-known/ tree carries the machine-readable specs:

public/.well-known/
├── mcp.json                 # points agents at /mcp
├── mcp/server-card.json     # MCP server identity card
├── openapi.json             # OpenAPI for the HTTP endpoints
├── api-catalog              # RFC 9727 linkset of all APIs
└── agent-skills/            # discrete "skills" (ask, browse, book) as SKILL.md

Because these live in public/, they're served as plain static files — bypassing the locale router entirely, so there's no dotpath/404 issue. I also emit RFC 8288 Link headers (rel="describedby" → llms.txt, rel="service-desc" → openapi.json) so an agent that only fetches headers still discovers everything.

The payoff

You can verify it live:

curl -s https://yonyon.ai/ask \
  -H 'content-type: application/json' \
  -d '{"query":"What does Yonatan build?"}'

That single-shot, no-auth, agent-facing endpoint returns a grounded answer from the same RAG-backed model that powers the site chat. An agent can then call the MCP book_intro_call tool and act.

Building agent-ready surfaces is also just good practice for the corpus AI models train on — the more structured and citable your presence, the more likely a model recalls your work. I package these patterns (and a lot more) as OrchestKit, my open-source Claude Code agent framework — 111 skills, 37 agents, 211 hooks.

If you're making something agent-readable and want a second pair of eyes, the front door at yonyon.ai is itself the demo — ask it a question, or grab a free 15-minute intro call.

Building an Automated Content Pipeline That Posts to 6 Platforms

Yonyon — Thu, 12 Mar 2026 10:32:21 +0000

Every developer knows the pain: you write a great article, publish it on one platform, and then spend the next hour manually reformatting and posting it everywhere else.

I built an automated content distribution pipeline that publishes to 6 platforms from a single source of truth. Here's how.

The Architecture

Write once, distribute everywhere:

Hashnode (source of truth)
Dev.to (you're reading this here)
LinkedIn (article share + commentary)
Threads (text teaser)
Instagram (card image + caption)
daily.dev (auto via RSS)

Each platform gets a tailored variant — not a blind copy-paste.

The Platform Adapter Pattern

Each platform implements a common interface with a single publish() method. Adding a new platform is just implementing one class. Rate limiting is Redis-backed per platform.

Smart Content Composition

The hardest part isn't the API calls — it's making content feel native. Twitter gets a 280-char hook. Threads gets a 500-char teaser. LinkedIn gets a 3,000-char article share.

The Quality Ladder

Ollama (local, free) generates the first draft
Quality gate checks readability and boring-start patterns
Claude Haiku polishes if needed (~$0.002)
Template fallback as safety net

The Feedback Loop

A weekly task evaluates performance, extracts patterns, and injects learnings into future prompts. The system gets smarter over time.

The Stack

Python 3.13, FastAPI, SQLAlchemy 2 async, Celery
Next.js 16, TypeScript, TanStack Query
AI quality ladder (Ollama → Haiku), RAG, pgvector
1Password secrets, Redis rate limiting

This post was cross-posted using the pipeline described above.

DEV Community: Yonyon

Elicitation didn't die in the MCP stateless rewrite. It's the only one that survived.

What actually happened

Why elicitation got the different treatment

What elicitation is

Old mechanism vs MRTR

The trap: an empty schema is not a confirmation

The part where two bugs turned out to be one bug

Two things I verified that you may want to check yourself

What to do this week

A note on the scan

The takeaway

Links

The bug FastMCP's own CI could not see

The bug

Why only mypy

Why it actually bit

The fix

The timeline

The part I did not expect

Status, honestly

The takeaway

Links

One operator. An army of minds.

AI agents shouldn't grade their own homework

The pattern

1. Independence beats "check harder"

2. A verdict is not a decision

3. Automate the trigger, or it never fires

4. The engineering that makes it safe

Where it fits in a workflow

Steal the pattern

OrchestKit scored 83/100 on ORA — what "agent-readiness" actually measures

The breakdown

What I take from it

Making your docs site agent-readable: llms.txt, MCP, and the .well-known files that actually matter

1. llms.txt — the agent's table of contents

2. Markdown content negotiation

3. An OpenAPI spec for your read APIs

4. An MCP server

5. The .well-known identity files

6. JSON-LD that an entity graph can reconcile

7. Tell crawlers the truth in robots.txt

How to verify

I made my portfolio readable by AI agents. A scanner found four things that didn't exist

1. The "helpful" GET that made my endpoint read as missing

2. The WebMCP tools nobody could see

3. The status page that 404'd in production only

4. ai-train=yes, on purpose

The pattern under all four

How I made my website fully agent-readable: an MCP server + NLWeb /ask in Next.js

How I made my website fully agent-readable: an MCP server + NLWeb /ask in Next.js

The trap: locale routing eats your agent endpoints

A dependency-free MCP server

Discovery: llms.txt + .well-known

The payoff

Building an Automated Content Pipeline That Posts to 6 Platforms

The Architecture

The Platform Adapter Pattern

Smart Content Composition

The Quality Ladder

The Feedback Loop

The Stack

1. `llms.txt` — the agent's table of contents

5. The `.well-known` identity files

7. Tell crawlers the truth in `robots.txt`

4. `ai-train=yes`, on purpose