DEV Community: Ben Greenberg

What stateless MCP changes for gateways

Ben Greenberg — Mon, 05 Oct 2026 07:26:11 +0000

The MCP spec went stateless on July 28. If you run one MCP server, that mostly means deleting your session handling and adding a server/discover method. If you run a gateway that sits in front of a dozen MCP servers and presents them to clients as one, it changes how the whole thing works.

I've been following how Agent Router (the AAIF project formerly known as Envoy AI Gateway) is handling this. In September the team merged PR #2545, which adds stateless fan-out for discovery and list requests. It isn't serving traffic yet, and that's on purpose. But it's the clearest look so far at what an MCP gateway looks like once sessions go away.

What the gateway used to lean on

Under the old spec, a client opened a session with initialize and carried an Mcp-Session-Id on everything after that. Agent Router used that session as its backbone. When a client initialized, the gateway sent initialize to each backend on the route, collected each backend's session ID and capabilities, and packed all of it into one encrypted session ID that it handed back to the client.

From then on, each request carried what the gateway needed: which route this was, who the caller was, the upstream session ID for each backend, and what each backend could do. The gateway itself didn't have to remember anything. The client was carrying the gateway's memory around for it.

The 2026-07-28 spec removes all of that. There's no initialize handshake, no Mcp-Session-Id, and no session. Each request carries its own protocol version, client info, and client capabilities in _meta, plus Mcp-Method and Mcp-Name headers so infrastructure can see what the request is without parsing the body. If a client wants to know a server's capabilities up front, it calls server/discover. Server-initiated requests like elicitation and sampling become multi round-trip requests, where the server returns an input_required result and the client retries with the answer.

So the gateway had to find a new home for each piece of information that used to live in that session ID.

The same tools/list call looks different under each spec. Under 2025-11-25, the client has to open a session first and carry its ID from then on:

POST /mcp
Content-Type: application/json

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
  "protocolVersion": "2025-11-25",
  "clientInfo": {"name": "my-agent", "version": "1.4.0"},
  "capabilities": {}
}}

# Response header: Mcp-Session-Id: <encrypted gateway session>
# Client then sends notifications/initialized with that session ID

POST /mcp
MCP-Protocol-Version: 2025-11-25
Mcp-Session-Id: <encrypted gateway session>

{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}

Under 2026-07-28, there's no first step. The request names its own method in a header and brings its version, identity, and capabilities in _meta:

POST /mcp
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list
Authorization: Bearer <token>

{"jsonrpc": "2.0", "id": 7, "method": "tools/list", "params": {
  "_meta": {
    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
    "io.modelcontextprotocol/clientInfo": {"name": "my-agent", "version": "1.4.0"},
    "io.modelcontextprotocol/clientCapabilities": {}
  }
}}

Where each piece goes now

The design proposal for this work walks through it piece by piece, and most of the answers turned out to be things Agent Router already had.

The route name already arrives on each request in a header that Envoy sets. The old code only read it during initialize. Now it reads it on each request.

The backend for a single-target call like tools/call is already encoded in the tool name. Agent Router exposes tools as backend__toolname, so the name itself tells the gateway where to send the call. Under the new spec that name also shows up in the Mcp-Name header.

Per-backend session IDs aren't needed anymore, since modern backends don't have sessions either.

Identity comes from the bearer token on each request, which the gateway was already checking. With no session, there's also no session to hijack.

Capabilities are the one piece that needed new work. The gateway now asks each backend with server/discover and merges the answers.

What #2545 adds

The PR builds the stateless path for the five requests that have to go to more than one backend: server/discover, tools/list, resources/list, resources/templates/list, and prompts/list. The gateway sends the request to each selected backend, merges the responses, and returns one JSON-RPC result.

A few details stood out to me.

Backend selection happens on each request now. Under sessions, the set of backends a client could see got fixed at initialize. In the review thread, the author pointed out that re-evaluating on each request is the right stateless behavior, because a new token can change which backends a caller is allowed to see. Revoke someone's access to a backend and their next tools/list reflects it. Under the old model, they'd keep seeing it until their session ended.

Capability merging uses one shared helper for both the old session path and the new stateless path, so a capability advertised by any backend that answered shows up in the merged result the same way in both.

Cache hints from the new spec (ttlMs and cacheScope) get merged by taking the most restrictive values. If one backend says its tool list goes stale immediately, the merged list goes stale immediately. If any backend marks its results private, the merged result is private.

Put together, a merged response from a route with a docs backend and a tickets backend looks roughly like this. The tool names carry their backend as a prefix, which is how a later tools/call finds its way back. If docs said its list was good for 60 seconds and tickets said 30, the merged list gets 30:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "tools": [
      {"name": "docs__search", "description": "Search the docs", "inputSchema": {"type": "object"}},
      {"name": "tickets__create", "description": "Open a ticket", "inputSchema": {"type": "object"}}
    ],
    "ttlMs": 30000,
    "cacheScope": "public",
    "resultType": "complete"
  }
}

Partial failure doesn't take down the route. If one backend is unreachable or sends back something malformed, the gateway skips it, logs a warning with the backend's name, records an error metric for it, and returns what the others sent. If none of them answer, you get a 500 instead of an empty list that looks like a healthy server with no tools. One reviewer, mohitgurnani, pushed for that all-failed check to cover the four list handlers, not only discovery, and it went in before merge.

Why it isn't live yet

If you go looking for where the new code gets called, you won't find a caller outside the tests. That's the plan, not an oversight.

The proposal splits the work into phases. Phase 0 builds the entire stateless path as unreferenced code, one stage of the request lifecycle at a time: classifying the incoming request, selecting and discovering backends, forwarding and merging, then subscriptions/listen. The proposal says outright that nothing in Phase 0 is reachable and existing behavior doesn't change. Phase 1 is where the dispatcher gets flipped so requests from modern clients start going down the new path.

So #2545 is staged code waiting for activation. PR #2692, which covers single-target calls like tools/call and the integration work, was still open when I checked. subscriptions/listen is a separate follow-up.

What this enables once it's switched on

The biggest change is for whoever operates the gateway and the servers behind it. Agent Router's encrypted session ID already let any gateway instance handle any request, but the setup still started with an initialize sent to each backend on the route, and each backend kept its own session that later requests had to land on. Under the new model, nothing in the chain holds a session. A request carries what it needs, the gateway forwards it, and a stateless backend can answer it from whichever instance the load balancer picks. You can scale gateway instances and backend instances behind plain round-robin balancing without sticky routing, and the proposal explicitly rules out adding a shared session store like Redis for the modern path.

Routing gets cheaper too. One of the proposal's goals is to let Envoy route on the Mcp-Method and Mcp-Name headers without parsing the JSON-RPC body. That opens up per-tool rate limits, per-method policies, and routing decisions made at the edge from headers alone.

Approval flows get easier to run through a gateway. Under the old spec, a server that wanted to ask the user something mid-call needed an open stream back to the client, and the gateway had to rewrite request IDs to route answers back to the right backend. With multi round-trip requests, the backend returns input_required, the client retries with the answer, and the gateway routes the retry by tool name like any other call. The proposal plans to pass these through untouched.

Access changes take effect on the next request. Because backend selection runs per request, revoking a caller's access to a backend takes effect on their next call, not the next time they reconnect.

What I'd still watch

The fan-out talks to backends one after another, so a route with several slow backends adds up. And a partial result looks identical to a complete one from the client's side. If eight tools come back from a ten-backend route, the client can't tell whether that's everything or whether two backends dropped out. The author agreed that surfacing which backends failed would help but deferred it, since the old session path would need the same change to stay consistent. Until that lands, the per-backend logs and metrics are the only place to see it, so make sure your monitoring is watching them.

There's also a small inconsistency in the discovery response. It includes a line saying how many backends the gateway is aggregating, and that number counts the backends selected, not the ones that answered. With one of two backends down, it still says two.

The larger open piece is mixed deployments. Phase 1 covers modern clients talking to modern backends. A modern client reaching a backend that still uses sessions, or an older client reaching a stateless backend, needs the gateway to translate between the two models, and the proposal defers that to Phase 2. Its reasoning is that most new backends will ship on the new spec from day one. Whether that holds depends on how fast the MCP servers you already depend on upgrade.

Is Structured Human Input the Missing Link in Agentic Work?

Ben Greenberg — Thu, 24 Sep 2026 07:08:43 +0000

Have you ever told your agent to go do something and walked away? You set the spec clearly. You defined what done should look like. You provided reference materials. You expected to come back later and find it finished. Yet, you come back and its paused waiting for your input.

The times it needs input from you in unpredictable and uneven. This clearly does not scale.

A long-running task can pause for hours. By the time you return, you need to know what it’s waiting for, what answers are valid, and how your response reconnects to the right piece of work. Free-form text can carry an answer, but it can’t reliably describe the interaction that produced it.

A pause needs a contract.

A2A already has the right lifecycle shape

The Agent2Agent protocol models long-running work as a stateful Task. An agent can move a task into input-required, and a client can continue the interaction with the same contextId and, where appropriate, the same taskId.

That gives you a durable handoff point. The task has an identity, a state, and a history.

A2A messages can also carry structured JSON in a data Part. So the protocol already has room for a client to return something more dependable than, “yes, please proceed.”

What’s missing is a standard way for the agent to describe the input it needs when it pauses.

That gap is the focus of A2A Discussion #1016, opened on August 29, 2025. The proposal is direct: when a task enters input-required, the agent can provide an input schema for the client. A confirmation can become a boolean. A choice can become a list. The client no longer has to infer a form from an English sentence.

Text is a weak contract at the moment you need precision

Why does this break down? Because the text prompt is doing two different jobs.

It tries to explain a decision to a person, and it tries to define a data contract for software. Those are separate needs.

A framework-owned UI can make this work by knowing its own agent runtime. It can render a custom approval component, attach a callback, and translate the response into the format its agent expects. That’s fine inside one application.

The friction appears when the client and server are independent.

A generic A2A client can discover an agent through its Agent Card and run a task without knowing the agent’s framework. When that task pauses, the client should not need an adapter for every remote agent’s approval flow. It should be able to receive a declarative request, render an appropriate control, validate the answer, and send structured data back.

That’s the difference between a pause that works in a demo and one that travels across clients.

Human input is part of the workflow state

Treating human participation as unstructured chat also makes operational questions harder than they need to be.

Can an operator see which tasks are blocked on a decision? Can a client distinguish a request for approval from a request for missing account data? Can it route an approval to the person who has authority to make it?

Without a structured request, every client invents its own answer.

With one, the task can say what it needs at the same layer where it reports that it is waiting. The client can then present the request as a form, an approval screen, or an API action, while preserving the same task identity and response shape.

