DEV Community: Ben Greenberg

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.

Turn a local skill library into agent-ready documentation

Ben Greenberg — Wed, 24 Jun 2026 11:32:16 +0000

Most agent setups start with a pile of useful local skills.

That pile usually makes sense to the person who built it. There is a skill for GitHub, one for writing, one for reminders, one for privacy filtering, one for making diagrams, one for checking session logs, one for working with canvases, one for creating new skills, and so on.

The problem shows up later, when a future agent has to decide what to do.

A local skill library answers the question, “What can this environment do?”

An AGENTS.md file should answer a different question:

When should an agent use each capability, what should it read first, what tools are safe to call, and what boundaries should it respect?

That difference matters. A directory full of skills is an inventory. Agent-ready documentation is an operating map.

This tutorial uses an OpenClaw-style skill library as the worked example, but the same pattern applies to any local agent setup.

Start with capabilities, not files

A common mistake is to document skills in filesystem order.

That gives you something like this:

- github
- writing-style-skill
- privacy-filter
- remind-me
- canvas
- skill-creator
- session-logs

That list is technically true, but it does not help an agent make decisions.

A better first pass groups skills by the work they enable:

## Capability map

### Development workflows

Use these when the user asks about code, repositories, issues, pull requests, debugging, or project maintenance.

- github: interact with GitHub through the `gh` CLI
- gh-issues: fetch issues, select candidates, delegate fixes, and open PRs
- node-inspect-debugger: debug Node.js processes
- python-debugpy: debug Python code

### Writing and publishing

Use these when the user asks for drafts, essays, social posts, newsletters, or style-sensitive writing.

- writing-style-skill: draft in the user's preferred voice
- blog-drafter: create blog drafts
- x-posts: optimize short-form posts and threads

### Safety and privacy

Use these when content may contain personal data, secrets, or sensitive context.

- privacy-filter: redact PII from text or files
- 1password: retrieve secrets through the approved CLI flow

### Personal automation

Use these when the user asks for reminders, home devices, calendar checks, or recurring background tasks.

- remind-me: create one-time reminders
- taskflow: coordinate longer detached jobs
- weather: check current weather and forecasts

This turns the library into a decision surface. The agent no longer has to infer that writing-style-skill is relevant to an essay draft, or that privacy-filter should be considered before sharing text externally. The map says so.

Add triggers

A capability map becomes much more useful when each section includes triggers.

Triggers are short descriptions of the user intent that should cause the agent to load a skill.

For example:

## Writing and publishing

Load `writing-style-skill` when the user asks to:

- draft an article, essay, email, talk abstract, or newsletter
- rewrite something in their voice
- adapt technical content for developers
- make a draft sound less generic

Load `x-posts` when the user asks to:

- write a post for X
- turn an idea into a thread
- improve a short social post for reach or clarity

Load `blog-drafter` only when the user explicitly wants a blog draft created.

The last line matters. Some skills only produce local context. Others take external action. blog-drafter crosses that boundary because it creates a draft in a publishing system. The agent needs to know that this should not happen casually.

Good triggers are concrete. Bad triggers are vague.

Bad:

Use this for content.

Better:

Use this when drafting or revising long-form writing, especially when tone and structure matter.

Best:

Load `writing-style-skill` before drafting blog posts, essays, conference abstracts, newsletter sections, or public-facing technical explanations.

The best version tells the agent what the user might actually say.

Document the first file to read

Many local skills have their own SKILL.md. An agent should not guess from the skill name alone. The root AGENTS.md should tell the agent which file is authoritative.

Example:

## Skill loading rule

When a task matches a skill, read that skill's `SKILL.md` before taking action.

Do not rely only on the skill name or description. The skill file may include safety rules, required tools, local paths, examples, or external-action limits.

For a local OpenClaw skill set, this is especially useful because different skills have different operational shapes.

A writing skill might mostly contain tone rules and examples.

A GitHub skill might specify preferred gh commands and review behavior.

A home automation skill might include device-specific constraints.

A privacy skill might define which data must be filtered before sharing.

The root file does not need to duplicate all of that. It needs to make skill loading mandatory and predictable.

Separate internal work from external action

Agent documentation should make one distinction very clear:

Reading, drafting, searching, and organizing are internal actions.

Sending, posting, publishing, deleting, buying, messaging, or changing real-world systems are external actions.