That does not require A2A to dictate a single UI. It gives the UI enough information to act without guessing.

There’s also a practical boundary here. A schema tells a client the shape of input, not whether the client should trust the requested action. The client still owns its policy: who may approve it, what must be shown before approval, and whether the request can proceed. A portable input contract makes those controls easier to build because the request is legible to software.

This belongs in an open agent ecosystem

The Agentic AI Foundation brings projects together around the protocols and infrastructure agents need to work across implementation boundaries. A2A’s task model is already a useful example of that work: agents can remain opaque while exposing enough state for another system to collaborate with them.

Human participation needs the same treatment.

An agent may call tools through MCP, delegate work through A2A, and run inside a client built by someone else. If it stops for a decision, that decision should not collapse back into framework-specific glue code. The request should move with the task.

This conversation is a serious next step in how we build agentic applications. The starting point is the question centered in Discussion #1016 and the work to advance it.

Jev vs Claude: Who Wins?

Ben Greenberg — Fri, 18 Sep 2026 11:15:07 +0000

I did not need Jev to beat Claude or Kimi on a benchmark. I needed to know whether I could trust it with a decision I actually make regularly, where a false pass matters and uncertainty cannot just be hidden behind confident prose.

That is a much harder test of the product claim.

The decision I actually needed

A surprising amount of AI work starts with the assumption that the answer should come from a large language model.

I wanted to challenge that assumption.

I had a useful test case in a judging workflow that I have iterated upon numerous times and use multiple times a year. The dataset I used for this experiment was from the 2026 Arbitrum Open House London Online Buildathon. One part of that workflow is an Arbitrum Alignment gate. Given the evidence already collected for a project, the system has to make one bounded decision:

satisfied, not_satisfied, or insufficient_evidence.

That is not a writing task.

The broader judging rubric absolutely contains work that benefits from a frontier LLM. There are 0 to 5 scores that require reading code, interpreting implementation quality, and weighing technical evidence. There are also prose fields where useful explanations need to be generated.

The full workflow never ends with a final score, rather a brief is given back to me, the human reviewer, to thoroughly analyze, source check and make a final call on.

I was not testing those.

I isolated the part of the workflow where the model is not being asked to write, brainstorm, explain, or synthesize an open-ended answer. It is being asked to apply a defined policy to a bounded evidence packet and choose one of three states.

That is almost exactly the territory TypeSafe claims Jev is built for.

So the question was not whether Jev could replace Claude, GLM, Kimi or Qwen.

It was whether those models were overkill for this decision in the first place.

A fair fight, deliberately narrow

I tested 102 archived submissions, anonymized as P-numbers.

Each system received the same JSON evidence packet and the same four-step written decision procedure. Every configuration ran three times across all 102 submissions, producing 306 decisions per variant. I ran it against Claude Sonnet.

There was no Jev specific simplification of the policy and no additional context given to Sonnet. Both systems had to answer the same question from the same evidence.

The narrowness of the test is important here because it relates exactly to what TypeSafe claims Jev is all about.

Jev is not a general-purpose text model. TypeSafe positions it as a System One model for structured decisions, with primitives such as Choice, Score, and Noul rather than free-form generation. Choice, the relevant primitive here, selects among a predefined set of outcomes and returns probabilities and confidence alongside the decision.

The workload also fit within Jev's current constraints. I was passing a structured evidence packet for one verification gate, not asking it to ingest an entire repository or execute the complete judging workflow.

That makes this a deliberately unfair place to make a sweeping model comparison.

It also makes it a very fair place to test Jev's actual claim.

If a model built specifically for bounded decisions cannot hold up here, then everything else about Jev pretty much falls to the sidelines.

Same accuracy band, radically different operating cost

No more suspense, the tl;dr is it held up.

Jev choice plus four diagnostic Nouls reached 100.0% accuracy against the existing labels across the 306 decisions. It produced zero false passes, zero false flags, and was unanimous across all three runs.

Claude Sonnet 5 at high reasoning reached 99.0%.

On the headline metric, that is effectively the same accuracy band: 100.0% versus 99.0%.

Then the economics diverge sharply.

Jev's median latency was 378 milliseconds.

Sonnet high's was 3,554 milliseconds.

That made Sonnet roughly 9.4 times slower on this task.

At the measured usage and pricing, 10,000 evaluations would cost approximately $2.27 with Jev and $129.74 with Sonnet high.

That is roughly a 57x difference.

This is where the experiment stops being an interesting model comparison and starts becoming a systems-design question.

If the output I need is one of three known states, and a decision-specific model can deliver comparable accuracy for roughly one-fiftieth the operating cost, what exactly am I buying from the generative model?

But raw accuracy gives good marks to both systems.

Of the 102 gold labels, 77 are satisfied, seven are not_satisfied, and 18 are insufficient_evidence.

A classifier that simply answered satisfied every time would already look pretty good on an accuracy chart while being completely unacceptable for the purpose of this gate.

The hard part is not recognizing the obvious passes. It is knowing what to do when the evidence is incomplete, ambiguous, or negative.

That is where the failures became much more interesting than the headline score.

Confidence that changes the workflow

This was the result that changed how I thought about Jev.

Jev Choice alone made two incorrect decisions across the 306 runs. Both landed in its 0.2 to 0.3 confidence range.

Sonnet high made three incorrect decisions. All three landed in its 0.9 to 1.0 confidence bin.

Jev's Expected Calibration Error was 0.037. Sonnet high's was 0.058.

Those numbers matter, but the workflow implication matters more.

At a Jev confidence threshold of 0.5, I could have automated 98% of the decisions in this dataset while retaining 100% accuracy among the automated decisions.

The remaining 2% could have gone to human review.

That is a far more useful property than simply being right slightly more often.

A model does not need to be perfectly accurate to be useful in an automated decision pipeline. It needs its uncertainty to correlate with the places where automation becomes dangerous.

The two systems also failed differently.

Jev Choice's majority error was in an ambiguous row labeled insufficient_evidence that Jev passed as satisfied.

But Jev also assigned low confidence to the decision. A simple confidence gate would have stopped it from being automated.

Sonnet's failures centered on an empty-repository row labeled insufficient_evidence that it classified as not_satisfied.

That is a less serious outcome operationally, but it exposes another distinction in the policy: "the evidence shows the requirement was not met" and "there is not enough evidence to decide" are not the same state.

Sonnet recognized that something was wrong, but it was highly confident in the wrong category.

This is why I find the confidence result more serious than the 100.0% accuracy result.

The interesting question is not just whether a model can make the decision. It is whether the model gives the surrounding system enough information to know when not to let that decision through.

Keep the policy whole

What happened when I tried to make the system more deterministic?

Jev exposes smaller decision primitives that make decomposition appealing. Alongside the final Choice, I used four Nouls as diagnostic sub-decisions. A Noul evaluates whether a statement is true and returns a probability.

That gives you something very helpful: inspectable intermediate state.

My instinct was to take those four individual judgments and implement the final four-step policy myself in code.

Ask the model the atomic questions.
Get four probabilities.
Write the conditionals.
Remove as much model judgment from the final step as possible.

It sounded safer. It was actually significantly worse.

Jev Choice alone reached 99.3%.

Choice plus the four diagnostic Nouls reached 100.0%.

My hand-coded composite of those same four Nouls fell to 94.1% and produced six false passes.

That is beyond a rounding error, it is the worst failure mode for this gate.

The individual sub-decisions were useful. My reconstruction of the policy from them was not.

I learned something important from that:

Sub-decisions are valuable for diagnosis, auditability, and understanding why a result occurred. But an ordered decision policy is not necessarily equivalent to a bag of independent Boolean answers. The sequence matters. The interaction between conditions matters. The meaning of one piece of evidence can depend on what has already been established elsewhere in the procedure.

In this experiment, asking Jev to apply the written policy as a whole worked better than asking it for individually reasonable facts and assuming I could perfectly reassemble the judgment afterward.

Jev does not replace the rest of this judging workflow.

It accepts text rather than repositories. Its current context constraints make it unsuitable for simply dumping an entire codebase into the model. The judging rubric still includes code-reading scores, broader analysis, and generated prose where a frontier LLM remains the more appropriate tool.

The result is not "Jev replaces Claude." It is that in this very real workflow where there is a consistent bounded decision gate, a general LLM may not be the right tool anymore.

Once I separated those two things in what is needed for a generative LLM model and a System One model, the economics changed by roughly 57x, the latency changed by nearly an order of magnitude, and the confidence signal gave me a credible way to automate almost the entire workload while escalating the uncertain edge cases.

I'm still figuring out where and how to apply this new model into my workflows, but this experiment has given me a good starting point in understanding its strengths and its weaknesses. More importantly, it's opened my eyes up to the potential of AI systems that incorporate more than the current ways of doing things.

The Redirect Is Part of the Threat Model: Hardening MCP Client Connections

Ben Greenberg — Mon, 14 Sep 2026 15:50:20 +0000

I was reading the release notes for the MCP Python SDK while planning this month’s AAIF Ambassador contribution, and one change stopped me: clients on 2.x now follow HTTP redirects only when they remain within the endpoint’s origin.

That’s a good default.

A redirect can move a client from the server it was configured to trust to somewhere else. If your client carries an authenticated session, OAuth state, or tool-discovery requests along for that move, you’ve expanded the set of endpoints that can receive them.

The MCP Python SDK v2.2.0 release, published September 7, makes the boundary explicit. Client("https://..."), streamable_http_client, and sse_client follow redirects only when the scheme, host, and port stay the same. An http to https upgrade on the same host is allowed. A redirect anywhere else fails, and the session remains usable.

Treat the configured origin as an authority boundary

MCP clients connect to endpoints that can expose tools and prompts, then ask users and agents to act on the results. That makes the endpoint URL more than a convenience setting. It identifies where your client can establish a session and where it can send authenticated requests.

Why does a redirect change that? Because HTTP redirects carry authority in a way application code can easily overlook. A client starts with:

https://mcp.example.com/mcp

Then the server responds with a redirect to:

https://other.example.net/mcp

A general-purpose HTTP client may be happy to follow it. An MCP client needs a stricter answer: other.example.net was never the configured server.

The Python SDK now applies this rule to OAuth provider requests too. That closes a gap where the MCP transport might enforce an origin boundary while the authentication flow followed a different redirect policy.

This is a small rule with a direct consequence: if the server you intended to use lives at another origin, configure that URL explicitly. Don’t let a redirect decide it for you.

Redirects are also deployment changes

Same-origin redirects still have valid uses. A server may redirect /mcp to /mcp/, or route traffic through a path that preserves the same scheme, host, and port. The SDK release notes call out the trailing-slash case: clients no longer need an httpx.AsyncClient configured with follow_redirects for MCP requests.

That means maintainers should treat endpoint changes as part of their security review, even when the change looks like routing cleanup.

Ask one question before shipping an endpoint redirect: does the final URL have the same scheme, host, and port as the URL users configure?

If the answer is no, publish the new endpoint and let clients opt into it. A redirect is the wrong migration mechanism when it crosses an origin boundary.

A review checklist for MCP client maintainers

When you change MCP connection handling, check the following:

Endpoint normalization: Confirm that adding or removing a trailing slash stays within the configured origin. Don’t rewrite a user-provided endpoint to a different host or port.
Redirect behavior: Enforce the origin check in every MCP transport you support. The Python SDK’s release names standard client connections, Streamable HTTP, and SSE connections. Your implementation should not leave one transport with a looser policy.
OAuth flows: Apply the same redirect rule to authorization, token, and metadata requests that your MCP client makes. Authentication code often uses a separate HTTP client or redirect setting.
Session state: When a redirect is rejected, keep the existing session state usable where your transport allows it. The Python SDK reports an MCPError for disallowed redirects and keeps the session available. An SSE connection fails with httpx2.HTTPStatusError.
Authenticated tool discovery: Don’t send credentials or session-bound headers to an origin that wasn’t explicitly configured. This includes requests used to discover which tools a server offers.
Error messages: Tell the user the redirect was rejected because it left the endpoint’s origin, and show the target URL only when it is safe to expose. The useful remediation is clear: configure the intended endpoint directly.
Tests: Add cases for a same-origin path redirect, an http to https upgrade on the same host, and a redirect to a different host. Also test OAuth requests separately from transport requests.

The Agentic AI Foundation gives projects such as MCP a neutral home for the protocols and open-source software that let agents work across tools and frameworks. Interoperability depends on clients agreeing on predictable behavior at boundaries like this one.

A configured MCP endpoint should remain the authority boundary.

Where MCP Ends and A2A Begins: Building a Two-Agent Support Workflow Without Tool-Wrapping

Ben Greenberg — Fri, 11 Sep 2026 13:20:22 +0000

When an agent needs help from another service, there is an architectural question to answer first: should that service be exposed as a tool, or should the agent delegate work to another agent?

The distinction matters when the service on the other side is itself autonomous.

A diagnostic agent, for example, may need to request missing context, investigate across several systems, maintain state across multiple exchanges, and eventually return a report. Exposing that agent as a function such as run_diagnostics() can flatten those behaviors into a tool-shaped interface.

MCP and A2A provide a cleaner separation.

MCP standardizes how models and agents interact with tools, APIs, data sources, and other capabilities. A2A standardizes communication between independent agents that need to discover one another, exchange context, delegate work, and manage stateful tasks.

For the support workflow in this tutorial, the boundary is:

MCP is how the support agent directly uses tools and resources available within its operating environment.
A2A is how the support agent delegates work to another agent that owns its own execution process.

That distinction changes the interface you build.

A2A and MCP now also share a governance home. A2A became a Growth Stage project of the Agentic AI Foundation, joining MCP and other open agentic infrastructure projects under the Linux Foundation.

Let’s build the smallest useful version of that boundary.

The support workflow

Consider two agents:

A support agent receives a developer issue: “My deployment completed, but the API returns 401.”
A diagnostic agent knows how to inspect deployment configuration and identity-provider state.

The support agent has MCP tools for operations it performs directly: searching the support knowledge base, reading the ticket, and retrieving deployment metadata from systems it can access.

Those tools do not have to run on the same machine as the support agent. The important distinction is that the support agent invokes them as capabilities and controls how they are composed into its workflow.

The diagnostic agent is different. It owns its own process. It may inspect several systems, request additional context, perform a longer-running investigation, or produce a report after several interactions.

That is where A2A fits.

The handoff looks like this:

The useful boundary is not simply “local versus remote.” It is capability use versus agent delegation.

If an agent needs to invoke a defined capability directly, MCP is usually the appropriate interface. If it needs to delegate a goal to an independently operating agent and let that agent manage its own process, A2A provides the protocol primitives for that interaction.

Start with the Agent Card

Before the support agent delegates anything, it needs to know whether the diagnostic agent can handle the request.

A2A uses an Agent Card for this. It is a JSON metadata document describing an agent’s identity, service interfaces, supported capabilities, security requirements, and skills.

For agents using well-known discovery, the card can be published at:

https://your-agent-domain/.well-known/agent-card.json

The official A2A CLI provides a direct way to inspect it:

a2a card get https://agent.example.com

Replace https://agent.example.com with an A2A agent endpoint you operate or can access.

The agent card is the client’s description of how the remote agent can be used.

For this workflow, the support agent needs answers to a few practical questions:

Does this agent advertise a skill related to deployment diagnostics?
Does it support streaming?
Which security schemes does it declare?
Which A2A interfaces and endpoints does it expose?

The support agent can use that information to determine whether the agent is appropriate before sending ticket or deployment context across the boundary.

This is different from a conventional tool call. With an MCP tool, the client can discover a defined tool schema and invoke that capability. With A2A, the client discovers an agent capable of accepting broader work and interacting through the A2A message and task model.

Keep directly operated capabilities in MCP

Before delegating the investigation, the support agent might use MCP tools such as:

search_knowledge_base("deployment completed API 401")
get_ticket_context(ticket_id)
get_deployment_metadata(deployment_id)

These are capabilities the support agent is operating directly. It chooses the calls, controls their sequence, and consumes the results as part of its own reasoning process.

It might be tempting to expose the diagnostic agent as another tool:

diagnose_deployment(deployment_id, error)

That can work when the interaction really is equivalent to a discrete capability invocation.

The abstraction becomes less useful when the system behind it needs to behave as an agent. It may need information that was not available when the call started. It may need the caller to authorize access. It may perform work long enough to require lifecycle tracking. It may generate one or more artifacts as the investigation proceeds.

Those cases can lead the tool wrapper to accumulate custom state, polling, callbacks, and continuation mechanisms.

A2A already provides protocol concepts for those interactions.

Use MCP to gather the information needed for a useful delegation request. Then send the goal and relevant context to the diagnostic agent through A2A.

Delegate the investigation

Once the Agent Card has been checked and the initial context collected, the support agent can send a message:

a2a send -a https://agent.example.com \
  "Investigate deployment dep_123. The deployment completed, but requests return 401. The affected API is orders."

The official CLI can negotiate among the A2A interfaces advertised by the agent, including JSON-RPC, HTTP+JSON/REST, and gRPC.

That means the client can interact through the A2A abstraction instead of maintaining a different application-level integration for every agent implementation.

There is one important detail here: sending an A2A message does not always create a task.

According to the protocol, the remote agent can return either:

a Message, for an immediate interaction that does not require task tracking, or
a Task, for stateful work that needs lifecycle management.

For a diagnostic investigation that takes time or may require additional input, a Task is the more relevant model.

A task gives the agents a shared unit of stateful work. It has an identifier, a lifecycle, status information, and potentially artifacts representing outputs of the work.

A task can remain active while the diagnostic agent investigates. It can move into a state indicating that more input or authorization is required. It can produce artifacts such as a diagnostic report. The client can later retrieve the task or request cancellation.

That is a different interaction model from invoking a function and waiting for its return value.

Stream updates when the user is waiting

Support workflows become difficult to reason about when a remote investigation starts and the calling application receives no information until completion.

A2A supports streaming for agents that advertise the capability in their Agent Card.

With the CLI:

a2a send -a https://agent.example.com --stream \
  "Investigate deployment dep_123. The deployment completed, but requests return 401."

For task-based interactions, the A2A protocol can stream task status updates and artifact updates while the work progresses.

The support agent can translate those events into useful information for the developer:

The deployment details have been sent to the diagnostic agent.

The deployment is reachable. The diagnostic agent is now checking identity-provider configuration.

The diagnostic report is ready.

Those messages should correspond to real information received from the remote agent. The support agent should not manufacture intermediate progress simply to make the interface appear responsive.

Streaming is only one option for following work.

A2A also defines task operations for retrieving task state, listing tasks, canceling active work, subscribing to task updates, and configuring push notifications. These mechanisms support workflows where the client cannot or should not keep one streaming connection open for the entire investigation.

The A2A CLI exposes task-oriented commands as well, including task inspection and cancellation, which makes the lifecycle visible while developing and debugging an integration.

Let the remote agent ask for context

The initial diagnostic request may not contain enough information to finish the investigation.

That is a normal part of a stateful agent interaction.

Suppose the diagnostic agent determines that it needs the deployment region before it can continue. It can return the task in an input-required state and explain what information is missing.

The support agent can then use an MCP tool it already controls:

get_deployment_metadata("dep_123")

Suppose the result contains:

region = us-east-1

The support agent can send that information back while referencing the existing A2A task rather than beginning an unrelated investigation.

This preserves an important boundary.

The diagnostic agent does not need direct access to the support agent’s deployment metadata tool. The support agent remains responsible for its own systems and decides what context crosses the agent boundary.

That can also reduce unnecessary privilege sharing. Instead of giving the diagnostic agent standing access to another system, the support agent can provide the specific piece of context needed for the current task.

A2A uses task and context identifiers to support these continued interactions. A taskId identifies the stateful unit of work, while a contextId can group related interactions.

The result is a multi-turn collaboration between agents without requiring either side to expose its internal tools, memory, or implementation to the other.

A decision rule you can use

Before adding another integration to an agent, ask:

Does this agent need to invoke a capability, or delegate a goal to another independently operating agent?

If it needs to invoke a capability, expose that capability through MCP.

If it needs to delegate a goal, discover the other agent through its Agent Card, verify that its advertised skills and security requirements fit the request, and communicate through A2A.

For this support workflow, that gives a clear split:

Capability	Protocol	Reason
Read ticket context	MCP	The support agent directly operates the ticket-system integration.
Search troubleshooting documentation	MCP	The support agent directly invokes a retrieval capability.
Investigate a deployment through a diagnostic agent	A2A	The diagnostic agent owns the investigation and its execution process.
Request additional diagnostic context	A2A + MCP	A2A carries the request between agents; the support agent can use MCP to retrieve information from its own systems.
Return a diagnostic report	A2A	The report can be represented as an artifact produced by the delegated work.

The two agents do not need to belong to different companies, frameworks, or repositories for this boundary to be useful.

They can initially live in the same codebase.

The protocol boundary becomes especially valuable when the diagnostic agent later moves to another framework, team, service, or organization. The support agent can continue using MCP for its tools while communicating with the diagnostic system as an agent rather than reducing it to a tool-shaped wrapper.

That is the practical boundary between MCP and A2A: MCP equips an agent with capabilities. A2A gives independently operating agents a standard way to work together.