That boundary belongs near the top of AGENTS.md.

Example:

## External action boundary

The agent may freely:

- read local files
- inspect skill documentation
- draft text
- run non-destructive local checks
- prepare changes for review

The agent must ask before:

- sending email or messages
- publishing posts
- creating public drafts
- deleting data
- changing account settings
- controlling physical devices
- spending money

For OpenClaw-style environments, this boundary keeps powerful skills usable without making them reckless. A github skill that reads issues is different from one that opens a pull request. A blog skill that drafts locally is different from one that creates a draft in an external service. A govee or homeconnect skill can affect the physical environment.

Write those distinctions down.

Agents are much better when they do not have to reconstruct your risk model from vibes.

Capture tool boundaries inside each capability

A capability map should not only say what a skill does. It should say what the agent should avoid doing.

For example:

## Privacy and redaction

Use `privacy-filter` before sharing user-provided text outside the local workspace when it may contain:

- names
- addresses
- phone numbers
- email addresses
- account identifiers
- private messages
- internal business context

Do not paste raw private content into public channels or external tools unless the user explicitly approves it.

Or for GitHub:

## GitHub work

Use `github` for repository, issue, pull request, and CI work.

Safe without asking:

- inspect issues and PRs
- read CI logs
- check branch status
- prepare local patches

Ask before:

- opening a PR
- commenting publicly
- closing issues
- pushing branches to shared remotes

This is the part many local docs miss. They document how to use a tool, but not when to stop.

Include sequencing rules

Some skills should run before others.

In the OpenClaw set, writing-style-skill should load before drafting. privacy-filter should run before sharing sensitive text externally. skill-creator should load before changing skill files. github should load before acting on GitHub state.

That can be expressed as simple sequencing rules:

## Sequencing rules

Before drafting public writing, load `writing-style-skill`.

Before creating or modifying a reusable skill, load `skill-creator`.

Before using private text in an external channel, consider `privacy-filter`.

Before taking GitHub action, load `github` and inspect the current repository state.

Before using a tool that affects the outside world, confirm the user intended that action.

These rules save agents from doing work in the wrong order.

A good AGENTS.md does not need to cover every possible path. It should cover the paths where ordering matters.

Give agents examples of correct routing

Examples are often more useful than rules.

Here is a compact routing table:

## Routing examples

User asks: "Draft this as a technical blog post."
Use: `writing-style-skill`
Do: draft in the user's preferred voice
Do not: publish it anywhere

User asks: "Turn this into a blog draft."
Use: `writing-style-skill`, then `blog-drafter`
Do: prepare the content first
Ask before: creating the external draft, unless the user clearly requested that exact action

User asks: "Can you fix this GitHub issue?"
Use: `github`, possibly `gh-issues`
Do: inspect the issue, read the repo, make local changes, run tests
Ask before: opening a PR if the instruction was ambiguous

User asks: "Remember this workflow as a reusable skill."
Use: `skill-creator`
Do: create or update the skill through the approved skill workflow
Do not: hand-edit skill proposal state if the environment has a dedicated tool for that

User asks: "Share this private message in a public post."
Use: `privacy-filter`
Do: redact or summarize safely
Ask before: publishing or sending

The point is not to create a huge rules engine. The point is to give future agents enough examples to route the next request correctly.

Keep local notes out of shared skills

A reusable skill should explain general behavior. Local environment details belong somewhere else.

For OpenClaw-style workspaces, that might mean:

SKILL.md       -> reusable instructions
TOOLS.md       -> local device names, account aliases, hostnames, personal setup notes
AGENTS.md     -> workspace-level operating rules
MEMORY.md     -> durable user and project context

This separation keeps skills portable.

A weather skill can explain how weather lookup works. The local notes can say which city is usually relevant. A canvas skill can explain how to present HTML on connected nodes. Local notes can say which node names exist in this setup.

That distinction is small, but it keeps a skill library from turning into a private config dump.

Make safety boundaries visible, not buried

If a skill can send, post, delete, control, spend, or expose private data, say so in the capability map.

A practical format:

## High-risk skills

These skills can affect external systems or expose private data. Load their `SKILL.md` and confirm intent before using them for external action.