The official A2A CLI is a useful place to start experimenting with that boundary:

https://github.com/a2aproject/a2a-cli

Wiring a Reachy Mini into OpenClaw without trusting the robot

Ben Greenberg — Tue, 08 Sep 2026 11:25:41 +0000

I put a Reachy Mini in the living room.

It is a small desktop robot from Pollen Robotics, now part of Hugging Face. A head on a moving body, two antennas, a camera, a speaker, and a microphone array. Inside is a Raspberry Pi CM4 running a daemon that exposes the motors, the audio and the camera over an HTTP API on port 8000, plus an app system: you install a Python package onto the robot and the daemon runs it as the current app.

Out of the box it ships with demos. It waves, it dances, it follows a face.

What I wanted was a voice touchpoint for the family, and a way to interact with the family while I am traveling. I already run OpenClaw in the house. I call my instance Jeeves, which is my sarcastic but helpful British butler. It holds my calendar, the home automation devices in every room, a Jewish holiday and Sabbath scheduler, a knowledge base, and the skills that act on all of it. I talk to it through Telegram and a dashboard.

So the robot is a face and a microphone in the room where my family sits, and Jeeves is everything worth saying back. Wiring the two together was my last weekend's project.

The obvious wiring, and why I did not ship it

The obvious version is to put the agent behind the robot. Install an app on the Reachy that captures audio, sends the transcript to the OpenClaw gateway, and speaks the answer. The robot becomes a client of my agent.

I got that working and then took it apart, for two reasons.

The first is that the robot is not a machine I can trust. Its own daemon API has no authentication of any kind. I checked this rather than assumed it: fetch /openapi.json off the robot and you get 100 endpoints and zero security schemes. Anything on the LAN can drive the motors, open the camera, or stop the running app. The security threat is low, but still not tolerable. We maintain separate guest WiFi, but even with that, I didn't like that exposure.

If the agent runs on the robot, then the robot holds a gateway token. The gateway token reaches an agent with my calendar, my house and my shell. Not acceptable to me.

The second reason showed up in the audit trail once it was answering questions in the room. A general question was a full agent turn: a system prompt around 30k tokens carrying tool profiles, the skills index and the workspace bootstrap, on a persistent session that had grown to 51k, with a reasoning model spending about 500 tokens of thought before its first word.

Median 15 seconds to answer "what's the weather today?".

At fifteen seconds nobody in the room waits for the answer. They go find a phone instead, and the robot goes back to being just a cute toy and an ornament on the shelf.

The shape I landed on

One rule drives the whole design: the robot is untrusted, and everything that could leak lives behind all the security I invested in my OpenClaw setup.

Living room                          Mac mini
Reachy Mini (CM4)                    reachy-broker :8092
  reachy-mini-daemon :8000   --->      one scoped bearer token
  jeeves_hub app             Tailscale 
    mic, speaker, motors               redaction at the boundary
    one token, no data                 whisper / OpenClaw gateway

The robot runs one app, jeeves_hub. It does wake-word matching, voice activity detection, motion and expressions, and it holds exactly one bearer token scoped to the broker. It never sees a credential, a model, or a calendar entry. Audio goes up, a policy and a reply come down.

The broker is a small Python HTTP server on the machine. It is the only path between the robot and my data, and it is the only thing that talks to OpenClaw.

If the robot were fully compromised tomorrow, what the attacker gets the highly restricted intent allowlist and nothing else.

Tailscale, not the LAN

The broker binds the tailnet interface and not 0.0.0.0:

The robot is on my tailnet, so the broker addresses it by its tailnet address too, never its LAN address. Nothing else in the house can reach the broker, and the traffic between the two is WireGuard rather than plaintext HTTP across a shared network.

Tailscale also handles the remote case as well. When I "teleport" in from a hotel, that is direct WireGuard, not the vendor's WebRTC path.

The intent allowlist

This is an essential part of the design.

The robot cannot phrase a request. It names an intent and passes typed arguments. Free text only ever reaches one intent, general.ask, which is also the least privileged one: no house access, no calendar, no files.

"""The intent allowlist.

This is the closed set of things a shared-room robot may ask for. An unknown
intent is refused before any data source is touched, so the blast radius of a
fully compromised robot is exactly what is listed here and nothing else.
"""

Routing a transcript to an intent is done with rules, not a model. That was deliberate. An LLM router adds a second model round trip to every turn, and it can be talked into picking a different intent by whatever is said in the room.

AC_MENTION = re.compile(
    r"\b(?:a\.?[/ ]?c\.?|air[ -]?condition(?:er|ing|ers)?"
    r"|air[ -]?cons?|cooling)\b",
    re.I,
)

The doctrine there is one line: an imperative actuates, a question never does, and a command that names no known room asks which one. "Is the ac on" is a read. "Turn on the ac" is a write. Anything ambiguous falls to the read.

Redaction happens on the broker side of the boundary, before a word is spoken. My calendar status is coarse: busy or free, until when, and a whereabouts word from a closed vocabulary. Never event titles, locations, attendees or company names.

The lean OpenClaw agent

This is how I dropped the response time on Reachy from 15 seconds to about 3 seconds.

Instead of routing general questions at main, I gave the robot its own agent in config/openclaw.json:

{
  "name": "Reachy family hub",
  "description": "Lean voice agent for the living-room robot: no skills, no tools, no workspace context. The persona rides in each message.",
  "workspace": "/Users/you/.openclaw/workspace-reachy",
  "model": {
    "primary": "FILL_IN_YOUR_LLM_MODEL_HERE",
    "fallbacks": [
      "FALLBACK_MODEL_1",
      "FALLBACK_MODEL_2"
    ]
  },
  "skills": [],
  "tools": { "profile": "minimal" },
  "heartbeat": { "every": "0m" },
  "contextInjection": "never",
  "thinkingDefault": "off",
  "reasoningDefault": "off",
  "memory": { "search": { "enabled": false } }
}

Every line there is removing something. No skills means no skills index in the prompt. The minimal tool profile means no coding tools. contextInjection: never means the workspace is not injected, so the persona files on disk are documentation for me rather than tokens I buy on every question. Thinking and reasoning off, because a living room answer is not a research task.

The same question that measured 15 seconds now measures about 2.9 seconds for the model leg and 3.4 to 3.9 seconds for the whole turn including speech synthesis, at roughly 5k prompt tokens instead of 30k. About a tenth of the cost.

The persona is composed per turn by the broker and rides in the message, so every request is stateless. No user field, no session header. A persistent session would re-buy the persona on every question anyway.

The broker POSTs to the gateway's OpenAI-compatible endpoint and addresses the agent by name:

body = json.dumps({
    "model": "openclaw/reachy",          # the agent, not a model id
    "messages": messages,
    "max_completion_tokens": 200,
}).encode()

req = urllib.request.Request(
    f"{GATEWAY_URL}/v1/chat/completions",
    data=body,
    headers={"Content-Type": "application/json",
             "Authorization": f"Bearer {token}"},
    method="POST",
)

There is a second agent, openclaw/reachy-deep, with the same lean shape and a stronger model, reached only when somebody says "think carefully". Everything else stays on the fast path.

Keeping the model out of the house

The lean agent handles general knowledge. It does not touch the house, and that is the other half of the speed story.

Before the deterministic router existed, "turn off the kitchen light" reached the model, which rediscovered the automation skill with its shell tool on every single request. 43 seconds when it worked, and a timeout when it did not.

Now every device is a closed table and a deterministic intent, and a light takes one to two seconds. Same for the time, for greetings, for "what can you help with", which is spoken from a command guide generated out of the router itself so it can never advertise a phrase the robot does not understand.

Zero tokens for any of it.

Running it under launchd

Both the broker and the speech service are launchd agents on the Mac.

#!/bin/bash
...

cd "$HOME/path/to/reachy-broker"
exec /opt/homebrew/bin/python3 -m api.server

That's all it takes it boot it up.

What it feels like now

You say "hey Jeeves" and then a sentence. The hub matches the wake phrase locally, streams the audio to the broker, whisper transcribes it, the router picks an intent, and either a deterministic handler or the lean agent answers.

House questions and house commands never leave the Mac. General questions go to the LLM through the gateway and never carry a fact about my family. The robot holds one token that can do exactly the things on a list I wrote.

The part I did not expect to care about is that setting thatg boundary made the fun parts possible. Once the robot could only ever name an intent, I stopped worrying about what it might be talked into doing and started adding things: games, ambient motion randomly making the kids laugh. None of that needed a new trust decision, because there is only one, and it is enforced in a single file.

If you are wiring a device you cannot trust into an agent that can act on your life, put a broker between them and give the device a closed list of things it may ask for. Then, once you take care of that bit, you can just get down to building it for both productivity and joy.

Vector Search Is Still the Memory Layer Agents Actually Need

Ben Greenberg — Thu, 27 Aug 2026 07:37:45 +0000

When I was working on Vector Search with JavaScript, vector search was a hot topic. By the time the book was published some people had begun saying that because of LLMs and their advances, we have moved beyond vector search.

This couldn't be farther from the truth. LLMs and agentic development is amazing, but it often gets things wrong. They don't fail because the model is weak always, but they fail because the right context can be sitting somewhere else and they had no idea that it existed.

Your docs are in one place. Tool outputs are in another. Prior decisions are in chat history, issue comments, AGENTS.md, local files, and half a dozen API responses. You can paste more into the prompt, but that gets expensive and messy fast.

Vector search gives agents a memory layer they can inspect, query, move, and rebuild.

That still matters in an LLM-first world.

The Agentic AI Foundation is a good place to frame this because AAIF is about open agentic infrastructure: MCP, goose, AGENTS.md, agentgateway, and the protocols around them. If agents are going to work across tools and runtimes, memory can’t live as a hidden feature inside one hosted product. It needs to be part of the system you can reason about.

The prompt is the wrong database

A prompt is a request. It’s not a storage layer.

Once you treat the prompt as storage, every workflow starts to rot. You add summaries. Then summaries of summaries. Then a “context” block, and then a "context" block for the original context block.

That doesn’t scale for project-specific agents.

You need retrieval that can answer questions like:

Which migration introduced this column?

What did the tool return the last time this failed?

Which internal doc explains this service boundary?

What did we decide about auth in the previous session?

Why does that happen? Because agents need working memory and reference memory at the same time. The model can reason over the current task, but your project context lives outside the model. Vector search gives you a way to fetch the few pieces that match the current intent instead of dragging the whole project into every turn.

MCP makes retrieval a first-class interface

MCP gives AI applications a standard way to connect to external systems. MCP servers can expose tools and resources, and resources are identified by URIs in the spec.

That maps cleanly to vector search.

You can build an MCP server with tools like:

search_project_context(query, filters)

fetch_context_chunk(uri)

upsert_tool_result(source, content, metadata)

list_context_sources(project_id)

The vector database doesn’t need to know about the agent. The agent doesn’t need to know about the vector database. MCP becomes the contract between them.

That contract matters when you want portability. Today your agent might run in an IDE. Tomorrow it might run in a local runtime like goose. The retrieval layer should move with you.

What should go into agent memory?

Start with the things you already look up manually.

Index your docs, READMEs, runbooks, schema notes, generated API references, issue threads, and selected tool outputs. Store the raw text or clean markdown. Keep metadata with every chunk: source URI, file path, repo, commit SHA when you have it, timestamp, author if useful, and content type.

Then be strict about retrieval.

Don’t return anonymous chunks. Return chunks with source links.

Don’t rely on similarity alone. Use metadata filters.

Don’t treat old context and new context equally. Add recency where the domain changes.

Don’t make the agent trust memory blindly. Give it enough source data to quote the file, open the URI, or ask for confirmation before making a risky change.

Vector search is useful because it’s probabilistic. Agent memory is useful when that probability is wrapped in provenance.

A small useful pattern

A practical agent memory loop can stay straightforward.

First, chunk source material by meaning, not by arbitrary token count. Function-level chunks work better than splitting every thousand characters in code-heavy repos. Section-level chunks work better for docs.

Then embed each chunk and store it with metadata.

At runtime, the agent turns the current task into a retrieval query. The MCP server searches the vector index, filters by project or source type, and returns a small set of candidates with scores and URIs. The agent fetches the best chunks, reads them, and decides what to do next.

That’s enough for many workflows.

You can add hybrid search when exact identifiers matter. You can add reranking when your top results are noisy. You can add write-back when tool results become useful future context. But the base shape stays the same: retrieve, inspect, act.

Vector search also makes memory debuggable

When an agent gives a bad answer, you need to know whether the reasoning failed or retrieval failed.

Those are different problems.

If retrieval returned the wrong chunks, fix chunking, filters, metadata, or ranking. If retrieval returned the right chunks and the model ignored them, fix the prompt or tool policy. If the index is stale, fix ingestion.

Without an inspectable retrieval layer, all of that collapses into “the agent was wrong.”

You can log the query, returned chunk IDs, scores, metadata filters, and final sources used. You can replay the retrieval step without running the full agent. You can delete bad documents from the index. You can rebuild from source.

That is what I would call operational memory.

Vector search didn’t become obsolete because models got better. It became more useful because agents now have more places to look.

What a good Agents.md should teach an agent on day one

Ben Greenberg — Mon, 03 Aug 2026 15:38:29 +0000

I hit this last week while working inside my own OpenClaw workspace: the agent had access to the right files, the right tools, and the right project context, but the useful behavior didn't come from any one magic prompt. It came from a small stack of durable instructions.

The root AGENTS.md said what to read first. SOUL.md defined the assistant's operating posture. USER.md gave personal context. TOOLS.md separated reusable tool behavior from local machine details. Skill docs explained when to load specialized workflows.

That structure has proven useful for me time and time again.

AGENTS.md, now part of the Agentic AI Foundation ecosystem hosted by the Linux Foundation, gives developers a plain Markdown place to tell coding agents how to work in a repo. The format is intentionally simple. The hard part isn't the file. The hard part is deciding what deserves to live in it.

Start with the first five minutes

A good AGENTS.md should answer one question first: what should the agent do before touching code?

In my workspace, the startup path is explicit:

Read SOUL.md
Read USER.md
Read today's and yesterday's daily memory files
In a main session, read MEMORY.md

That gives the agent a boot order. It doesn't need to guess which file matters, whether memory is allowed, or whether private context belongs in a shared chat.

Most repo instructions skip this. They say "follow project conventions" and then bury the conventions across a README, package scripts, CI config, old PRs, and comments. An agent can search, but search isn't the same as orientation.

Give it a first route through the repo.

Separate identity from operating rules

Your repo probably doesn't need a SOUL.md, but the pattern is useful. One file can define working posture, while AGENTS.md defines project behavior.

For a software repo, that might look like this:

## Working posture

- Read the existing code before proposing new abstractions.
- Prefer local helpers over new dependencies.
- Keep changes scoped to the user request.
- Run the narrowest useful test first, then broaden if the change touches shared behavior.

Those are judgment rules. They belong near the top because they shape every later decision.

Then put repo-specific mechanics somewhere else:

## Commands

- Install dependencies: `pnpm install`
- Run unit tests: `pnpm test`
- Run type checks: `pnpm typecheck`

Why split them? Because commands change faster than principles. If you mix everything together, the file turns into a junk drawer. Agents will still read it, but you won't know which instruction is steering behavior.

Put boundaries where the agent will trip over them

The best line in my workspace AGENTS.md is short: trash > rm.

That teaches a local safety rule in three tokens. It says destructive deletion should be recoverable. It doesn't explain Unix philosophy. It doesn't lecture. It gives the agent a rule it can apply while acting.

Your AGENTS.md should include boundaries like that:

## Red lines

- Don't edit generated files directly.
- Don't change public API behavior without updating tests.
- Don't run migrations against shared databases.
- Use `trash` instead of `rm` when deleting local files.

Notice the shape: concrete verbs, concrete objects, concrete limits.

"Be careful with data" is too vague. "Don't run migrations against shared databases" gives the agent something it can obey.

Teach context access rules

Agents often fail by reading too little or too much. Repo instructions can fix both.

In my workspace, MEMORY.md is only loaded in main sessions, not shared contexts. That's a privacy rule and a context rule at the same time. Daily notes are raw logs. Long-term memory is curated. TOOLS.md is for environment-specific notes, while skills are reusable.

That structure avoids a common problem: durable instructions become a dumping ground for every fact anyone might need someday.

For a team repo, you can use the same split:

## Context files

- `README.md`: human setup and project overview.
- `AGENTS.md`: agent workflow and repo norms.
- `docs/architecture.md`: current service boundaries.
- `docs/runbooks/`: production procedures. Read only when the task touches operations.
- `.env.example`: allowed environment variable names. Never read real `.env` files unless asked.

That last sentence matters. It tells the agent where the map ends.

Keep local details out of shared skills

TOOLS.md in my workspace makes a clean distinction: skills define how tools work, and TOOLS.md stores local specifics like camera names, SSH aliases, speakers, or preferred voices.

That maps well to engineering teams.

A reusable instruction might say:

When debugging CI, inspect the failing job logs before changing code.

A local instruction might say:

The staging dashboard is at <internal URL>.

Those shouldn't live in the same place. Reusable instructions can move across projects. Local details shouldn't leak, and they age faster.

This is one reason AGENTS.md fits naturally inside the AAIF project set. MCP describes how agents connect to tools. agentgateway works on routing and governing agent traffic. AGENTS.md handles repo-level behavior. You need all of those layers if agents are going to work across projects without each tool inventing its own private convention.

Use skills for depth, not bulk

My workspace says: "Skills provide your tools. When you need one, check its SKILL.md."

That's the right division of labor. AGENTS.md should route the agent to deeper instructions. It shouldn't contain the full manual for every workflow.

Bad:

## Release process

[900 lines of release rules, changelog policy, package registry notes, rollback steps, comms templates, and edge cases]

Better:

## Release process

For release work, read `skills/release/SKILL.md` before making changes. Do not publish packages or create GitHub releases unless the user explicitly asks.

Why does this work? The root file stays readable, and the agent loads detail only when the task needs it.

That matters more as context grows. An instruction file can hurt you if it forces every task to carry every workflow. A CSS fix doesn't need your incident response manual.

Tell the agent when to speak and when to stay quiet

This is an important part as well that shouldn't be ignored.

The workspace AGENTS.md has group chat rules. It tells the assistant to respond when directly mentioned, when it can add value, or when correcting meaningful misinformation. It also tells the assistant to stay quiet when the conversation is casual or already answered.

That's repo-relevant too. Agents need communication norms.

For a development repo, that might be:

## PR comments

- Comment when a change affects behavior users can observe.
- Mention test gaps plainly.
- Don't restate the diff.
- Don't leave speculative security claims without a concrete path or file reference.

Agents generate a lot of text by default. Your instructions should define what useful text looks like in your project.

Make maintenance part of the contract

The workspace instructions have a blunt rule: no "mental notes." If something should persist, write it to a file.

That belongs in more repos.

Agents learn project facts during a task: a flaky test command, a generated directory that shouldn't be edited, a local setup wrinkle, a service boundary that wasn't documented. If the agent only uses that knowledge once, the next run pays the same discovery cost.

Add a maintenance rule:

## Updating these instructions

When you learn a durable repo rule, update `AGENTS.md` or the relevant doc in the same PR. Keep task-specific notes out of this file.

Then enforce the second sentence. Otherwise AGENTS.md becomes a chat transcript with headings.

A practical structure

If I were starting a repo-level AGENTS.md today, I'd use this shape:

# AGENTS.md

## Start here

- Read this file before making changes.
- Read `README.md` for setup.
- Read the nearest package-level `AGENTS.md` if one exists.

## Working posture

- Preserve existing patterns unless the task calls for changing them.
- Keep edits scoped.
- Prefer small tests close to the changed code.

## Commands

- Install:
- Test:
- Typecheck:
- Lint:

## Repo map

- `apps/web`: frontend
- `packages/api`: API client
- `packages/db`: schema and migrations

## Boundaries

- Don't edit generated files.
- Don't run destructive database commands.
- Ask before publishing, emailing, posting, or deploying.

## Workflow routing

- For releases, read `docs/release.md`.
- For security changes, read `docs/security.md`.
- For UI changes, inspect existing components first.

## Maintenance

- Add durable lessons here.
- Remove stale instructions when the code changes.

That's enough for day one. It creates the framework to build upon as you continue to iterate.

The goal isn't to make the agent know everything. The goal is to make the first move reasonabe, the dangerous moves constrained, and the next file obvious.

In an open agentic ecosystem, the shared convention doesn't need to be heavy to be useful. It needs to be predictable enough that any agent can arrive in your repo and know where to begin: AGENTS.md.

From First-Run Drop-Off to First Useful Agent Run

Ben Greenberg — Thu, 16 Jul 2026 22:16:16 +0000

I keep coming back to the same onboarding question: what happens in the first 10 minutes?

For agent tools, that window is brutal. A developer opens a repo, starts the agent, asks for a change, and waits to see if the tool understands the project. If the agent guesses the package manager, misses the test path, edits generated files, or asks the developer to explain the repo from scratch, trust drops fast.

That isn't an agent model problem every time. A lot of it is repo readiness.