- blog-drafter: creates drafts in a publishing account
- imsg: can send iMessage/SMS
- work-slack: reads workplace Slack data
- gog/work-google: access personal or work Google data
- govee/homeconnect/sensibo/switchbot: control physical devices
- 1password: accesses secrets

This does not mean the skills are unsafe. It means they are powerful.

Agents do better with clear labels.

Write the root AGENTS.md as an operating manual

A useful AGENTS.md should be short enough to read and strong enough to steer behavior.

A good structure looks like this:

# AGENTS.md

## Role

You are working inside this workspace. Read local instructions before acting. Prefer existing skills and tools over inventing new workflows.

## Startup

Read:

- SOUL.md
- USER.md
- recent daily memory files
- MEMORY.md when in a direct private session

## Capability map

Group available skills by task:

- development workflows
- writing and publishing
- privacy and safety
- personal automation
- debugging and inspection
- media and presentation
- skill maintenance

## Skill loading

When a task matches a skill, read that skill's `SKILL.md` before acting.

## External action boundary

Internal work is allowed. External action requires clear user intent or confirmation.

## Safety rules

Protect private data. Prefer recoverable actions. Do not run destructive commands casually.

## Routing examples

Include examples of common user requests and the skills they should trigger.

## Local notes

Put machine-specific details in `TOOLS.md`, not in reusable skills.

That is enough to turn a pile of local skills into a working agent interface.

Treat AGENTS.md as a map, not a museum

The file should change as the skill library changes.

When you add a new skill, add it to the capability map. When a tool gains external side effects, move it into the high-risk section. When an agent makes a routing mistake, add a small example that would have prevented it.

The best AGENTS.md files are not long. They are current.

For developers building local agent systems, this is the real payoff: your skill library stops being something only you understand. It becomes a documented capability layer that future agents can read, reason over, and use correctly.

That is what agent-ready documentation is for.

An AI agent that pays for its own API calls on AWS

Ben Greenberg — Fri, 29 May 2026 11:27:13 +0000

I built a small AWS Bedrock AgentCore agent that pays for a paywalled API with real USDC on Arbitrum One. It asks for a report, gets back HTTP 402 Payment Required, settles the charge on its own, and retries. No API key, no card on file, no human clicking approve. The settlement lands on Arbitrum One mainnet, and the run prints an Arbiscan link to the transaction so you can read it yourself.

There's a great walkthrough of the same idea on Base Sepolia by William Mendoza Gopar. This post expands upon his work: mainnet instead of testnet, real USDC instead of a burn-address demo, and a merchant built on CloudFront, Lambda@Edge, and API Gateway. The full source is at github.com/hummusonrails/arbitrum-x402-aws.

What AgentCore gives you

AgentCore is AWS's hosted runtime for AI agents, still in preview. The piece this project leans on is AgentCore Payments: a managed signer that holds an embedded wallet for you and produces payment authorizations on request. Your code asks the PaymentManager to handle a charge, and the private key stays inside AgentCore.

You stand up four resources once: a PaymentManager with a connector to Coinbase CDP, an embedded crypto wallet as a PaymentInstrument, and a PaymentSession that carries a spend budget and an expiry. After that, paying is a single call.

What x402 is

x402 puts the 402 Payment Required status code to work. A paid endpoint answers an unpaid request with 402 and a JSON body describing what it wants: the network, the token, the recipient, and the amount. The client signs an EIP-3009 transferWithAuthorization for USDC, which lets someone else submit the transfer on-chain, and resends the request with the signature attached. The server verifies and settles through a facilitator, then returns the content. No accounts to create, no keys to rotate, and charges as small as a fraction of a cent. That last property is what lets an agent use it with no human in the loop.

One aside on the AWS side: this x402 support is a brand-new preview release. This week I worked with the AWS team to make sure it settles across EVM chains, Arbitrum One included, so the wallet, the facilitator, and the settlement path behave the same way on Arbitrum as on any other EVM network.

Why Arbitrum One

An agent that pays per API call cannot spend a dollar in transaction fees to move a fraction of a cent. The math only works if the settlement layer makes sub-cent payments cheap enough to vanish into the cost of the call itself. Arbitrum One clears that bar on price.

Price is half of it. The other half is predictability.