The Agentic AI Foundation, hosted by the Linux Foundation, is building an open home for projects like MCP, goose, AGENTS.md, and agentgateway. That work can sound big and infrastructural, but one of the most useful entry points is small: make your repo easier for an agent to understand on the first run.

AGENTS.md is the repo-side context. goose is a practical runtime path. Together, they give you a way to move from "the agent is poking around" to "the agent made a useful first pass."

Start With The First Useful Run

Don't begin by asking, "What should our agent docs say?"

Ask this instead: what should a developer be able to ask an agent to do in this repo within 10 minutes?

Pick one task. Not the whole system. One useful first run.

For example:

Find the right entry point for a small bug
Add a focused test around an existing function
Update a docs page with a known source file nearby
Explain how a specific package or module is wired

That first run gives your AGENTS.md a job. It isn't a policy dump. It's the context an agent needs to avoid wasting the developer's first session.

Put Repo Truth Where Agents Can Find It

AGENTS.md is a simple open format for guiding coding agents, and the project site says it's already used by over 60k open-source projects: https://agents.md.

The reason it works is plain: agents need a predictable place for repo instructions. README files are written for humans. CI files are written for automation. AGENTS.md gives agents the details that usually live in maintainer heads.

Your first version should answer:

What kind of project is this?
Where does source code live?
Where do tests live?
Which files should agents avoid editing?
What style or architecture choices should agents preserve?
What should the agent do before claiming a task is done?

Keep it short enough that someone would maintain it. Stale agent instructions are worse than missing ones because they create confident mistakes.

Write Instructions Like Maintainer Notes

An AGENTS.md file doesn't need brand language. It needs maintainer notes.

Say things like:

# AGENTS.md

## Project Shape

This repo contains a web app and supporting packages. App code lives in `apps/web`. Shared code lives in `packages`.

## Working Rules

Prefer small changes that match nearby patterns. Do not rewrite public APIs unless the task asks for it.

## Tests

When changing behavior, add or update the closest existing test. If you can't run the test locally, say what you inspected and why the test wasn't run.

## Files To Avoid

Do not edit generated files, lockfiles, or vendored code unless the task is specifically about dependency updates.

Notice what's missing: fake certainty.

Don't say "run the full test suite" unless that's realistic. Don't list commands you haven't checked. Don't tell the agent to use a package manager you don't use. Your agent instructions should be as true as your README.

Design The Goose Path

goose is an open-source AI agent runtime under AAIF. Its project page describes it as an agent that can install, execute, edit, and test with any LLM: https://aaif.io/projects/goose.

For onboarding, think of goose as the first-run path you can test against your repo instructions.

A good first-run path has three pieces:

A clear starting task
A repo-level AGENTS.md
A visible stopping point

The stopping point matters. If the agent changes code, how does the developer know whether it did the right thing? Maybe the agent should point to the files it changed. Maybe it should explain the test it would run. Maybe it should stop before touching a migration, generated file, or public API.

That belongs in AGENTS.md.

Make The Agent Ask Better Questions

A useful agent doesn't need to know everything. It needs to know when to stop guessing.

Add guidance for uncertainty:

## When Unsure

If the requested change touches auth, billing, data deletion, or production configuration, ask before editing.

If there are multiple plausible implementations, describe the tradeoff and choose the smallest local change unless the user tells you otherwise.

Why does that help? Because first-run drop-off often comes from surprise. The agent edits the wrong layer, takes a broad refactor path, or treats a risky area like ordinary code.

Good instructions narrow the blast radius.

Treat Docs As Product Surface

Developer onboarding isn't separate from product. The docs shape what users try, where they get stuck, and whether they come back.

For agent-ready repos, AGENTS.md is part of that product surface. So review it the same way you'd review a quickstart:

Is the first task obvious?
Are repo boundaries named?
Are setup assumptions current?
Are risky areas called out?
Can a new contributor tell what "done" means?

This is where AAIF's open ecosystem angle becomes practical. If agent tools are going to work across projects, maintainers need shared conventions that don't depend on one vendor, one editor, or one model. AGENTS.md gives repos a portable instruction layer. goose gives developers an open way to run agent workflows against it.

Small file. Real leverage.

A Practical Checklist

Use this before you point an agent at your repo:

Pick one first-run task a new developer would value.
Add or update AGENTS.md with project shape, test expectations, and files to avoid.
Remove commands you haven't verified.
Tell the agent how to behave around risky code paths.
Run the first task through goose or your agent runtime of choice.
Edit AGENTS.md based on where the agent guessed wrong.
Repeat until the first run produces something you would review seriously.

The goal isn't to make the agent perfect. The goal is to make the first session legible.

A developer should be able to open the repo, start the agent, ask for one scoped task, and understand the result without becoming the repo tour guide.

I built my first Robinhood Chain app as an index basket

Ben Greenberg — Sun, 12 Jul 2026 15:51:24 +0000

I built a small index basket app on Robinhood Chain because I wanted to understand the developer path from the first contract deploy all the way to a working frontend.

The app is intentionally plain: a user deposits Stock Tokens, which are blockchain tokens that represent real equity exposure, and receives an ERC-20 basket share. ERC-20 is Ethereum's standard token interface, so a compatible token exposes familiar methods like balanceOf, transfer, and approve. The basket share is priced from live price feeds, and the user can redeem it back into the underlying Stock Tokens.

That's the part that made this interesting to me. The chain is custom, but the app path is not. I still wrote Solidity, deployed with Foundry, read contract state with viem, and wrote transactions from React with wagmi.

If you've built normal web apps, think of the chain's RPC endpoint as the API base URL. A wallet is login plus a signing key. A smart contract is backend code you deploy to the chain, except you should treat it like immutable infrastructure because you don't get to hot-patch it casually later.

The demo and source are here:

The custom chain still feels like the EVM

Robinhood Chain is a custom Arbitrum Chain, which means it runs as a dedicated chain on the stack of Arbitrum, an Ethereum scaling system. It is also EVM-compatible. EVM means Ethereum Virtual Machine, the runtime that executes Solidity contracts, so the tooling surface looks like the Ethereum developer flow many tutorials already teach.

An L2, or rollup, is a chain that executes transactions separately and then posts compressed proof or transaction data back to Ethereum. Robinhood Chain uses Ethereum blobs for data availability, which is a cheaper Ethereum data lane for rollups to publish the data needed to reconstruct chain state. Gas, the metered compute fee you pay to run transactions, is paid in ETH.

The first deploy looks like this:

export PRIVATE_KEY=0x<your_private_key>
export RH_RPC_URL=https://rpc.testnet.chain.robinhood.com

forge create src/MyContract.sol:MyContract \
  --rpc-url $RH_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast

Foundry is the contract build, test, and deploy CLI. forge create compiles the contract, sends the deployment transaction, and broadcasts it to the RPC endpoint.

This is the part I appreciate as a developer. Robinhood gets its own chain configuration, infrastructure, pricing, and product controls. I still get the contract model I know how to reason about.

Stock Tokens are ERC-20s with display accounting

Stock Tokens are ERC-20s that represent real market assets. That means contracts can read balances, request approvals, and transfer them using the same functions they would use for any other ERC-20.

IERC20 nvda = IERC20(NVDA_TOKEN_ADDRESS);

uint256 balance = nvda.balanceOf(user);
nvda.approve(spender, amount);
nvda.transfer(recipient, amount);

The wrinkle is corporate actions. Stocks split. Dividends happen. The economic relationship between one token and one underlying share can change.

Stock Tokens implement ERC-8056, the Scaled UI Amount extension. Raw token balances stay stable for contracts. A UI multiplier is how wallets and apps display the share-equivalent amount.

interface IScaledUIAmount {
    function uiMultiplier() external view returns (uint256);
    function balanceOfUI(address account) external view returns (uint256);
    function totalSupplyUI() external view returns (uint256);
    function newUIMultiplier() external view returns (uint256);
    function effectiveAt() external view returns (uint256);
}

The display conversion is:

underlyingShares = rawBalance * uiMultiplier / 1e18;

Why not just mutate balances after a split?

Because contracts depend on stable accounting. If my basket contract holds a raw token balance, I don't want a display-level corporate action to unexpectedly rewrite the reserve math inside the contract. The UI can show share-equivalent amounts, and the protocol can keep using raw ERC-20 units.

The basket contract does only a few things

The sample app has two contracts and no owner.

Contract	Role	Control surface
`BasketFactory`	Deploys and records baskets	Permissionless
`BasketToken`	Holds components, mints, redeems, prices shares	No owner or upgrade path

The factory does not custody user funds. It deploys a basket and records the address.

function createBasket(
    string calldata name,
    string calldata symbol,
    BasketToken.Component[] calldata components,
    uint256 maxPriceAge
) external returns (address basket) {
    basket = address(new BasketToken(name, symbol, components, maxPriceAge));
    _baskets.push(basket);
    isBasket[basket] = true;
    emit BasketCreated(basket, msg.sender, name, symbol);
}

Each basket stores a fixed list of components. A component is a token, a price feed, and the amount of that token backing one basket share.

struct Component {
    address token;
    address feed;
    uint256 unitsPerShare;
}

A price feed is an external data source a contract or app can read. In this app, the feeds come from Chainlink, an oracle network that publishes market data onchain. An oracle is the bridge between offchain facts, like a stock price, and onchain code.

On mainnet, the production chain where real assets move, the demo basket uses TSLA, NVDA, and AAPL Stock Tokens with their Chainlink feeds:

function _mainnetComponents()
    internal
    pure
    returns (BasketToken.Component[] memory c)
{
    c = new BasketToken.Component[](3);
    c[0] = BasketToken.Component(MAINNET_TSLA, MAINNET_TSLA_FEED, 0.4e18);
    c[1] = BasketToken.Component(MAINNET_NVDA, MAINNET_NVDA_FEED, 0.3e18);
    c[2] = BasketToken.Component(MAINNET_AAPL, MAINNET_AAPL_FEED, 0.3e18);
}

One TRIO share is backed by 0.4 TSLA, 0.3 NVDA, and 0.3 AAPL.

On testnet, which is a staging chain with no real funds at risk, the demo uses faucet Stock Tokens for TSLA, AMZN, and NFLX with mock feeds. A faucet is a service that gives you test tokens so you can build without spending real money.

Minting follows the ERC-20 approval pattern

From the frontend, minting is two steps: approve each component token, then call the basket.

await writeContract({
  address: stockTokenAddress,
  abi: erc20Abi,
  functionName: "approve",
  args: [basketAddress, amount],
});

await writeContract({
  address: basketAddress,
  abi: basketTokenAbi,
  functionName: "mint",
  args: [shares, account],
});

That writeContract call is from wagmi, a React library for wallet connections and contract writes. viem is the TypeScript Ethereum client underneath it for typed reads, writes, and transaction handling.

Onchain, the basket pulls the required component amounts and mints shares in the same transaction.

function mint(uint256 shares, address to) external nonReentrant {
    if (shares == 0) revert ZeroShares();

    uint256 count = _components.length;
    for (uint256 i = 0; i < count; i++) {
        Component memory c = _components[i];
        uint256 amount = Math.mulDiv(
            c.unitsPerShare,
            shares,
            SHARE_UNIT,
            Math.Rounding.Ceil
        );

        IERC20(c.token).safeTransferFrom(msg.sender, address(this), amount);
    }

    _mint(to, shares);
    emit Minted(msg.sender, to, shares);
}

The rounding direction matters. Mint rounds up so a user cannot underpay the basket reserves by tiny decimal leftovers.

Redeem is the mirror image. Burn first, transfer components out, and round down so the reserves cannot be overdrawn.

function redeem(uint256 shares, address to) external nonReentrant {
    if (shares == 0) revert ZeroShares();
    if (to == address(0)) revert ZeroAddress();

    _burn(msg.sender, shares);

    uint256 count = _components.length;
    for (uint256 i = 0; i < count; i++) {
        Component memory c = _components[i];
        uint256 amount = Math.mulDiv(
            c.unitsPerShare,
            shares,
            SHARE_UNIT,
            Math.Rounding.Floor
        );

        IERC20(c.token).safeTransfer(to, amount);
    }

    emit Redeemed(msg.sender, to, shares);
}

Redeem skips the price feed and the factory. It burns shares and returns the component tokens the contract already holds.

I keep pricing and redemption apart on purpose. You use the price for the UI. Redeem returns the collateral.

Local to mainnet is the path I want rehearsed

The repo gives you the whole loop.

git clone --recurse-submodules https://github.com/hummusonrails/robinhood-chain-dapp-example.git
cd robinhood-chain-dapp-example

pnpm install
anvil
pnpm run deploy:local
pnpm run smoke
pnpm run dev

anvil is Foundry's local development chain. Think of it as a throwaway local server for contracts. The local deploy creates mock Stock Tokens, mock Chainlink feeds, the factory, and a demo Tech Trio basket. It also writes apps/frontend/.env.local, so the frontend knows which addresses to call.

For Robinhood Chain testnet:

PRIVATE_KEY=$YOUR_TESTNET_KEY pnpm run deploy:testnet

One Foundry script handles local, testnet, and mainnet by checking the chainid, which is the chain's network identifier.

function run() external {
    vm.startBroadcast();

    BasketFactory factory = new BasketFactory();
    console2.log("FACTORY=%s", address(factory));

    BasketToken.Component[] memory components;
    if (block.chainid == 4663) {
        components = _mainnetComponents();
    } else if (block.chainid == 46630) {
        components = _testnetComponents();
    } else {
        components = _localComponents();
    }

    address basket =
        factory.createBasket("Tech Trio", "TRIO", components, MAX_PRICE_AGE);

    console2.log("DEMO_BASKET=%s", basket);
    console2.log("CHAIN_ID=%s", block.chainid);

    vm.stopBroadcast();
}

The testnet deployment behind the live walkthrough is:

Contract	Address
`BasketFactory`	`0xC1940D5fd58ce735A44a53f910852B12250F6a14`
`BasketToken` (`TRIO`)	`0x7633e0920Ea46A8Ec54F61C95adECD391c01Edd4`

Before spending mainnet gas, I want fork tests. A fork test runs tests against a local copy of live chain state, so you can check integration assumptions without sending real transactions.

pnpm run test:contracts
pnpm run test:fork

Here is the shape of the fork test:

function test_mintAndRedeem_withRealStockTokens() public {
    deal(TSLA, alice, 1e18);
    deal(NVDA, alice, 1e18);
    deal(AAPL, alice, 1e18);

    vm.startPrank(alice);
    IERC20Metadata(TSLA).approve(address(basket), type(uint256).max);
    IERC20Metadata(NVDA).approve(address(basket), type(uint256).max);
    IERC20Metadata(AAPL).approve(address(basket), type(uint256).max);

    basket.mint(2e18, alice);
    assertEq(basket.balanceOf(alice), 2e18);
    assertEq(IERC20Metadata(TSLA).balanceOf(address(basket)), 0.8e18);

    basket.redeem(2e18, alice);
    assertEq(basket.totalSupply(), 0);
    assertEq(IERC20Metadata(TSLA).balanceOf(alice), 1e18);
    vm.stopPrank();
}

That is the development loop I want for this kind of app: mocks for speed, testnet for wallet flow, fork tests for live integration assumptions, and mainnet only after the path is rehearsed.

A block explorer, which is basically hosted request logs for a chain, then gives you a way to inspect deployed contracts and transactions. The testnet contracts are verified on Blockscout, so you can read the source and calls after deployment.

Stock Tokens change the app assumptions

Stock Tokens still fit the ERC-20 interface, but the surrounding assumptions are different from a generic token.

For user balances, don't blindly show balanceOf. Use balanceOfUI or apply uiMultiplier so the user sees the share-equivalent amount.

For prices, read the per-token Chainlink feed on mainnet. For corporate actions, track multiplier updates and pending effective times. For valuation, remember that the feed price already includes the multiplier.

Stock market hours matter too. Crypto feeds may update around the clock. Stock feeds follow market sessions, so stale data checks need to reflect that.

The exit path is the one I care about most. If a user wants to redeem their basket share, I don't want that flow blocked because an oracle read is stale. The contract already holds the component tokens. Redemption should return the collateral.

Learn the chain later; start with the app

Robinhood Chain runs on Arbitrum Nitro, the same underlying technology as Arbitrum One, deployed as a dedicated chain. Arbitrum One is the public shared L2. A custom Arbitrum Chain gives a team its own execution environment while keeping the Ethereum-style contract model.

The mechanics under the hood are also why the fees are small. Transactions hit a sequencer, which is the service that orders transactions for the rollup, land in fast blocks, get batched, and settle back to Ethereum using blob data. The fee combines L2 execution gas with the data cost on L1, which is Ethereum itself.

That's useful context, but I wouldn't start by trying to absorb the whole chain architecture.

Start with the working system. Read a Stock Token balance. Approve a token. Mint a share. Redeem it. Check the price feed. Run the fork test. Look at the transaction in a block explorer.

Plenty of apps can live on Robinhood Chain. This basket is a good first build because it touches the surfaces most apps using market assets will need: token reads, approvals, ERC-8056 display logic, Chainlink feeds, local mocks, testnet deployment, verified contracts, fork tests, and a Next.js frontend using wagmi and viem.

What I learned from building it is where the real work sits: deciding where accounting belongs, where pricing belongs, and which assumptions deserve a test before real users and real assets touch the contract. The app stack itself is familiar.

The MCP Release Candidate Survival Guide: Apps, Auth, Deprecations, and Tool Schemas

Ben Greenberg — Thu, 02 Jul 2026 10:27:58 +0000

The MCP 2026-07-28 release candidate is the largest major specification revision since MCP launched. It is also a compatibility test for everyone building clients, servers, SDKs, gateways, and developer tools around the protocol.

The release candidate was locked on May 21, 2026. The final specification is scheduled for July 28, 2026. This window is the time to test real implementations and find migration pain points.

1. Check your transport assumptions

The biggest change is that MCP is now stateless at the protocol layer.

If your current Streamable HTTP implementation depends on initialize, initialized, or Mcp-Session-Id, you have migration work. In the release candidate, each request carries the protocol version, client info, and capabilities in _meta. The new server/discover method covers cases where a client needs server capabilities up front.

A tools/call request over Streamable HTTP now includes headers such as:

MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search

That changes how infrastructure can handle MCP traffic. A gateway no longer needs to inspect JSON bodies just to route or rate-limit common operations. A load balancer can send requests to any server instance because the protocol no longer assumes a sticky session.

The compatibility question is simple: does your server still hide required state in the connection?

If yes, move that state into an explicit application handle. For example, a tool can return a basket_id, browser_id, or job handle, and the model can pass it back as a normal tool argument later. That makes state visible to the model and portable across server instances.

2. Test server-to-client request flows

Stateless MCP still needs interaction during a call. The release candidate changes how that works.

Server-initiated requests can only happen while the server is processing a client request. For elicitation, roots, or sampling flows, the server returns an InputRequiredResult, and the client retries the original call with inputResponses and requestState.

That means clients need to preserve and replay the right data. Servers need to treat the retry as a continuation, even if it lands on another instance.

A good test case is a destructive tool call that asks for confirmation. The server should return an input request, the client should collect the answer, and the retry should succeed without relying on connection memory.

3. Treat MCP Apps as real app surfaces

MCP Apps let servers provide interactive HTML interfaces that hosts render in sandboxed iframes.

This is a big developer-experience change, but it also has security and product implications. Tools can declare UI templates ahead of time, which lets hosts prefetch, cache, and review them before anything runs. The UI still talks back through MCP’s JSON-RPC protocol, so UI-driven actions go through the same consent path as tool calls.

If you maintain a host, test your iframe isolation, permission prompts, and caching behavior. If you maintain a server, check that your UI template declarations are deterministic and do not depend on hidden session state.

The Apps model will reward consistent discipline: explicit templates, clear tool boundaries, and no surprise network behavior.

4. Harden authorization now

The release candidate tightens MCP authorization around OAuth 2.0 and OpenID Connect deployments.

Clients now need to validate the iss parameter on authorization responses under RFC 9207. Authorization servers should begin sending iss now because future clients are expected to reject responses without it.

Dynamic Client Registration also changes. Clients declare OpenID Connect application_type, which matters for desktop and CLI clients using localhost redirect URIs. Clients also bind registered credentials to the issuing authorization server’s issuer.

The migration checklist here is direct:

Verify iss handling in clients.
Confirm authorization servers send iss.
Check Dynamic Client Registration metadata.
Re-register when a resource moves between authorization servers.

This is especially relevant for MCP because one client may connect to many servers. Mix-up risks are not theoretical in that shape.

5. Stop building new work on deprecated core features

Roots, Sampling, and Logging are deprecated in the release candidate.

They still work. The deprecation is annotation-only for this release, and the methods, types, and capability flags continue to work in every spec version published within a year of it. Removal would require a separate SEP.

Still, new work should move elsewhere:

Roots should move to tool parameters, resource URIs, or server configuration.
Sampling should move to direct integration with model provider APIs.
Logging should move to stderr for stdio or OpenTelemetry for structured observability.

If you maintain SDK abstractions, this is the moment to add warnings without breaking users. If you maintain docs, stop teaching deprecated features as the default path.

6. Validate tool schemas against JSON Schema 2020-12