An agent commits to a workflow and runs it; it cannot pause to renegotiate when gas spikes partway through. When fees jump for a few minutes, a person shrugs and waits, but an agent paying per call either overpays or stalls. Arbitrum's gas pricing is built to absorb those spikes. The recent Arbitrum One upgrade replaced the old single-target pricing model, and during peak activity it cut gas by around 98% compared to what that model would have charged. Fees stay low, and they stay close to where they were a minute ago. For x402 micropayments, that stability is worth as much as the headline number.

The shape of the demo

Three pieces talk to each other. The agent runs on AgentCore with its embedded CDP wallet. The merchant is an AWS stack: CloudFront in front, a Lambda@Edge function on viewer-request that speaks x402, and an API Gateway HTTP API with a Lambda behind it that holds the report. Settlement runs through the Coinbase CDP facilitator, which broadcasts the USDC transfer on Arbitrum One.

The round trip looks like this. The agent does a GET /report. Lambda@Edge sees no payment and returns 402 with the terms. The agent asks AgentCore to produce a payment for those terms and retries. This time Lambda@Edge has a payment header, calls the facilitator to verify and settle, and on success passes the request through to API Gateway, which returns the gated JSON.

The agent side

The agent code is short because the wallet logic lives in AgentCore. It makes a normal GET. If the response is anything other than 402, it returns it. If it is a 402, it hands the whole challenge, status, headers, and body, to generate_payment_header, which reads the terms, signs the authorization inside the embedded wallet, and returns the header to attach. Then it retries the GET.

def fetch_with_payment(*, client, payment_manager, url, user_id,
                       payment_instrument_id, payment_session_id):
    first = client.get(url)
    if first.status_code != 402:
        return first

    payment_required_request = {
        "statusCode": 402,
        "headers": dict(first.headers),
        "body": first.text,
    }
    proof_headers = payment_manager.generate_payment_header(
        user_id=user_id,
        payment_instrument_id=payment_instrument_id,
        payment_session_id=payment_session_id,
        payment_required_request=payment_required_request,
        network_preferences=["eip155:42161"],  # Arbitrum One
        client_token=str(uuid.uuid4()),
    )
    return client.get(url, headers=proof_headers)

I pass network_preferences=["eip155:42161"] so the payment targets Arbitrum One rather than relying on a default. The agent never builds EIP-712 typed data and never touches the private key. From the caller's point of view it made one GET and got back a 200 with the report and an Arbiscan link.

The merchant side

The payment logic sits in the Lambda@Edge function on viewer-request. With no payment header it returns the 402 and the accepts[] terms. With a header it decodes the payment, calls the CDP facilitator's /verify, then /settle, and returns the original request so CloudFront continues on to API Gateway. A verify or settle failure comes back as a fresh 402 or a 502.

One detail to note: CDP's facilitator uses short-lived JWTs that are bound to the exact request URL and method and expire in two minutes. You cannot mint one ahead of time and paste it into config. The edge function signs a fresh JWT with node:crypto for each verify and settle call, which is also why the CDP key material gets inlined into the edge bundle at build time (Lambda@Edge cannot read environment variables at runtime).

A design choice worth flagging: this version verifies and settles in viewer-request, before the origin responds. That keeps the demo to one function and one round trip. For production you want to verify in viewer-request and settle in viewer-response, so you only take the money after the content is delivered.

Funding it and running it

Setup is one command that creates the AgentCore resources and prints a wallet address. You fund that wallet with USDC on Arbitrum One, grant the agent signing permission, and paste the printed IDs into .env. Then:

$ make run-agent
GET https://<merchant>/report
  via AgentCore PaymentSession payment-session-...
  using Instrument            payment-instrument-...

Status: 200
Body:
{ ...gated report JSON... }

Arbiscan: https://arbiscan.io/tx/0x...

The agent requests the report, pays, and prints the JSON plus the transaction link. The whole round trip takes a few seconds, most of it the facilitator talking to the chain. The charge in the repo is 0.01 USDC per call.

Cost and the preview caveat

Idle, this costs close to nothing. CloudFront, Lambda@Edge, API Gateway, and AgentCore are billed per use, and the demo's traffic fits inside their free tiers. Per call you pay the 0.01 USDC settlement and a rounding error of compute.

AgentCore Payments is in preview, so treat it that way. Field names and SDK shapes can move between releases, and I hit a few of those while building this. Pin your versions and re-test after you upgrade.

Where this goes next