Tool inputSchema and outputSchema now use full JSON Schema 2020-12.

For input schemas, the root still has to be type: "object", but schemas can now use oneOf, anyOf, allOf, conditionals, $ref, and $defs. Output schemas are unrestricted. structuredContent can be any JSON value instead of only an object.

That creates opportunity and risk.

Servers should bound schema depth and validation time. Implementations should not auto-dereference external $ref URIs. Clients that made assumptions about simple object-only schemas need tests against composed schemas.

Also check error handling. The missing resource error changes from MCP’s custom -32002 to the JSON-RPC standard -32602 Invalid Params. If your client matches on the literal code, update it.

As you work through the checklist, if you find any issues or major friction points bring them to the community. You can open an issue in the specification repository. For implementation questions, the relevant Working Group channel in the contributor Discord is the fastest path to an answer.

MCP Server or CLI: A Decision Rubric for Developer Tooling

Ben Greenberg — Wed, 01 Jul 2026 14:29:03 +0000

Teams are rushing to make their internal tools available to agents. That is good. It is also where a lot of design mistakes begin.

The question usually shows up like this:

Should we expose this as an MCP server, or should the agent just use our CLI?

That framing makes it sound like one option is more “agentic” than the other. I do not think that is the useful distinction. A CLI and an MCP server solve different problems. The better question is: where does this capability naturally live, and what contract does the agent need in order to use it well?

MCP, now hosted by the Agentic AI Foundation under the Linux Foundation, gives the open agentic AI ecosystem a shared protocol for connecting agents to tools, data, and applications. That shared protocol matters because teams should not have to rebuild the same integration patterns for every agent runtime. But MCP is not a reason to wrap every executable in a server. Sometimes a CLI is exactly the right interface. Sometimes an MCP server is. Often, the answer is both, with different responsibilities.

Here is the rubric I use.

Start with the workflow

A CLI is strongest when the workflow already belongs to a human developer.

If the task is repo-local, terminal-native, and already part of how developers build, test, debug, or ship software, start with the CLI. Developers know how to inspect it. CI can run it. Logs are usually visible. Failures can be reproduced outside the agent. The same interface works for humans, scripts, and automation.

Good CLI-shaped examples:

Running a project-specific code generator
Applying a migration in a local development environment
Linting, formatting, testing, or packaging
Inspecting repo state
Scaffolding files inside a checked-out project
Running one-off diagnostics where stdout and exit codes are enough

An MCP server is strongest when the workflow does not naturally belong in a terminal session, or when the agent needs a structured, discoverable capability instead of a command string.

Good MCP-shaped examples:

Reading from or writing to a SaaS API
Searching a private knowledge base
Fetching typed records from an internal system
Performing actions that need scoped authorization
Exposing capabilities across multiple agent clients
Providing context as resources, not just command output
Giving the agent a constrained set of tool calls instead of broad shell access

The trap is assuming that “agent can run command” and “agent has a good tool interface” are the same thing. They are not.

A CLI gives an agent a way to execute. MCP gives an agent a way to understand what capabilities exist, what inputs they accept, and what kind of result comes back.

The five-question rubric

When deciding between a CLI, an MCP server, or both, I like to ask five questions.

1. Is this primarily an interactive human workflow?

If yes, prefer a CLI.

Developers still need tools that work when no agent is involved. If a human would reasonably run the tool while sitting inside a repo, reading logs, adjusting flags, and retrying, a CLI is usually the right primary interface.

That does not mean agents cannot use it. Agents are quite good at driving existing developer workflows when the commands are documented and the outputs are predictable. This is where AGENTS.md fits naturally: document which commands are safe, how to run tests, what directories are off-limits, and what failure modes are expected.

The CLI should be boring in the best way:

Clear subcommands
Stable flags
Machine-readable output where useful
Non-zero exit codes on failure
Dry-run modes for risky actions
Good help text
No hidden interactive prompts in automation paths

If the tool needs a human to make judgment calls mid-run, keep that interaction in the CLI. Do not hide it behind an MCP tool and pretend the workflow became autonomous.

2. Does the agent need to discover the capability?

If yes, lean toward MCP.

One of the real advantages of MCP is that tools can be described to the agent as tools. The agent does not need to infer everything from a README, shell history, or tribal knowledge. It can see available tool names, descriptions, schemas, and expected inputs.

That matters when the capability is meant to be reused across agents or across teams.

A CLI can be documented well, but discovery is still indirect. The agent needs to know the command exists, know where it is installed, know how to call it, and know how to interpret the output. MCP makes the capability part of the agent’s tool surface.

Use MCP when the agent should be able to answer questions like:

What tools are available to me?
What arguments does this action require?
What resources can I inspect?
What shape will the result have?
What actions are allowed in this environment?

This is especially useful for APIs and internal systems where a raw CLI would either expose too much or force the agent to learn a human-oriented interface.

3. Where is the auth boundary?

If the action crosses an authorization boundary, consider MCP carefully.

A CLI often inherits the developer’s local environment: shell credentials, config files, tokens, SSH agents, cloud profiles. That can be fine for local workflows. It can also be too broad for agent access.

MCP gives teams a cleaner place to define permission boundaries. The server can expose only the operations the agent should have. It can scope credentials server-side. It can validate inputs before touching the underlying system. It can log tool calls in a way that is easier to review than arbitrary shell execution.

This does not make MCP magically safe. A poorly designed MCP server can still be dangerous. But the server boundary gives you a place to enforce policy.

Ask:

Should the agent inherit the user’s full shell environment?
Should this action use delegated or scoped credentials?
Do we need per-tool authorization?
Do we need audit logs of agent actions?
Do we need to prevent arbitrary command composition?

If the answer to those questions is yes, a CLI alone may be too blunt.

For production-facing systems, this is also where infrastructure projects like agentgateway become relevant. Once agent traffic spans MCP servers, APIs, models, and services, teams need consistent policy, routing, and observability. That is a different layer than the individual tool decision, but the design choices connect.

4. Is the operation stateful?

State changes raise the bar.

A read-only diagnostic command is one thing. A tool that creates tickets, deploys services, updates customer data, rotates secrets, or changes infrastructure is another.

For state-changing actions, the interface should make the action hard to misuse. That can be done in a CLI, an MCP server, or both. The question is which interface gives you the better control surface.

A CLI might be right when the state change belongs in a developer-controlled workflow:

Apply this migration to my local database
Generate this file in my branch
Create a release artifact after tests pass

An MCP server might be right when the state change touches an external system:

Create an incident
Update a CRM record
Open a pull request with a structured payload
Provision access for a user
Trigger a workflow in a deployment platform

For stateful MCP tools, I would avoid generic verbs like run, execute, or update when the action can be modeled more specifically. The tool should say what it does. The input schema should constrain what can happen. The response should include enough structured data for the agent to verify the result.

For stateful CLIs, I want dry-run support, confirmation controls that can be disabled only in explicit automation modes, and output that makes it clear what changed.

The shared principle is the same: the agent should not be guessing.

5. What is the maintenance cost?

Every new interface becomes a product surface.

A CLI needs packaging, versioning, docs, help text, examples, and compatibility guarantees. An MCP server needs all of that plus server lifecycle, transport decisions, schema design, client compatibility, authentication, deployment, monitoring, and operational ownership.

That cost may be worth it. But it should buy something real.

An MCP wrapper around a CLI can be useful when it adds:

Better tool descriptions
Safer input validation
Structured outputs
Scoped permissions
Shared access across agent clients
A stable abstraction over a messy underlying command
Resource access the CLI does not provide well

An MCP wrapper is probably not worth it when it only shells out to an existing command and returns the same text output the agent would have seen anyway.

That does not mean “never wrap a CLI.” It means the wrapper should create leverage. If the MCP server is only a thinner, less debuggable path to the same command, keep the CLI and document it well.

The “both” pattern

Many teams should build both, but not as duplicates.

A good pattern is:

The CLI remains the human and CI interface.
The MCP server exposes selected capabilities for agents.
Shared core logic lives below both interfaces.
The MCP server does not become a dumping ground for every CLI command.
The CLI does not become an escape hatch for unsafe agent actions.

For example, imagine an internal deployment tool.

The CLI might support the full developer workflow: build, validate, preview, deploy, rollback, inspect logs, and run local checks. It assumes the user is a developer with repo access and deployment permissions.

The MCP server might expose narrower tools: get deployment status, list services, create a preview environment, request a rollback plan, or fetch logs for a specific service. Those tools can have tighter schemas and safer defaults. They can also return structured data that an agent can reason over without parsing terminal output.

Both interfaces can call the same underlying deployment library. They do not need to expose the same surface area.

That separation is healthy. Humans need power tools. Agents need constrained capabilities with clear contracts.

A practical decision guide

Use a CLI when:

The task is repo-local or terminal-native
Humans need to run it directly
CI should run the same interface
Shell composition is a feature
Text output and exit codes are enough
The auth model is already appropriate for the local developer context

Use an MCP server when:

The agent needs discoverable tools or resources
The task touches an external system
Inputs and outputs should be typed
Permissions need to be scoped
Multiple agent clients should share the same integration
The tool should hide implementation details
Auditability and policy matter

Use both when:

Humans and agents both need the capability
The CLI is already valuable
The MCP server can expose a safer or more structured subset
Shared core logic can prevent drift
The agent interface should be stable even if the CLI evolves

Do neither, at least for now, when:

The workflow is not understood yet
The tool would expose broad credentials without guardrails
The “agent use case” is just novelty
A README update would solve the immediate problem
The maintenance owner is unclear

What this means for the open agentic AI ecosystem

The open agentic AI ecosystem needs standards like MCP. It also needs restraint.

If every team turns every script into an MCP server, agents get a larger tool list but not necessarily better tools. Tool overload is real. Poor descriptions, loose schemas, unsafe side effects, and noisy outputs make agents worse, not better.

The goal is not to make everything agent-accessible. The goal is to make the right capabilities available through the right contract.

That is why this decision matters so much at this particular moment. MCP gives builders a common way to expose tools and context. AGENTS.md gives projects a common place to tell coding agents how to work inside a repo. agentgateway points toward the operational layer teams need when agent traffic becomes production traffic.

These projects are stronger when we use them for the problems they actually solve.

A CLI is not “less agentic” because it runs in a terminal. An MCP server is not “better architecture” because it speaks a protocol. The useful line is simpler:

If the work belongs in the developer workflow, start with a CLI.

If the agent needs a structured, discoverable, permissioned capability, build an MCP server.

If both humans and agents need it, design both surfaces intentionally and keep the shared logic underneath.

That is the rubric. Not CLI versus MCP. CLI where the workflow lives. MCP where the capability needs a contract.