The same pattern extends in two directions worth trying. The agent can pay several different x402 endpoints with the same wallet and session, which makes it a buyer for any priced API it can reach. And the spend budget on the PaymentSession is the natural place to wire an alert or a hard stop, so an agent that misbehaves runs out of allowance instead of running up a bill.

Resources

Repo: github.com/hummusonrails/arbitrum-x402-aws
The Base Sepolia walkthrough by William: go to his blog
x402 protocol: x402.org
Bedrock AgentCore: aws.amazon.com/bedrock/agentcore
EIP-3009 (Transfer With Authorization): eips.ethereum.org/EIPS/eip-3009

I let a kosher lobster run my Shabbat automations

Ben Greenberg — Thu, 23 Apr 2026 06:22:18 +0000

What I built

I run an Orthodox Jewish household. That means twenty-five hours a week, every week, the family doesn't touch electronics, doesn't cook, and doesn't adjust the thermostat without thinking about it. Multiply that by the Jewish holiday calendar, where a holiday can chain into Shabbat for two days straight, and you have a real scheduling problem. The fridge needs to be in Sabbath mode before candle lighting and back to normal at the conclusion of the day. The bedroom AC needs a pre-cooled run that ends before sunset. The living room AC needs to know whether it's a heat wave week or not. None of these can be touched once the time starts.

I built a personal automation stack on top of OpenClaw that handles all of it. The lobster is in charge.

There is a small wrinkle here that I think is a bit funny. Lobsters are not kosher. The mascot of the open source agent platform managing my religiously observant home is, in fact, one of the most explicitly non-kosher animals. The lobster AI has been very gracious about all of that.

How I used OpenClaw

OpenClaw skills are just directories with a SKILL.md and whatever scripts you want the agent to call. That structure made it natural to build each appliance as its own skill and then layer scheduler scripts on top that get triggered by cron jobs not the LLM.

This split matters. The schedulers don't need an LLM in the loop. They need to be deterministic, idempotent, and survive me forgetting they exist. The agent layer is for the times I message OpenClaw on Telegram and ask "is the fridge already in Sabbath mode?" and want a real answer back.

Here are two of the schedulers, with the city ID swapped out so you can drop in your own.

The Shabbat scheduler

This one runs every Friday morning. It pulls candle lighting and havdalah times from Hebcal, then schedules at jobs to flip the fridge into Sabbath mode an hour before candle lighting and back out at it concludes.

pythondef get_shabbat_times():
    """Fetch this week's candle lighting and havdalah times."""
    resp = requests.get(HEBCAL_URL, params={
        "cfg": "json",
        "geonameid": MY_CITY_GEONAMEID,
        "M": "on",
    }, timeout=15)
    resp.raise_for_status()
    data = resp.json()

    candles = None
    havdalah = None
    parasha = None
    for item in data.get("items", []):
        if item.get("category") == "candles" and not candles:
            candles = datetime.fromisoformat(item["date"])
        elif item.get("category") == "havdalah" and not havdalah:
            havdalah = datetime.fromisoformat(item["date"])
        elif item.get("category") == "parashat" and not parasha:
            parasha = item.get("title", "")
    return candles, havdalah, parasha

Then the actual scheduling:

pythonsabbath_on_time = candles - timedelta(hours=1)
schedule_at_job(sabbath_on_time, "on")
schedule_at_job(havdalah, "off")

That's the whole shape of it. Hebcal is the single source of truth for times, the appliance skill is the single source of truth for how to talk to the fridge, and the scheduler just glues them together with at.

The Holiday scheduler

This is the one that took the most thought, because the Jewish holiday calendar is genuinely hostile to naive scheduling. Rosh Hashana is two days. Yom Tov can start as Shabbat ends and run another full day. Passover has a full holiday day with all restrictions on day one, the intermediate days in the middle with no electroni restrictions, and the holiday fully again on the last day.

You can't just toggle the fridge per holiday day. You need to know when the whole continuous Sabbath-mode period actually ends.

So the scheduler walks forward through consecutive holiday days and Shabbat as one block:

pythondef find_end_of_period(start_date, yomtov_dates):
    """Walk forward through consecutive Yom Tov days and Shabbat.
    Handles multi-day Yom Tov, Yom Tov flowing into Shabbat,
    and Shabbat sandwiched between Yom Tov days."""
    current = start_date
    while True:
        next_day = current + timedelta(days=1)
        if next_day in yomtov_dates or next_day.weekday() == 5:
            current = next_day
        else:
            break
    return current

The most useful piece, though, is the coordination between schedulers. When a holiday starts as Shabbat is ending, the Shabbat scheduler has already queued an OFF job for the end of Shabbat. If the holiday scheduler runs and just queues its own ON job on top, you get a brief window where the fridge exits Sabbath mode and re-enters it, which defeats the point. So the Yom Tov scheduler clears the conflicting Shabbat job before doing its own work:

pythonif dow == 5:  # Saturday: Yom Tov starts motzei Shabbat
    log("Yom Tov follows Shabbat, fridge already in sabbath mode")
    log("Cancelling Shabbat OFF job so sabbath mode stays on")
    clear_existing_jobs("shabbat_scheduler.py")

That one block is the kind of thing working through the full complexity of the calendar introduces you to.

The reminder

Half an hour before candle lighting, OpenClaw sends me a checklist over Telegram. Nothing too complicated, just a quick list:

pythonmessage = (
    f"Shabbat Reminder -- {parasha or 'Shabbat Shalom'}\n\n"
    f"Candle lighting in 1 hour at {candles_local}.\n"
    f"Havdalah at {havdalah_local}.\n\n"
    f"Checklist:\n"
    f"- Lights\n"
    f"- Fridge (SabbathMode)\n"
    f"- Door\n"
    f"- Plata / hot water"
)

The reminder doesn't take any actions on the appliances. The schedulers already did that. It's a human-in-the-loop check that the things requiring human judgement (the door key, the lights I forgot to switch) actually got handled.

The orchestration layer

Everything is wired together with launchd plists:

kosher-lobster.openclaw.cron.shabbat-scheduler.plist fires every Friday morning
kosher-lobster.openclaw.cron.yomtov-scheduler.plist fires daily
kosher-lobster.openclaw.cron.shabbat-ac.plist and shabbat-sleep.plist handle the AC zones
kosher-lobster.openclaw.cron.shabbat-reminder.plist fires the Telegram message

The AC schedulers are weather-aware. They pull a forecast, checks against a temperature threshold, and only generates ON/OFF blocks if the forecast warrants it. The data model shows the shape:

tsinterface ShabbatPlan {
  parasha: string;
  candles: string;
  havdalah: string;
  forecast: {
    friday_high_f: number;
    saturday_high_f: number;
    threshold_f: number;
    extreme_heat?: boolean;
  };
  temp_c: number;
  temp_f: number;
  blocks: ShabbatBlock[];  // ON/OFF time blocks
  status: string;          // active | skipped | cancelled
}

A mild Friday in spring? No AC plan generated, no electricity wasted. A heat wave week? Blocks get pre-computed and queued. The scheduler decides; I don't wake up at 5 AM to think about it.

What I learned

The thing I underestimated going in was how much of OpenClaw's value comes from the boundary it draws between agent-driven work and deterministic work. I started by trying to make OpenClaw as the LLM "decide" when to flip the fridge. That was a bad idea. There's no room here for an agent reasoning incorrectly about a calendar edge case.

The right pattern was:

The scheduler scripts are deterministic, and committable to git
The skill SKILL.md files teach the agent how to query state when I ask
The agent never takes scheduled actions on its own; it answers questions and runs explicit commands

OpenClaw's skill structure made that separation easy to maintain because each skill is just a folder. The schedulers live alongside the skills they call, share the same Python environment, and don't require any agent loop to function. If I uninstalled OpenClaw tomorrow the cron jobs would keep firing and the fridge would keep going into Sabbath mode on time. That's the right resilience property for this kind of automation.

The other thing I learned is that the agent shines exactly where the schedulers can't help.

"Is the AC set for this evening?" is a Friday-afternoon question I used to answer by a lot of inquiry into the weather, figuring out what we needed in each room and more. Now I message OpenClaw on Telegram and get the AC schedule shared with me in two seconds.

The schedulers handle the recurring; the agent handles the one-off. Both of those are first-class in OpenClaw and that's why this works.

The lobster, against all expectations, has turned out to be the most observant member of the household. He never forgets the time. He never opens the fridge without checking. He has read more of the Jewish calendar API than any of us.