DEV Community: kt

What Coding Agents Leave in Public Git Repos

kt — Wed, 04 Nov 2026 13:38:24 +0000

I let coding agents write a lot of my commits now. They write what they see, and what they see is my machine: /Users/<me>/src/... in a README, a project path in a notes file, a session link at the bottom of a commit. None of it is a secret, so no secret scanner flags it. It is still my account name, in public.

I wanted to know how common that is, so I counted with GitHub search and checked samples by hand.

The numbers

What	GitHub's count	Real in my sample	Rough estimate
`CLAUDE.md` with `/Users/<name>/`	27,424 files	105 of 300	~9,600 files
`AGENTS.md` with `/Users/<name>/`	26,208 files	140 of 300	~12,200 files
Claude Code project path `~/.claude/projects/-Users-<name>-…`	47,104 files	122 of 300	~19,000 files
Commits with a Codex task link	~50,800	431 of 500	~44,000 commits
Commits with a Claude Code session link	1.8M to 10.8M	500 of 500	millions

"Real" means the path holds an actual account name. I threw out placeholders like /Users/you/, /Users/username/ and /Users/<user>/; a third to a half of the hits survived that.

Caveats:

Code search only sees default branches of indexed repositories, so the file counts are a floor, not a census.
GitHub's commit count for the session link moved between 1.8 million and 10.8 million in one afternoon. All 500 of the newest results did contain one.
My samples are the first pages of results, not a random draw.
No repository or person is named here. Every number is an aggregate.

Why each one ends up there

Agent memory files. CLAUDE.md and AGENTS.md are where agents keep notes about a project, and agents write what they know: absolute paths to the repo, to a sibling checkout, to a log directory. Those paths start with your home directory, which is your login. The file then gets committed because it is supposed to be shared with the next session.

The project slug. Claude Code keeps per-project state under ~/.claude/projects/ in a directory named after the absolute path, so /Users/taro/src/app becomes -Users-taro-src-app. That slug shows up in notes, logs and debugging output that agents paste into the repository.

Session links. Some agent setups add a trailer like Claude-Session: https://claude.ai/code/session_… to each commit, or a task link to the PR body. What the link does publicly is tie a commit to an agent session and, across repositories, tie commits to each other.

Check your own

Your commits with a session link:

gh search commits "claude.ai/code/session_" --author <your-github-login>

Your public files with your home path:

gh search code "/Users/<your-login>/" --owner <your-github-login>

In a local clone, including deleted files and commit metadata:

brew install --cask kanywst/tap/kwangmyong
kwangmyong init
kwangmyong scan --history .

Stop it at the source

Scanning finds what is already out. kwangmyong hook claude stops it before the write: as a Claude Code PreToolUse hook it blocks git commit, git push, gh bodies, file writes and GitHub MCP calls that carry your name, login, email, hostname or home path, and tells the agent why with the value masked. Codex, Gemini CLI, Cursor, Copilot, Windsurf, Kiro and Devin have adapters too.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit|mcp__github__.*", "hooks": [{ "type": "command", "command": "kwangmyong hook claude" }] }
    ]
  }
}

Method

Run with gh api on 2026-11-04:

code: "/Users/" filename:CLAUDE.md, "/Users/" filename:AGENTS.md, "-Users-" ".claude/projects", first 300 results each, text-match fragments checked with a regex, placeholders excluded
commits: "claude.ai/code/session_" and "chatgpt.com/codex/tasks", newest first, 500 results each, messages checked with a regex

Source for the tool: https://github.com/kanywst/kwangmyong

Secret Scanners Look for Credentials. I Wanted One That Looks for Me.

kt — Wed, 04 Nov 2026 04:39:45 +0000

I let coding agents write a lot of my commits now. They write what they see, and what they see is my machine: /Users/<me>/... in a README, me@my-laptop ~ % in a pasted test log, a claude.ai/code/session_... link at the bottom of a PR body.

None of that is a credential, so secret scanners don't flag it. I wanted one that knows who I am.

Source: https://github.com/kanywst/kwangmyong
Install: brew install --cask kanywst/tap/kwangmyong or go install github.com/kanywst/kwangmyong/cmd/kwangmyong@latest

Same repository, two scanners

The demo is a four-commit repository for a made-up developer, Taro Yamada (login tyamada, laptop Taros-MacBook-Pro):

README.md mentions /Users/tyamada/src/app/log
NOTES.md mentions ~/.claude/projects/-Users-tyamada-src-app/memory
test.log has tyamada@Taros-MacBook-Pro app % make test
one commit message ends with a Claude Code session URL
AUTHORS with 山田太郎 was added in one commit and deleted in the next

gitleaks 8.30.1:

$ gitleaks git . --no-banner
INF 3 commits scanned.
INF scanned ~204 bytes (204 bytes) in 36.2ms
INF no leaks found

Correct. There are no secrets in it.

What kwangmyong shows

On a terminal, kwangmyong scan --history . sweeps the repository with a live count, then opens this:

Every value is masked as a prefix and a fingerprint (ty…[b35fc2ee]), so a screenshot or a CI log is not a new leak. r reveals values on that screen only. Search only sees masked text, so typing your own name into it finds nothing.

ALSO lists the other places the same value turns up. FIX depends on where it is: a file needs an edit, a deleted file or a commit message needs a history rewrite, and p drafts that rewrite (git filter-repo inputs plus a checklist of what a rewrite cannot reach) without leaving the screen.

Quit, and the verdict stays in the scrollback:


╭────────────────────────────────────────────────────────────────────────────╮
│ ✗ TARGET EXPOSED  6 pieces of intel on you, from 5 places                  │
│   4 to fix in files · 2 baked into history                                 │
│   threat level ■■■■□ HIGH                                                  │
│   swept 3 files · 4 commits · 1 deleted blob                               │
│   looked for 2 names · 1 login · 1 host · home paths · agent session links │
│   values are masked · --reveal shows them                                  │
│   next ▸ kwangmyong plan .  drafts the history rewrite for you to review   │
╰────────────────────────────────────────────────────────────────────────────╯

A clean repository gets ✓ TARGET DARK with what was swept and what was looked for, so "nothing found" also says how hard it looked. Piped, in CI, or with --format json|sarif, the same report prints without the UI.

It starts from who you are

The profile lives in ~/.config/kwangmyong/config.toml, never in the repository, and kwangmyong init fills it in from the machine: login, home directory, full name, hostname, global git identity.

[identity]
names  = ["Taro Yamada", "山田 太郎"]
logins = ["tyamada"]
hosts  = ["Taros-MacBook-Pro"]

Each value is expanded into the forms it actually shows up in: tyamada, t.yamada, Yamada Taro, -Users-tyamada-, Taro's MacBook Pro. Session links from Claude Code and Codex are flagged without any config.

Stop the agent, not just the commit

The part I use most is the hooks. kwangmyong hook install sets up pre-commit, commit-msg and pre-push for a repository. For agents, the pre-tool hook gets the tool call before it runs:

Agent	Hook
Claude Code	`kwangmyong hook claude`
Codex CLI	`kwangmyong hook codex`
Gemini CLI	`kwangmyong hook gemini`
Cursor	`kwangmyong hook cursor`
GitHub Copilot	`kwangmyong hook copilot`
Windsurf, Kiro, Devin	`kwangmyong hook windsurf`, `kiro`, `devin`

It checks git commit, git push, gh bodies and body files, file writes into the repository and GitHub MCP writes, and exits 2 to block. The agent gets the reason back, masked:

✗ TRANSMISSION BLOCKED. kwangmyong stopped this command: it would hand out intel on you.

[HIGH] command gh:3
  3 │ ht…[bf572e0c]'
    │ ^^^^^^^^^^^^^ your agent's session link

fix ▸ use ~/ or repo-relative paths, your public handle instead of a real name,
      the GitHub noreply address as the commit email, and no agent session links.

CI

- uses: kanywst/kwangmyong@v0
  with:
    identity: ${{ secrets.KWANGMYONG_IDENTITY }}
    sarif: kwangmyong.sarif

The identity comes from a secret as TOML. The Action checks the release binary against its signed checksums, and the SARIF is masked no matter what.

Not covered yet

Wikis, Actions logs, Discussions.

Source and issues: https://github.com/kanywst/kwangmyong

Ransomware in Japan: 61 of 92 Known Entry Points in 2025 Were VPN Appliances

kt — Tue, 27 Oct 2026 14:47:29 +0000

Japan's National Police Agency surveys ransomware victims about how the attacker got in. In 2025, 92 could say. 61 named their VPN appliance. Two named email.

Most security training is still about email. I built a site that shows where the intrusions actually started.

Site: https://0-draft.github.io/vpn-is-the-door/ (Japanese: https://0-draft.github.io/vpn-is-the-door/ja/)
Source: https://github.com/0-draft/vpn-is-the-door

One square per case, stacked outside the opening the attacker used.

One company, drawn as a floor plan

The site follows a fictional 280-person parts maker. Email comes in through the main entrance and gets checked at reception. The VPN appliance is a door in the outer wall that lets staff in without passing reception; it opens into the corridor behind it.

What happens after the door opens

Chapter 2 is a scroll-driven plan: the door opens, Active Directory falls, backups are deleted, data leaves through the same door, and encryption comes last.

In 2025, 79 of the 99 Japanese victims that tried to restore from backup could not, and 48 found their backups encrypted too. The chapter also maps the published investigation report of an Osaka hospital onto the same steps.

31 exploited VPN flaws

Chapter 3 lists 31 VPN and remote-access flaws from CISA's Known Exploited Vulnerabilities catalog (FortiGate, Ivanti Connect Secure, Citrix NetScaler, Palo Alto GlobalProtect, SonicWall and others). Selecting a row shows which part of the door it breaks.

29 of the 31 are reachable before login, so MFA never comes into play.
19 were exploited before the vendor warned anyone.
For 17, patching alone did not close the door: stolen credentials or sessions stayed valid, or the intruder's implant survived the update.

Where each control actually helps

The last figure in chapter 6 lets you pick how the attacker gets in and which controls are on, then shows where the route stops.

MFA does nothing against a pre-auth flaw. An offline backup lets you recover from encryption but does not stop the leak.

Cases, in the organizations' own words

Chapter 4 has 15 real incidents, including Asahi Group, ASKUL, three Japanese hospitals and Colonial Pipeline. Each is based only on the organization's own statement or an official investigation report. If an organization wrote "network device", the page says "network device". Nine of the 15 name a VPN appliance.

How the numbers were checked

NPA figures come from NPA's own statistics workbooks, sheet by sheet. Percentages are computed in one place and unit-tested against NPA's published roundings.
Every KEV field was checked with jq against the catalog JSON; the 2026-numbered CVEs were also checked against the NVD API.
Anything not confirmed in a primary source is left out. The 80 cited documents are listed on the sources page.

No exploit code or attack steps appear anywhere.

How it's built

Astro 7, static, on GitHub Pages. No UI framework; the interactive figures are plain TypeScript. The floor plan is data, and a test fails if the intruder's route crosses a wall anywhere but a doorway. Search is Pagefind, and the OG images are drawn at build time with satori. CI runs axe, a link check that includes #fragments, and a Lighthouse budget. A weekly job compares the door schedule with the live KEV catalog.

If a number or attribution is wrong, open an issue with the source that shows it.

Mandatum: Making an AI Agent's Authority a Chain You Can Verify

kt — Wed, 16 Sep 2026 10:45:49 +0000

Update (2026-11-08): mandatum has since been archived at v0.2.0 and is no longer developed. The code and the specification stay readable, and the open questions below are still worth arguing with, but nothing here will be fixed or extended.

Introduction

Almost every AI agent acting for a person does it by inheriting a credential: a service account, an API key, a shared token, the user's own session.

Three things break the moment you do that. Two surveys put a rough number on the first of them: 28% of organizations can reliably trace agent actions to a human or system across all environments (Cloud Security Alliance and Strata Identity, Securing Autonomous AI Agents, February 2026; n=285), and 68% cannot clearly distinguish AI agent activity from human activity (Cloud Security Alliance and Aembit, Identity and Access Gaps in the Age of Autonomous AI, March 2026; n=228). Both are vendor-commissioned and self-reported, and neither says "human sponsor" — the first says "human or system".

So I built mandatum.

Repo (archived): https://github.com/kanywst/mandatum

The three things

You cannot say who is responsible. The audit log has a service account in it. Which human was that?

You cannot revoke one agent. Everything shares the credential, so cutting off the misbehaving agent cuts off everything else. Nobody pulls that lever, so the agent keeps its access.

You cannot constrain a sequence. Authorization is decided one call at a time. An agent reads untrusted external content, then writes to an internal system. Both calls are legitimately authorized. The pair is the exfiltration.

MCP's authorization specification covers the transport: how a client gets a token for a server. It says nothing about which tool that token may call, which agent holds it, or who delegated to whom, and MCP's authorization interest group has open work on per-tool scopes and on consent across chains of agents. The Enterprise-Managed Authorization extension, stable since June 2026, gets an access token from an enterprise identity assertion, so what it produces is scoped to a server rather than to a call.

What mandatum does

An agent's authority becomes a signed chain rooted in a named human.

Each link commits to its parent by hash, so links are not interchangeable. Capabilities can only narrow going down. The human at the root is carried unchanged to every leaf, so attribution survives arbitrary sub-delegation. Revoke any link and everything below it dies with it. Nothing else does.

The library never decides authorization itself. It establishes that an agent holds authority a human delegated, then hands that to an OpenID AuthZEN PDP (OPA, Cedar, OpenFGA, whatever you already run). The request follows the AuthZEN COAZ-MCP binding's default mapping rather than a parallel one I invented — so far for tools/call only, without the binding's declared mappings or CEL, and with additions of my own that the conformance document lists as divergences.

The sequence part

The bottom block of that diagram is the bit I actually wanted to build, because per-call authorization structurally cannot do it:

go test -run Example ./pkg/sequence/ -v

write first:       allowed
read external:     allowed
write after read:  denied by no-write-after-external-read
sub-agent writes:  denied by no-write-after-external-read

The last line matters. State is keyed by the chain root, not by whoever is acting, so an agent cannot escape an inherited constraint by delegating to a sub-agent it just minted.

A constraint compiles to one bit (has the trigger fired) plus a counter. The state a chain accumulates is fixed-size however long it runs.

Three places I'd actually use it

A coding agent that can open pull requests. It reads a dependency's README, an issue comment, a diff from a fork: all attacker-writable. Then it pushes. Tag the reads external-content and the push mutating, and the second one stops after the first.

{ "id": "no-push-after-third-party-read",
  "forbid": { "resource.tags": ["mutating"] },
  "after":  { "resource.tags": ["external-content"] } }

A support agent that can issue credits. The customer's message is attacker-controlled text, and the refund tool moves money. Same shape, and the sponsor is the support engineer who approved the session, so the audit record names a person rather than svc-support-bot.

A research agent someone left running. max_invocations on the sponsor's grant caps the whole chain, and because state is keyed by the root, spawning ten sub-agents spends the same budget rather than ten of them.

None of these need a new policy engine. They need the tool call to know what happened earlier under the same authority.

What isn't built

There is no audit log yet. The sequence store is in-process only, which means one enforcement point. Two PEPs with separate memories give an agent two histories to spend. Nothing has had a third-party security review.

All of that is in the threat model, which lists what is not covered rather than only what is.

Where I'd like to be wrong

The design leans on a chain rather than a flat list of prior actors. A list answers "who was upstream". A chain also answers "did any hop widen its authority", but that is a lot of machinery, and if the first question turns out to be enough, most of it isn't earning its place.

Where a chain belongs in an AuthZEN request is open too. The binding carries the acting client in context.agent and says nothing about the hops above it: it does not rule a chain out of that field and it does not name a place for one, so mandatum keeps the hops under a vendor-prefixed key rather than taking a name inside the binding's namespace. That question is live in openid/authzen#612, a thread on whether context.agent should be trust-anchored when it comes from the validated token — and where the working group corrected an earlier reading of mine. If you have run agent systems in production and think the chain is overkill, I'd rather hear it now.

The specification has an open-questions section that is genuinely open.

I Made Four Authorization Engines Answer the Same Questions

kt — Sat, 12 Sep 2026 07:11:35 +0000

"Which authorization engine should I use" always gets answered with a table. Cedar is analyzable, Rego is expressive, Zanzibar is relationship-based. I could never feel the difference from any of it.

So I gave four of them the same rules and ran every possible request through all four at once.

Live demo: https://0-draft.github.io/authz-playground/
Repo: 0-draft/authz-playground

One question, asked of every engine at every hour of the day. A raised line is allow. Red is where they disagree.

Where ReBAC stops

The page adds one rule at a time. The owner can edit. Folder admins too. Then: only during business hours.

That third one is where ReBAC stops keeping up. check(user, relation, object) has three arguments and none of them holds a clock, so it goes on allowing edits at 3am while the other three deny them. Eight of 72 requests split.

That gap is why OpenFGA later added Conditions. Their announcement names time of day as the example relationships handle badly.

The playground now has that fix as a fifth row: the same Zanzibar model with an OpenFGA condition. The grant stays relational, and one more relation gates it:

define within_hours: [user:* with business_hours]
define editor: (owner or admin from parent) and within_hours

It agrees with the other three on every request. It is still not free. A condition can only hang off a tuple, and business hours are about the request rather than any relationship, so every document needs a placeholder tuple whose only job is to carry the clock. The page rates it possible but forced, not native.

Add a document and Casbin needs its policy table regenerated, while ReBAC just gains a tuple and the model never moves.

What broke

The projections are where I could lie without noticing, so they get checked twice: every engine runs every request and any disagreement is reported, and a separate implementation written from the requirement text alone checks they are not all wrong together.

Both earned their keep.

I gave the ReBAC model viewer: owner or editor, because obviously an editor can read too. The requirements never said that. Disagreements doubled and the comparison was quietly dishonest until the harness flagged it.

Worse, the request enumeration sampled 03:00, 10:00, 14:00 and 22:00, so neither edge of the business-hours window was ever evaluated. I moved one engine's window to 08:00-19:00 to see what would happen. All fourteen tests passed. The suite that existed to protect the comparison could not see the one boundary the whole thing rests on.

The fix was to sample both edges of the window and the hour either side of them, 08, 09, 17 and 18, plus a test that fails if any of those ever drops out of the enumeration. The 08:00-19:00 window now fails at once.

How it runs

No backend. Cedar through its official wasm bindings, Casbin's TypeScript build, and about a hundred lines reimplementing the Zanzibar check algorithm. Rego is OPA itself compiled to js/wasm, so policies are compiled and evaluated live: 8 MB gzipped, loaded lazily, roughly 2 ms per evaluation after the first.

If you try that last one, restrict the builtins. I shipped the default set, which left http.send reachable from pasted Rego. It fired a request from the visitor's browser and deadlocked the Go runtime for the rest of the session.

Have a go at stage 3 and drag across the chart: 0-draft.github.io/authz-playground

Envoy AI Gateway: A Hands-On Tour You Can Run Before Touching Kubernetes

kt — Fri, 14 Aug 2026 11:24:30 +0000

The day we ended up with three places to call an LLM

It started with OpenAI. Then someone pointed out that Bedrock had a cheaper model for one of our workloads, so Bedrock got added. Then a team wanted to use the vLLM instance running on our own GPUs, and that made three.

At that point the codebase looked like this:

Service A called the OpenAI SDK directly
Service B hit bedrock-runtime through boto3
Service C talked to vLLM with a hand-rolled HTTP client
Three API keys lived in three separate Secrets, each with its own rotation procedure
Nobody could answer "how many tokens did each team burn last month?"

Every one of those code paths does the same thing: send text, get text back. And yet we had three SDKs, three retry policies, three auth schemes, three sets of instrumentation. That is not an application problem. It is the absence of a front door. The HTTP world solved this fifteen years ago with API gateways, and the same thing is happening again with LLM traffic.

Envoy AI Gateway is the project filling that gap, and it hit v1.0 GA on June 23, 2026.

This article builds up in order: start with local execution that uses no Kubernetes whatsoever, then look at real schema translation, fallback, MCP, and only at the end move to Kubernetes. Read it top to bottom and you can follow along with your hands on the keyboard.

Every command and every output below came from an actual run. The environment was macOS on arm64, Go 1.26.5, aigw v1.0.0, kind v0.32.0, Envoy Gateway v1.8.1, and Envoy AI Gateway v1.0.0.

0. How to read this

Sections	Content	What you need
1 - 2	What an AI gateway is, and where it sits in the Envoy family	Nothing
3 - 4	Architecture and the CRDs	Nothing
5	Get it running	Go or Docker
6	Watch schema translation happen	Same
7	Fallback and model name virtualization	Same
8	MCP gateway	Same, plus Node.js
9	Move it to Kubernetes	kind / kubectl / helm
10 - 12	Token limits, production features, when to adopt	Nothing

Sections 5 through 8 need neither Kubernetes nor a cloud API key. Everything happens against mock servers running on localhost. If you are short on time, those four sections alone are worth it.

1. What makes an "AI gateway" different from a normal API gateway

"Can't you just put nginx or Envoy in front of the LLM?" is a reasonable instinct, and it is about 70 percent right. The other 30 percent is why a dedicated product exists.

1-1. The same operation has three different shapes

OpenAI, Anthropic, and Bedrock all support "one round trip of chat," and all three want a different path, a different body, and return a different response shape.

OpenAI      POST /v1/chat/completions   {"model":..., "messages":[...], "max_tokens":N}
Anthropic   POST /v1/messages           {"model":..., "messages":[...], "max_tokens":N, "system":"..."}
Bedrock     POST /model/<id>/converse   {"messages":[{"role":..,"content":[{"text":..}]}],
                                         "system":[{"text":..}],
                                         "inferenceConfig":{"maxTokens":N}}

max_tokens becomes inferenceConfig.maxTokens. The system prompt gets pulled out of messages and turned into its own top-level array. A normal reverse proxy can rewrite paths and headers, but restructuring a JSON body is outside its job description.

This is the least glamorous and most valuable thing an AI gateway does. Section 6 shows it happening for real.

1-2. Requests are the wrong unit for billing

For a normal API, "100 requests per second" is a fine limit. For an LLM it barely means anything. A 10-token request and a 100,000-token request both count as 1. The cost differs by four orders of magnitude.

Worse, you do not know the consumption until the response comes back. At request time the output token count does not exist yet. You need a pay-later model: approve first, bill afterward. That is a different premise than any rate limiter was built on.

1-3. Responses stream for a long time

An SSE connection stays open for tens of seconds to several minutes. Default timeouts, buffer sizes, whether a retry is even safe. All of it drifts from HTTP API common sense.

Here are those three problems in one picture. On the left, every application carries its own translation, key management, and instrumentation. On the right, that moves into the gateway.

The reduction in lines matters less than the fact that capabilities disappeared from the application boxes. Getting API keys out of applications is the single biggest operational win.

2. Where this sits in the Envoy family

Three products with confusingly similar names stack on top of each other, so let me sort that out first.

Envoy Proxy carries the data. On its own it needs either a config file or xDS.
Envoy Gateway is the management layer that reads Kubernetes Gateway API resources and turns them into Envoy config.
Envoy AI Gateway adds AI-specific CRDs on top and reaches into xDS through an Envoy Gateway extension point called the extension server.

Envoy AI Gateway does not replace Envoy Gateway. It sits on top. If you already run Envoy Gateway you can bolt this on, but the flip side is that Envoy Gateway concepts become prerequisites.

If you have never touched Gateway API, these four are enough to follow along.

Resource	Role
`GatewayClass`	Which implementation to use. The `ingressClass` equivalent
`Gateway`	Which port to listen on
`HTTPRoute`	How to route
`Backend`	Target hostname and port. An Envoy Gateway specific CRD

Think of it as the standard Kubernetes API group that succeeded Ingress.

3. Architecture

3-1. Control plane and data plane

None of the AI-specific logic lives inside Envoy itself. All of it is pushed out into an external process called ExtProc.

Since that term just appeared for the first time, here is what it means. ExtProc is a stock Envoy HTTP filter that streams request and response headers and bodies to an external process over gRPC, and then applies whatever that external process rewrote back into Envoy. Envoy AI Gateway implements its side in Go. That means no C++ to write, and no coupling to Envoy's own release cycle.

3-2. Why ExtProc is wired in twice

ExtProc sits in two places: in front of the router filter and at the upstream filter position. This is the design decision that pays off the most, so it is worth explaining before you see the effect.

Later in this article you will configure "if the primary provider fails, fall back to a different one." In Envoy, that retry happens after the router filter, at the upstream level. Here is the problem: if the primary is OpenAI and the fallback is Bedrock, then the moment you fail over, both the body translation and the auth header have to change. Translating once, before the router, would be too early.

Splitting it in two exists to preserve an obvious ordering rule: translate only after the destination is known.

3-3. The life of a request

Two things to take away.

First, x-ai-eg-model is not a header the client sets. The gateway extracts it from the model field in the body and attaches it itself. Your routing rules match on that header.

Second, dynamic metadata. This is a named scratch area Envoy keeps per request, used to pass values between filters. ExtProc writes token counts there, and the rate limiter downstream reads them. Section 10 puts it to work.

4. The CRDs worth memorizing

Resource	Role
`AIGatewayRoute`	The unified API as clients see it. Picks a backend by header match. Generates an `HTTPRoute` with the same name
`AIServiceBackend`	One upstream. `schema` declares what format that upstream speaks, which decides the translation target
`BackendSecurityPolicy`	Upstream auth. API keys, plus short-lived tokens fetched from AWS STS, Entra ID, or GCP STS
`Backend`	Hostname and port. An Envoy Gateway resource, not AI-specific
`MCPRoute`	Aggregates MCP servers. Section 8
`QuotaPolicy`	Cumulative token budgets. Section 10
`GatewayConfig`	Per-Gateway ExtProc settings

One thing trips people up here. In v1.0, AIGatewayRoute has no schema field. The input schema is determined by the request path: /v1/chat/completions means OpenAI format, /anthropic/v1/messages means Anthropic format. The only thing you declare is the egress side, AIServiceBackend.schema.

At v1.0 GA, AIGatewayRoute, AIServiceBackend, BackendSecurityPolicy, GatewayConfig, and MCPRoute all became stable at v1beta1. The maintainers state plainly that they will not break these APIs short of a critical security issue. QuotaPolicy is still v1alpha1 and sits outside that promise.

5. Hands-on: run it without Kubernetes

Envoy AI Gateway ships a CLI called aigw that stands up a gateway locally with neither Kubernetes nor Docker, eating exactly the same CRD YAML. It is good for learning and for validating config before you ship it. Linux and macOS only.

5-1. Install aigw

If you have Go, this is the fastest path.

go install github.com/envoyproxy/ai-gateway/cmd/aigw@v1.0.0
export PATH=$PATH:$(go env GOPATH)/bin

Docker works too.

docker run --rm -p 1975:1975 -e OPENAI_API_KEY=$OPENAI_API_KEY \
  envoyproxy/ai-gateway-cli run

Prebuilt binaries are on GitHub Releases. The whole subcommand surface is this:

  version                Show version.
  run [<path>]           Run the AI Gateway locally for given configuration.
  healthcheck            Docker HEALTHCHECK command.
  download-envoy         Download Envoy binary for the Envoy Gateway default version.

On first start, aigw run fetches the Envoy binary for you. On my machine that put Envoy 1.38.1 under ~/.local/share/aigw/, about 97MB. Later runs reuse it.

One gotcha: if you installed via go install, aigw version prints dev because the build info never got stamped in. Use a release binary or the Docker image if you need to confirm the version.

5-2. Stand up a mock LLM to talk to

Burning real OpenAI credit for this would be wasteful, so here is a server that returns an OpenAI-compatible response and nothing else, written against the Python standard library. Zero dependencies.

#!/usr/bin/env python3
"""Minimal OpenAI-compatible mock upstream, for testing aigw locally."""
import json
import time
from http.server import BaseHTTPRequestHandler, HTTPServer


class Handler(BaseHTTPRequestHandler):
    def log_message(self, fmt, *args):
        print("upstream <- %s %s" % (self.command, self.path), flush=True)

    def do_POST(self):
        n = int(self.headers.get("content-length", 0))
        body = json.loads(self.rfile.read(n) or b"{}")
        # observe what the gateway injected on the way in
        print("authorization=%r" % self.headers.get("authorization"), flush=True)
        print("model=%r" % body.get("model"), flush=True)
        self._json({
            "id": "chatcmpl-mock",
            "object": "chat.completion",
            "created": int(time.time()),
            "model": body.get("model", "mock-gpt"),
            "choices": [{"index": 0, "finish_reason": "stop",
                         "message": {"role": "assistant", "content": "I'll be back."}}],
            "usage": {"prompt_tokens": 11, "completion_tokens": 5, "total_tokens": 16},
        })

    def _json(self, obj, code=200):
        raw = json.dumps(obj).encode()
        self.send_response(code)
        self.send_header("content-type", "application/json")
        self.send_header("content-length", str(len(raw)))
        self.end_headers()
        self.wfile.write(raw)


HTTPServer(("127.0.0.1", 11434), Handler).serve_forever()

Save it as mockllm.py and start it. Port 11434 matches Ollama's default, so if you already run Ollama you can point at that instead of the mock.

python3 mockllm.py &

5-3. Start it with no config file

aigw run generates its own config from environment variables. If any of OPENAI_API_KEY, AZURE_OPENAI_API_KEY, or ANTHROPIC_API_KEY is set, no config file is needed. Override OPENAI_BASE_URL to aim it at the mock or at Ollama.

OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_API_KEY=unused aigw run

AI Gateway External Processor is ready
Envoy AI Gateway listening on http://localhost:1975 (admin http://localhost:52816) after 6.3s

First start took 6.3 seconds including the Envoy download. Later starts took 1.4 seconds.

The admin port in that log line is Envoy's own admin port, and it changes on every start. The aigw admin endpoint you will use shortly is a different thing, fixed at 1064.

5-4. Send a request

curl -s -H "Content-Type: application/json" -XPOST \
  http://localhost:1975/v1/chat/completions \
  -d '{"model":"mock-gpt","messages":[{"role":"user","content":"Say this is a test!"}]}'

{"id": "chatcmpl-mock", "object": "chat.completion", "model": "mock-gpt", "choices": [{"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": "I'll be back."}}], "usage": {"prompt_tokens": 11, "completion_tokens": 5, "total_tokens": 16}}

That worked. The interesting part is on the mock side.

authorization='Bearer unused'
model='mock-gpt'
upstream <- POST /v1/chat/completions

The curl command sent no Authorization header at all, yet the upstream received Bearer unused. The gateway injected OPENAI_API_KEY. That is "get keys out of the application" made concrete, and on Kubernetes BackendSecurityPolicy fills the same role.

5-5. Tokens are already being counted

The aigw admin port at 1064 serves Prometheus-format metrics.

curl -s http://localhost:1064/health
curl -s http://localhost:1064/metrics | grep -E 'gen_ai.*(_sum|_count)\{'

OK
gen_ai_client_token_usage_sum{gen_ai_operation_name="chat",gen_ai_provider_name="openai",gen_ai_request_model="mock-gpt",gen_ai_token_type="input"} 11
gen_ai_client_token_usage_sum{...,gen_ai_token_type="output"} 5
gen_ai_server_request_duration_seconds_sum{...} 0.010359625

The prompt_tokens: 11 and completion_tokens: 5 the mock returned landed straight in the metrics. Names and labels follow the OpenTelemetry GenAI semantic conventions, so dashboards can stay vendor neutral.

Note that gen_ai_client_token_usage is exported as a histogram, not a counter. Use _sum for total tokens and _count for request counts.

Metric	What it tells you
`gen_ai.client.token.usage`	Token consumption. `gen_ai.token.type` splits input from output
`gen_ai.server.request.duration`	End-to-end request latency
`gen_ai.server.time_to_first_token`	Time to the first token. Perceived responsiveness
`gen_ai.server.time_per_output_token`	Inter-token latency. Generation speed

For LLMs, how fast something feels is usually decided by time to first token rather than total latency, so getting that out of the box matters.

6. Hands-on: watch schema translation happen

Section 1 claimed that restructuring JSON is the least glamorous and most valuable thing here. Time to see it.

The setup: stand up a mock that expects requests in Bedrock Converse format, then send it OpenAI format from the client. Print the raw body the upstream received and the gateway's work is right there on screen.

6-1. A mock that speaks Bedrock

#!/usr/bin/env python3
"""AWS Bedrock Converse format mock upstream.
   Prints whatever the gateway translated the request into."""
import json
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer


class Handler(BaseHTTPRequestHandler):
    def log_message(self, fmt, *args):
        pass

    def do_POST(self):
        n = int(self.headers.get("content-length", 0))
        raw = self.rfile.read(n)
        print("=== path the upstream received ===", flush=True)
        print(self.path, flush=True)
        print("=== body the upstream received ===", flush=True)
        print(json.dumps(json.loads(raw or b"{}"), indent=2), flush=True)

        # respond in Bedrock Converse format
        resp = {
            "output": {"message": {"role": "assistant",
                                   "content": [{"text": "I'll be back."}]}},
            "stopReason": "end_turn",
            "usage": {"inputTokens": 11, "outputTokens": 5, "totalTokens": 16},
        }
        body = json.dumps(resp).encode()
        self.send_response(200)
        self.send_header("content-type", "application/json")
        self.send_header("content-length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


HTTPServer(("127.0.0.1", 11600), Handler).serve_forever()

6-2. Set the egress schema to AWSBedrock

The config is short. Set schema.name on the AIServiceBackend to AWSBedrock and that is it.

apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIServiceBackend
metadata:
  name: bedrock-mock
  namespace: default
spec:
  schema:
    name: AWSBedrock
  backendRef:
    name: bedrock-mock
    kind: Backend
    group: gateway.envoyproxy.io
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
  name: bedrock-mock
  namespace: default
spec:
  endpoints:
    - fqdn:
        hostname: localhost
        port: 11600

Add the same GatewayClass, Gateway, and AIGatewayRoute used in section 7, then start it with aigw run translate.yaml.

6-3. Send OpenAI format

curl -s -XPOST http://localhost:1975/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"claude-mock","max_tokens":100,
       "messages":[{"role":"system","content":"You are terse."},
                   {"role":"user","content":"hi"}]}'

This is what the upstream received.

=== path the upstream received ===
/model/claude-mock/converse
=== body the upstream received ===
{
  "inferenceConfig": {
    "maxTokens": 100
  },
  "messages": [
    {
      "content": [
        {
          "text": "hi"
        }
      ],
      "role": "user"
    }
  ],
  "system": [
    {
      "text": "You are terse."
    }
  ]
}

Three separate things happened.

The third one, peeling the system prompt out of the messages array and relocating it into a standalone system array, is exactly the kind of thing you cannot express in reverse proxy configuration.

6-4. The return trip gets translated too

The mock replies in Bedrock format. This is what reached the client.

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": { "content": "I'll be back.", "role": "assistant" }
        }
    ],
    "model": "claude-mock",
    "object": "chat.completion",
    "usage": { "prompt_tokens": 11, "completion_tokens": 5, "total_tokens": 16 }
}

output.message.content[0].text became choices[0].message.content, and usage.inputTokens became usage.prompt_tokens. An OpenAI SDK will consume this unmodified.

6-5. Where I got stuck: `Anthropic` is not a valid translation target

My first attempt wrote the mock in Anthropic Messages format and set schema.name: Anthropic. It returned 500, with this in the log.

level=ERROR msg="error processing request message"
  error="... failed to create translator for backend ...: unsupported API schema: backend={Anthropic  v1}"

Digging into it, the cause was not what I assumed. It is not that the translation is impossible. That combination simply is not registered in a switch. The error comes from here, in internal/endpointspec/endpointspec.go.

// ChatCompletionsEndpointSpec.GetTranslator
switch schema.Name {
case filterapi.APISchemaOpenAI:        ...
case filterapi.APISchemaAWSBedrock:    ...
case filterapi.APISchemaAWSAnthropic:  ...
case filterapi.APISchemaAzureOpenAI:   ...
case filterapi.APISchemaGCPVertexAI:   ...
case filterapi.APISchemaGCPAnthropic:  ...
default:
    return nil, fmt.Errorf("unsupported API schema: backend=%s", schema)
}

There is no case for APISchemaAnthropic. That is the whole story.

The body translation from OpenAI format to Anthropic Messages format exists and works today. Both openai_awsanthropic.go and openai_gcpanthropic.go call the same buildAnthropicParams(openAIReq, ...), and what that returns is *anthropic.MessageNewParams, the struct from Anthropic's official Go SDK. What is missing is the branch for "when the destination is api.anthropic.com," which would differ only by setting the path to /v1/messages and skipping the anthropic_version injection.

By contrast, the switch for requests entering through /anthropic/v1/messages has all five filled in.

// MessagesEndpointSpec.GetTranslator
case APISchemaGCPAnthropic / APISchemaAWSAnthropic / APISchemaAnthropic
   / APISchemaOpenAI / APISchemaAWSBedrock

You can accept Anthropic format and emit to an OpenAI backend. Only the reverse direction has a hole in it.

In practice this is what it means:

Where your Claude lives	Usable from an OpenAI-format client?
On Bedrock (`AWSAnthropic`)	Yes
On Vertex AI (`GCPAnthropic`)	Yes
Direct contract with Anthropic (`Anthropic`)	No. You have to receive on `/anthropic/v1/messages`

The most straightforward setup is the least convenient one. This is a v1.0.0 observation and a later version may well close the gap.

Also worth clearing up: AWSAnthropic and Anthropic are not two routes to the same place. They are the same model bought from different vendors. api.anthropic.com does not accept IAM credentials, and Bedrock does not accept an Anthropic API key. Which one you write is not a preference, it is dictated by where your Claude actually lives.

	`Anthropic`	`AWSAnthropic`	`AWSBedrock`
Destination	api.anthropic.com	Bedrock	Bedrock
Path	`/v1/messages`	`/model/<id>/invoke`	`/model/<id>/converse`
Body	Anthropic native	Anthropic native plus `anthropic_version`	Converse's shared format
Auth	`AnthropicAPIKey`	`AWSCredentials`	`AWSCredentials`

AWSAnthropic and AWSBedrock both target Bedrock, but the former uses InvokeModel and drops the Anthropic body into a Bedrock envelope untouched, while the latter repacks everything into Converse, the format shared across all Bedrock models. Pick Converse if you want to swap between Claude and Llama with one request shape. Pick InvokeModel if you want Anthropic-specific structures to pass through intact.

So schema is decided by three things, not one: the shape of the upstream API, which vendor you bought from, and whether that pairing with your ingress path is implemented. These are the eight values defined at v1.0.0.

OpenAI  AzureOpenAI  AWSBedrock  AWSAnthropic
Anthropic  GCPVertexAI  GCPAnthropic  Cohere

7. Hands-on: fallback and model name virtualization

What you actually want in production is "fail over to another provider when the primary dies" and "keep the model name fixed as far as the application is concerned." Here is both.

7-1. Stand up an upstream that fails

#!/usr/bin/env python3
"""An upstream that always returns 503, for testing fallback."""
from http.server import BaseHTTPRequestHandler, HTTPServer


class Handler(BaseHTTPRequestHandler):
    def log_message(self, fmt, *args):
        print("primary(broken) <- %s %s" % (self.command, self.path), flush=True)

    def do_POST(self):
        self.rfile.read(int(self.headers.get("content-length", 0)))
        body = b'{"error":{"message":"upstream is down"}}'
        self.send_response(503)
        self.send_header("content-type", "application/json")
        self.send_header("content-length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


HTTPServer(("127.0.0.1", 11500), Handler).serve_forever()

Port 11500 is the broken primary. Port 11434 from section 5 is the healthy fallback.

7-2. Write the config

Save this as aigw-config.yaml. It is exactly the same CRD YAML you would use on Kubernetes, and you could kubectl apply it as is.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: aigw-run
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: aigw-run
  namespace: default
spec:
  gatewayClassName: aigw-run
  listeners:
    - name: http
      protocol: HTTP
      port: 1975
---
apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIGatewayRoute
metadata:
  name: aigw-run
  namespace: default
spec:
  parentRefs:
    - name: aigw-run
      kind: Gateway
      group: gateway.networking.k8s.io
  rules:
    # the client only ever knows the invented model name "team-chat"
    - matches:
        - headers:
            - type: Exact
              name: x-ai-eg-model
              value: team-chat
      backendRefs:
        - name: primary
          priority: 0
          modelNameOverride: broken-model
        - name: secondary
          priority: 1
          modelNameOverride: mock-gpt
  llmRequestCosts:
    - metadataKey: llm_input_token
      type: InputToken
    - metadataKey: llm_output_token
      type: OutputToken
---
apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIServiceBackend
metadata:
  name: primary
  namespace: default
spec:
  schema:
    name: OpenAI
  backendRef:
    name: primary
    kind: Backend
    group: gateway.envoyproxy.io
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
  name: primary
  namespace: default
spec:
  endpoints:
    - fqdn:
        hostname: localhost
        port: 11500
---
apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIServiceBackend
metadata:
  name: secondary
  namespace: default
spec:
  schema:
    name: OpenAI
  backendRef:
    name: secondary
    kind: Backend
    group: gateway.envoyproxy.io
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
  name: secondary
  namespace: default
spec:
  endpoints:
    - fqdn:
        hostname: localhost
        port: 11434
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: fallback
  namespace: default
spec:
  targetRefs:
    # an HTTPRoute is generated with the same name as the AIGatewayRoute, so aim at that
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: aigw-run
  retry:
    numRetries: 2
    # only one attempt per priority, so it drops to the next one immediately
    numAttemptsPerPriority: 1
    perRetry:
      backOff:
        baseInterval: 100ms
        maxInterval: 1s
      timeout: 30s
    retryOn:
      httpStatusCodes:
        - 503
      triggers:
        - connect-failure
        - retriable-status-codes

Three parts are worth reading closely.

priority is lowest-wins, so 0 is the intended target and anything from 1 up is a fallback.

modelNameOverride rewrites the team-chat the client sent into a different name right before it goes upstream. The same Claude Sonnet is called anthropic.claude-sonnet-4-20250514-v1:0 on Bedrock and claude-sonnet-4@20250514 on Vertex AI. This is the feature that keeps that difference from leaking into your application.

BackendTrafficPolicy targets not the AIGatewayRoute but the HTTPRoute generated from it, which carries the same name. Section 9 shows that generated object for real.

7-3. Run it

aigw run aigw-config.yaml

curl -s -w '\nHTTP %{http_code} in %{time_total}s\n' \
  -H "Content-Type: application/json" -XPOST \
  http://localhost:1975/v1/chat/completions \
  -d '{"model":"team-chat","messages":[{"role":"user","content":"hi"}]}'

{"id": "chatcmpl-mock", ..., "message": {"role": "assistant", "content": "I'll be back."}}
HTTP 200 in 0.113045s

The client got a 200. The logs on both upstreams show what happened behind it.

=== primary(broken) ===
primary(broken) <- POST /v1/chat/completions

=== secondary ===
model='mock-gpt'
upstream <- POST /v1/chat/completions

One attempt against the primary, a 503, then a switch to the secondary. And the model name the secondary received is mock-gpt, not team-chat, so modelNameOverride is doing its job. Of the 113ms total, 100ms is the baseInterval backoff we configured.

7-4. The metrics keep a record of the virtualization

gen_ai_client_token_usage_sum{gen_ai_original_model="team-chat",gen_ai_request_model="mock-gpt",gen_ai_response_model="mock-gpt",gen_ai_token_type="input"} 11

gen_ai_original_model and gen_ai_request_model sit side by side as separate labels. You can trace both what the application asked for and which model actually served it. Without that, investigating the blast radius of a provider migration is hopeless.

7-5. Send a model that is not in any route

curl -s -w '\nHTTP %{http_code}\n' -XPOST http://localhost:1975/v1/chat/completions \
  -H 'content-type: application/json' -d '{"model":"nope","messages":[]}'

No matching route found. It is likely because the model specified in your request is not configured in the Gateway.
HTTP 404

Models are allowlisted. Anything not written into an AIGatewayRoute does not get through. That prevents someone accidentally hammering an expensive model, at the cost of needing a config change to adopt a new one. Build that into your operational process.

7-6. Where I got stuck: forgetting `retriable-status-codes`

My first retryOn looked like this, and fallback silently did nothing.

    retryOn:
      httpStatusCodes:
        - 503
      triggers:
        - connect-failure
        - reset

It says httpStatusCodes: [503] right there, and yet a 503 does not trigger a retry. This is Envoy behavior: unless triggers contains retriable-status-codes, the httpStatusCodes list is never evaluated at all. httpStatusCodes defines which codes count as retriable, and "retry on retriable codes" is a separate trigger you have to switch on.

This is Envoy in general rather than anything specific to Envoy AI Gateway, but it is the easiest trap to fall into when wiring up fallback.

8. Hands-on: use it as an MCP gateway

Since v0.4, Envoy AI Gateway also works as a gateway for the Model Context Protocol. It looks like a separate topic from LLM traffic, but the shape of the problem is identical. Connect an agent to five MCP servers and you have five sets of credentials scattered around and no record of which tools got called.

Name collisions between tools are avoided with a prefix derived from the backend name.

8-1. Try it against a public MCP server that needs no auth

You can pass config inline with --mcp-json. The format is the same mcpServers shape Claude Desktop and VS Code use.

aigw run --mcp-json '{"mcpServers":{"deepwiki":{"type":"http","url":"https://mcp.deepwiki.com/mcp"}}}'

Pull the tool list with the MCP Inspector in CLI mode.

npx --yes @modelcontextprotocol/inspector@0.16.8 \
  --cli http://localhost:1975/mcp --method tools/list

"name": "deepwiki__ask_question",
"name": "deepwiki__read_wiki_contents",
"name": "deepwiki__read_wiki_structure",

Upstream, DeepWiki publishes these as ask_question and so on. Through the gateway they come back with deepwiki__ prepended. Add more backends and the names still will not collide.

Now call one.

npx --yes @modelcontextprotocol/inspector@0.16.8 \
  --cli http://localhost:1975/mcp \
  --method tools/call \
  --tool-name deepwiki__read_wiki_structure \
  --tool-arg repoName=envoyproxy/ai-gateway

Available pages for envoyproxy/ai-gateway:
- 1 Overview
  - 1.1 Key Concepts
  - 1.2 Architecture Overview
- 2 System Architecture
...

The prefix got stripped and the call landed on the right backend.

8-2. Narrow the tool list

--mcp-config reads the same thing from a file. Headers support environment variable interpolation with ${VAR}.

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/readonly",
      "headers": {
        "Authorization": "Bearer ${GITHUB_ACCESS_TOKEN}"
      },
      "includeTools": ["issue_read", "list_issues"]
    }
  }
}

includeTools is the useful one. You get to decide, at the gateway, which tools an agent can even see. The GitHub MCP server has write operations too, but here only two read operations are exposed. As a defense against prompt injection, simply not showing an agent the dangerous tools has an unusually good ratio of effect to implementation cost.

On Kubernetes the same thing goes in an MCPRoute.

apiVersion: aigateway.envoyproxy.io/v1beta1
kind: MCPRoute
metadata:
  name: mcp-route
  namespace: default
spec:
  parentRefs:
    - name: aigw-run
      kind: Gateway
      group: gateway.networking.k8s.io
  path: "/mcp"
  backendRefs:
    - name: github
      kind: Backend
      group: gateway.envoyproxy.io
      path: "/mcp/x/issues/readonly"
      toolSelector:
        includeRegex:
          - .*issues?.*
      securityPolicy:
        apiKey:
          secretRef:
            name: github-token

toolSelector takes exactly one of include or includeRegex. You cannot set both. Omit it entirely and every tool is exposed.

Going further, securityPolicy.oauth terminates the MCP spec's OAuth flow at the gateway and lets you evaluate JWT claims and scopes with CEL expressions to authorize individual tools.

9. Move it to Kubernetes

Once it makes sense locally, take it to a cluster. The YAML from section 7 carries over almost unchanged.

9-1. Prerequisites

You need Kubernetes 1.32 or newer. That is the requirement most likely to disqualify an existing cluster. Beyond that, kubectl, helm, and curl.

Locally, kind is fine.

kind create cluster --name aigw

Install Envoy Gateway with the AI Gateway values applied.

helm upgrade -i eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.8.1 \
  --namespace envoy-gateway-system \
  --create-namespace \
  -f https://raw.githubusercontent.com/envoyproxy/ai-gateway/main/manifests/envoy-gateway-values.yaml

kubectl wait --timeout=5m -n envoy-gateway-system \
  deployment/envoy-gateway --for=condition=Available

If Envoy Gateway is already installed, the extension server will not be enabled without these values. The project recommends reinstalling from a clean slate.

9-2. AI Gateway itself

The CRDs and the controller ship as separate charts.

helm upgrade -i aieg-crd oci://docker.io/envoyproxy/ai-gateway-crds-helm \
  --version v1.0.0 --namespace envoy-ai-gateway-system --create-namespace

helm upgrade -i aieg oci://docker.io/envoyproxy/ai-gateway-helm \
  --version v1.0.0 --namespace envoy-ai-gateway-system --create-namespace

kubectl wait --timeout=5m -n envoy-ai-gateway-system \
  deployment/ai-gateway-controller --for=condition=Available

Splitting the CRDs into their own chart started in v1.0, so upgrading from anything older requires a transfer of ownership.

helm upgrade -i aieg-crd oci://docker.io/envoyproxy/ai-gateway-crds-helm \
  --version v1.0.0 --namespace envoy-ai-gateway-system --take-ownership

On a kind node with 2 vCPU and 4GB, everything up to this point took a little over five minutes.

NAMESPACE                 NAME                                     READY   STATUS
envoy-ai-gateway-system   ai-gateway-controller-7d76dd5b85-vqgsf   1/1     Running
envoy-gateway-system      envoy-gateway-f97c95b-5s2q9              1/1     Running

9-3. Get traffic flowing

The official sample works as is.

kubectl apply -f https://raw.githubusercontent.com/envoyproxy/ai-gateway/main/examples/basic/basic.yaml

kubectl wait pods --timeout=4m \
  -l gateway.envoyproxy.io/owning-gateway-name=envoy-ai-gateway-basic \
  -n envoy-gateway-system --for=condition=Ready

export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system \
  --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=envoy-ai-gateway-basic \
  -o jsonpath='{.items[0].metadata.name}')

kubectl port-forward -n envoy-gateway-system svc/$ENVOY_SERVICE 8080:80

curl -s -H "Content-Type: application/json" \
  -d '{"model":"some-cool-self-hosted-model","messages":[{"role":"system","content":"Hi."}]}' \
  http://localhost:8080/v1/chat/completions

{"choices": [{"index": 0,"message": {"role": "assistant","content": "I'm king of the world!"},"finish_reason": "stop"}],"usage": {"prompt_tokens": 1,"completion_tokens": 100,"total_tokens": 300}}

Traffic flows. As a side note, the official docs show the expected response as "I'll be back.", but the v1.0.0 test upstream image actually returns "I'm king of the world!". It is a hardcoded string either way, so it does not matter.

9-4. Look at what got generated

This is the part most worth inspecting on the Kubernetes side. Applying a single AIGatewayRoute grew several resources behind your back.

kubectl get httproute,httproutefilter -A

NAMESPACE   NAME                                                    AGE
default     httproute.../envoy-ai-gateway-basic                     5m
default     httproutefilter.../ai-eg-host-rewrite-envoy-ai-gateway-basic               5m
default     httproutefilter.../ai-eg-route-not-found-response-envoy-ai-gateway-basic   5m

There is an HTTPRoute with the same name as the AIGatewayRoute. That is what section 7 pointed BackendTrafficPolicy at. The contents tell you more.

spec:
  rules:
  - backendRefs:
    - group: gateway.envoyproxy.io
      kind: Backend
      name: envoy-ai-gateway-basic-testupstream
      weight: 1
    filters:
    - extensionRef:
        kind: HTTPRouteFilter
        name: ai-eg-host-rewrite-envoy-ai-gateway-basic
      type: ExtensionRef
    matches:
    - headers:
      - name: x-ai-eg-model
        type: Exact
        value: some-cool-self-hosted-model
      path:
        type: PathPrefix
        value: /
    timeouts:
      request: 60s
  - filters:
    - extensionRef:
        kind: HTTPRouteFilter
        name: ai-eg-route-not-found-response-envoy-ai-gateway-basic
      type: ExtensionRef
    matches:
    - path:
        type: PathPrefix
        value: /
    name: route-not-found

Below the rule I wrote, a catch-all rule named route-not-found has been appended automatically. That is the origin of the 404 message from section 7-5.

Because of that insertion, a single AIGatewayRoute can hold at most 15 rules. Gateway API caps HTTPRoute.spec.rules at 16, and one slot is reserved for the catch-all. Need more than that and you split the AIGatewayRoute and attach both to the same Gateway.

You can also see that the default request timeout is 60 seconds. That is short for long generations, so you will end up raising it on the AIGatewayRoute.

9-5. ExtProc arrives as a native sidecar

Look at the Gateway Pod and the container layout is slightly unusual.

kubectl get pod -n envoy-gateway-system <gateway-pod> \
  -o jsonpath='{range .spec.initContainers[*]}INIT {.name} {.restartPolicy}{"\n"}{end}'

INIT ai-gateway-extproc Always

ExtProc is not injected into the normal containers list. It goes into initContainers with restartPolicy: Always, making it a native sidecar. That is the Kubernetes 1.29 feature where, unlike a conventional sidecar, startup ordering is guaranteed and the container comes up before the main one. If ExtProc is not there the instant Envoy starts, every request returns 500, so this shape is required.

containers:      envoy (envoyproxy/envoy:distroless-v1.38.1)
                 shutdown-manager (envoyproxy/gateway:v1.8.1)
initContainers:  ai-gateway-extproc (envoyproxy/ai-gateway-extproc:v1.0.0)  restartPolicy: Always

9-6. Connect to the real OpenAI

curl -O https://raw.githubusercontent.com/envoyproxy/ai-gateway/main/examples/basic/openai.yaml

Replace apiKey: OPENAI_API_KEY with your own key and apply. Two things matter.

apiVersion: aigateway.envoyproxy.io/v1beta1
kind: BackendSecurityPolicy
metadata:
  name: envoy-ai-gateway-basic-openai-apikey
  namespace: default
spec:
  targetRefs:
    - group: aigateway.envoyproxy.io
      kind: AIServiceBackend
      name: envoy-ai-gateway-basic-openai
  type: APIKey
  apiKey:
    secretRef:
      name: envoy-ai-gateway-basic-openai-apikey
---
apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: envoy-ai-gateway-basic-openai-tls
  namespace: default
spec:
  targetRefs:
    - group: "gateway.envoyproxy.io"
      kind: Backend
      name: envoy-ai-gateway-basic-openai
  validation:
    wellKnownCACertificates: "System"
    hostname: api.openai.com

BackendSecurityPolicy is the Kubernetes version of the key injection from section 5. Update the Secret and it takes effect within seconds, with no Pod restart.

BackendTLSPolicy is mandatory for any external HTTPS upstream. Forget it and Envoy tries to speak plaintext to port 443 and fails.

9-7. Raise the buffer limit

basic.yaml contains one unglamorous setting you will always need in production.

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: client-buffer-limit
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: envoy-ai-gateway-basic
  connection:
    bufferLimit: 50Mi

Envoy Gateway's default buffer limit is 32KiB, which is nowhere near enough for LLM requests. Base64 an image into the body or send a long conversation history and it gets rejected. The sample raises it to 50MiB. It is easy to forget, so put it in from the start.

9-8. When you do not want API keys in Secrets

BackendSecurityPolicy supports automatic short-lived credential retrieval for the major clouds.

Provider	Mechanism
AWS Bedrock	OIDC federated with AWS STS to issue temporary credentials
Azure OpenAI	Short-lived access tokens from Entra ID
GCP Vertex AI	Google STS via Workload Identity Federation
OpenAI and others	API key stored in a Secret

Providers without an OIDC story, OpenAI among them, cannot escape key management. But you can at least stop distributing those keys per application. Confine them to the gateway and both the blast radius of a rotation and the number of audit points collapse to one.

10. Token-based rate limiting and quotas

Time to look at the pay-later model from section 1-2 in real YAML. This part needs Redis, so it is not something aigw run can demonstrate.

10-1. How it works

Two ideas carry this.

Set the request-time cost to zero. With cost.request.number: 0 the gateway checks that budget remains without spending any. The real consumption is charged after the response arrives.

Dynamic metadata is the handoff point. ExtProc writes into a namespace called io.envoy.ai_gateway, and BackendTrafficPolicy reads from it. That namespace is fixed and cannot be changed. Typo it and rate limiting quietly stops working.

10-2. Configuration

First, declare on the AIGatewayRoute what to pull out of the response and which key to store it under.

  llmRequestCosts:
    - metadataKey: llm_input_token
      type: InputToken
    - metadataKey: llm_cached_input_token
      type: CachedInputToken
    - metadataKey: llm_output_token
      type: OutputToken
    - metadataKey: llm_total_token
      type: TotalToken

Then consume those keys from a BackendTrafficPolicy.

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: token-ratelimit
  namespace: default
spec:
  targetRefs:
    - name: envoy-ai-gateway-token-ratelimit
      kind: Gateway
      group: gateway.networking.k8s.io
  rateLimit:
    type: Global
    global:
      rules:
        - clientSelectors:
            - headers:
                # a separate budget per distinct x-tenant-id value
                - name: x-tenant-id
                  type: Distinct
          limit:
            requests: 10000
            unit: Hour
          cost:
            request:
              from: Number
              number: 0
            response:
              from: Metadata
              metadata:
                namespace: io.envoy.ai_gateway
                key: llm_input_token

The field is named limit.requests, but because cost comes from metadata this is effectively "10,000 tokens per hour." To give input, output, and total their own budgets, repeat the same rule shape with a different key.

type: Distinct means one bucket per header value, which is how you get per-tenant or per-user limits in a single line. Swap in x-ai-eg-model if you want per-model limits instead.

10-3. Rate limiting versus quotas

There is a separate CRD called QuotaPolicy that is easy to confuse with this. The API landed in v0.6 and it only started actually enforcing anything in v0.7. It is still v1alpha1 and outside the v1.0 stability guarantee.

	Usage-based rate limiting	QuotaPolicy
What it controls	Rate. Consumption pace per unit time	Cumulative budget. Total spend over a window
Typical use	Stop a runaway batch from crowding everyone out	"This team gets one million tokens a month"
Where you write it	`BackendTrafficPolicy`	`QuotaPolicy`
What it attaches to	Gateway or HTTPRoute	`AIServiceBackend`

QuotaPolicy can hold a budget per model, and CEL lets you weight token types differently.

perModelQuotas:
  - modelName: gpt-4
    quota:
      # cached input counts as one tenth, output counts sixfold
      costExpression: "input_tokens + cached_input_tokens / 10u + output_tokens * 6u"
      defaultBucket:
        limit: 10000
        duration: "1h"

One trap. The modelName in perModelQuotas must match the modelNameOverride on the AIGatewayRoute, or the quota is silently ignored. No error, no warning. If you set modelNameOverride: mock-gpt in section 7, write mock-gpt on the quota side too.

11. Features that matter in production

An inventory, including things this article has not touched.

Feature	Why you want it	What implements it
Schema translation	Clients only ever speak OpenAI format	Request path plus `AIServiceBackend.schema`
Provider fallback	Automatic evacuation to another provider during an outage	`priority` plus `BackendTrafficPolicy.retry`
Model name virtualization	Naming differences between providers never reach the app	`modelNameOverride`
Upstream auth	Keys leave the application. Short-lived tokens on the clouds	`BackendSecurityPolicy`
Token limits and quotas	Stop runaways on both rate and cumulative spend	`BackendTrafficPolicy` / `QuotaPolicy`
Observability	Metrics, traces, and logs following the OTel GenAI conventions	Prometheus / OTLP
MCP gateway	Aggregating MCP servers, filtering tools, OAuth	`MCPRoute`
InferencePool integration	Smarter routing to self-hosted vLLM on your own GPUs	Gateway API Inference Extension

The set of supported endpoints has grown a lot since v0.1.

POST /v1/chat/completions             POST /v1/embeddings
POST /v1/completions                  POST /v1/images/generations
POST /v1/responses                    POST /v1/audio/transcriptions
POST /v1/responses/input_tokens       POST /v1/audio/translations
POST /anthropic/v1/messages           POST /cohere/v2/rerank
POST /anthropic/v1/messages/count_tokens
GET  /v1/models

Because /anthropic/v1/messages is there, an application written against the Anthropic SDK can go through the gateway unchanged. The ingress is not locked to OpenAI format.

InferencePool deserves a mention. If you own GPUs and run a fleet of vLLM replicas, plain round-robin is close to the worst possible choice. Sending a request to the node whose KV cache already holds the conversation is fast, and round-robin will happily throw it at a node that misses. The Endpoint Picker from Gateway API Inference Extension routes based on which replica currently holds the conversation. Envoy AI Gateway has supported Inference Extension v1.0 since v0.4, and an AIGatewayRoute can reference an InferencePool. If you self-host, look into this.

12. Deciding whether to adopt it

Worth it

With two or more providers, translation and fallback alone pay for the thing. If you need to attribute spend, instrumenting every application by hand instead is not realistic. And if you already run Envoy Gateway, the marginal cost is mostly the operational knowledge.

Be careful

With one provider and one application, using the SDK directly is faster. A gateway is one more hop and pure liability.

If you are not on Kubernetes, aigw run works standalone, but rate limiting and quotas assume Redis and Envoy Gateway's rate limit service. The full feature set is Kubernetes-only.

If your cluster is below 1.32, this becomes a cluster upgrade conversation first.

Know the failure modes up front

Failure mode	Symptom	Fix
Buffer limit left at 32KiB	Long prompts or image payloads get rejected	Raise `bufferLimit` via `ClientTrafficPolicy`
Missing `retriable-status-codes`	Fallback silently does nothing	Always include it in `triggers`
Unimplemented `schema` pairing	500 with `unsupported API schema`	Check the ingress path and egress `schema` as a pair
`modelNameOverride` and `QuotaPolicy.modelName` disagree	The quota is ignored with no error	Make the names match
Typo in the dynamic metadata namespace	Rate limiting quietly stops working	`io.envoy.ai_gateway` is fixed
Default 60 second timeout	Long generations get cut off midway	Raise `timeouts` on the `AIGatewayRoute`
Model missing from any route	404	Fold new model adoption into your process
Gateway becomes a SPOF	All LLM traffic stops	Multiple replicas, PDB, regional redundancy

That last one is not something to wave away. Routing every application's LLM calls through one place means that when it goes down, everything goes down. Whether the observability and governance you get back is worth that depends on the size of your organization.

Version notes

v0.6 shipped two breaking changes. AIGatewayRoute.spec.filterConfig was removed and moved to GatewayConfig, and the version-as-prefix behavior on VersionedAPISchema was dropped in favor of prefix. Copying YAML out of older blog posts will bite you.

Wrapping up

The thing I most want to leave you with is that you can try all of this with aigw run before you ever stand up Kubernetes.

Sections 5 through 8 of this article did not even use Docker. A machine with Go and the Python standard library was enough to watch key injection, schema translation, fallback, model name virtualization, and MCP aggregation all happen for real. And because the config YAML is byte-for-byte the same CRDs Kubernetes uses, it carries straight over to a cluster.

The difference in how fast things click is substantial. Write a mock server, run aigw run against it, and go from there.

Let's Play Shogi: I Turned My GitHub Profile README Into a Playable Board

kt — Thu, 13 Aug 2026 11:18:30 +0000

Update (2026-10-02): the board has moved out of my profile README into its own repository, 0-draft/shogi. Everything below still describes how it works; only the address changed.

Update (2026-11-08): the board is retired. In the months it was up, nobody but me played a move, so the repository is frozen and will be archived; the code stays readable at 0-draft/shogi, but new moves no longer do anything.

Introduction

There is a shogi board on my GitHub profile. Click a piece and you play a move.

https://github.com/kanywst

Your opponent is not me. It is whoever wanders by next. Someone plays for Black, someone else plays for White, and a game slowly happens between strangers.

This started because I could not decide what to put on my profile README. A skill list, GitHub Stats badges, the snake eating my contribution graph. I have seen all of them, and I look at all of them exactly once. I wanted something a visitor could actually do.

If you have never played shogi

Two things from the game matter for the rest of this post.

Squares are named by file and rank, so 7g is one specific square, and 7g7f means the piece on 7g moves to 7f. And unlike chess, a captured piece does not leave the game: it becomes yours, and on a later turn you can drop it back onto almost any empty square instead of moving something. That second rule is what makes the number of possible moves explode, which turns out to decide the whole interface.

A profile README is just a repository

GitHub has a rule where a repository named after your username gets its README.md rendered at the top of your profile page. For me that is kanywst/kanywst.

It is an ordinary repository, so GitHub Actions runs in it. If an Action rewrites README.md and commits, the profile page changes with it.

kanywst/kanywst (an ordinary repository)
  └─ README.md ──────> rendered at github.com/kanywst
       ▲
       └── GitHub Actions can rewrite it

No JavaScript runs in a README

GitHub sanitizes the README before rendering it. You can check exactly what happens through the markdown API:

gh api /markdown -f mode=gfm \
  -f text='<div style="color:red" onclick="x()">A</div><script>alert(1)</script>'

<div>A</div>&lt;script&gt;alert(1)&lt;/script&gt;

The style and onclick attributes are gone, and the script tag comes back escaped, so it renders as visible text instead of running. "Click this and something happens" is not available in the usual way.

What survives is roughly links, images, and tables.

So the only action a visitor can take is following a link, and the only way to receive input is a URL.

An Issue can be pre-filled from a URL

GitHub's new-issue page accepts query parameters, so you can open it with the title already typed in.

https://github.com/kanywst/kanywst/issues/new?title=shogi%7Cmv+7g7f
                                              └────────┬────────┘
                              opens the form with "shogi|mv 7g7f" already in it

The visitor presses the green "Submit new issue" button. That is the whole interaction. Nothing to type.

Once the issue exists, an issues.opened event fires, and that starts the Action. The whole round trip looks like this.

Following one link is one move.

The board is 81 links

The board is a <table> where each square is a <td>, and every square holds an image wrapped in a link.

<td><a href="new-issue URL"><img src="piece image" alt="7g black pawn"></a></td>

The piece images are not generated. There are 58 static SVGs sitting in .github/koma/, and the board state is expressed purely by which files get placed where. White's pieces are Black's pieces rotated 180 degrees, because orientation is the only way to tell the two sides apart on a shogi board.

Depending on the state of a square, the link points at one of three things.

State of the square	Link target	Meaning
A square the selected piece can reach	`?title=shogi\	mv 7g7f`
A piece belonging to the side to move	`?title=shogi\	sel 7g`
Anything else	`#shogi`	nothing happens

Even a dead square needs that third link. If you leave an image unwrapped, GitHub wraps it for you and points it at the image file:

<a target="_blank" rel="noopener noreferrer" href="y.svg"><img src="y.svg"></a>

A visitor who taps an empty square would land on a raw SVG with no way back to the profile. Sending them to #shogi costs nothing and keeps them on the board.

Two clicks, not one

The obvious design is one link per legal move, so a single click plays a move. Shogi has too many moves for that. I counted 1125 positions from random games: the median was 40 legal moves and the maximum was 167. Pieces in hand are the reason. Holding one pawn means every empty square is potentially another move.

There are only 81 squares to hang links on, so that does not fit. So the move takes two steps instead.

Now the number of links on screen is either how many pieces you own or how many squares the selected piece can reach, and neither can exceed the number of squares. It ends up feeling like marcizhu/marcizhu, which does the same thing with chess.

Illegal moves never get a circle, so the rules live entirely in what the board offers you. To check that the move generator was not lying, I counted the legal moves in the starting position and got 30, which is the known value for shogi.

Red circles alone did not communicate anything

This part I fixed after publishing. Someone looked at the board while a piece was selected and told me the circle made no sense.

They were right. One red circle floats in the middle of the board, and nothing on the board says which piece it belongs to. The real problem was that the selected piece still looked like an ordinary piece.

In a normal web app you would put a CSS class on the selected square and be done. Here the sanitizer eats style, as the API call earlier showed. The only thing left under my control is which file goes in <img src>.

So every piece image now has a second version with a red frame around the square. The frame is the same red as the destination circles, so "this piece goes to those circles" connects at a glance.

Adding 28 images to replace one line of CSS is a bad trade everywhere except here.

Wrapping up

No server, no database. The position lives in a single JSON file committed to the repository, and every move is recorded as a commit named shogi: move by @someone.

The part I like is that the players swap out asynchronously. Whoever plays Black and whoever plays White are probably different people who will never meet, and the game continues anyway.

As a thing to put on a profile, I think it says more than a skill list does.

If you pass by, play a move.

Let's play shogi.

https://github.com/0-draft/shogi

Mapping MCP, A2A, and ACP: Telling AI Agent Protocols Apart in 2026

kt — Sun, 28 Jun 2026 11:51:47 +0000

How this started: I went looking for ACP and it was gone

I wanted to sort out the difference between MCP, ACP, and A2A. MCP I hear about constantly. A2A I knew by name. ACP I barely knew, so I opened its official repo (github.com/i-am-bee/acp).

Here is what greeted me at the top of the README:

ACP is now part of A2A under the Linux Foundation!

The repo was archived on August 27, 2025 and set to read-only. In other words, ACP as a standalone protocol was over. It had been folded into A2A.

A lot of explainers written in the first half of 2025 are built around "pick the right one of MCP, ACP, and A2A." But in 2026 those three are not three equals. There are two pillars, MCP and A2A, and ACP is the history of something that flowed into one of them.

So in this post I am going to draw a map first: "an agent only reaches out in two directions." Then I will place MCP and A2A on that map, and only after that explain where ACP sat and where it went. Read it top to bottom and the loose terms should snap onto a single picture.

You need almost no background. If you have ever had an LLM call an API, you can follow this.

Prereq 1: what actually makes something an "AI agent"

Before the protocols, let me line up the words. "LLM" and "AI agent" get used interchangeably, but they are not the same thing.

An LLM on its own is close to a function that takes text and returns text. Smart, but it cannot do anything by itself. It cannot browse the web, read a file, or run code. It just answers what you ask.

An AI agent uses that LLM as a brain, and works toward a goal: it decides for itself, picks up tools, and loops as many times as needed. Tell it "book me a flight for next week's Tokyo trip" and it searches for seats, compares prices, and hits the booking API. It drives that whole loop on its own.

The thing to hold onto: an agent is a brain (the LLM) plus hands and feet (tools). The brain alone does nothing. How you wire up those hands and feet is where the first protocol shows up.

Prereq 2: an agent only reaches out in two directions

When an agent talks to "the outside world," it really only goes in two directions. These two directions are the map this whole post hangs on.

Downward, to use a tool (the vertical direction): a search engine, a database, an internal API, the filesystem. Things the agent "uses" as its own hands and feet. There is a master/servant relationship.
Sideways, to team up with another agent (the horizontal direction): an agent built by another team, an agent at another company. A peer you "hand work to" as an equal.

These two directions are completely different in nature.

Vertical (a tool): the other side is just a function. You pass input, you get output. It does not think. It does what it is told.
Horizontal (an agent): the other side has a brain too. You hand over "what you want done" (the intent), and it figures out how on its own. Sometimes it takes several round trips.

This vertical = MCP, horizontal = A2A split is the standard way to carve things up as of 2026. And this is not someone's hot take: the A2A spec itself has an "A2A and MCP" section that frames MCP as how an agent uses a tool and A2A as how agents collaborate as peers, and calls them complementary, not competitors.

So let me take the two one at a time.

MCP: the standard for the vertical direction (agent ↔ tool)

The problem MCP solved: N×M wiring hell

MCP (Model Context Protocol) is an open protocol Anthropic published in November 2024. In one line, it is a standard way to give an LLM tools.

Why standardize at all? Picture a world without a standard. Say there are N kinds of LLM (Claude, GPT, Gemini, ...) and M tools you want to connect (Slack, GitHub, Postgres, ...). With no standard, you end up writing a custom connector for every pair. That is N×M wires.

MCP drops one common socket in the middle. The tool side builds an "MCP server" once and every LLM can use it. The LLM side implements an "MCP client" once and can reach every tool. The wiring drops to N+M.

Before USB, every device needed its own cable. USB standardized the socket. MCP is "the USB between an LLM and its tools."

What is inside MCP: three roles and the primitives

MCP runs on top of JSON-RPC 2.0 (a plain convention for exchanging requests and responses as JSON) and keeps session state as it goes. There are three roles.

Role	What it does
Host	The app the user actually touches (Claude Desktop, an IDE, your own agent)
Client	Lives inside the Host and holds a 1-to-1 connection to a single server
Server	The side that provides tools and data (a Slack server, a DB server, and so on)

A server exposes mainly three things (called primitives). Nail these down and MCP's shape comes into focus.

Tools: "functions" the LLM can call. Like create_issue(title, body): pass arguments, it does something and returns a result. The LLM calls these actively.
Resources: "data" you let the LLM read. File contents, DB records, logs. Identified by a URI.
Prompts: prepared "instruction templates." The user picks one to use.

There are two ways to connect (the transport): stdio, which launches the server as a local process and talks over standard in/out, and Streamable HTTP, which connects over HTTP. Local tools use the former, remote services the latter.

Where MCP is now (2026)

MCP has not stood still. The spec gets updated often, and the latest as of 2026 is the 2025-11-25 revision. Read the trend of the changes and the direction is clear.

2025-06-18 revision: security took center stage. It formally classifies an MCP server as an OAuth 2.0 "resource server" and binds tokens to a specific server. It also added structured output (structuredContent) and elicitation (asking the user for more input mid-conversation).
2025-11-25 revision: authorization got stronger still (OpenID Connect Discovery support, among others). It also added tasks (experimental) for tracking long-running work.

MCP started as "just connect the tools" and has been shifting its weight toward "who is allowed to use this tool" (authn and authz). Once tools include internal DBs and payment APIs, that is the natural progression.

A2A: the standard for the horizontal direction (agent ↔ agent)

Where MCP runs out of road

MCP connects the tools. But what if the other side is not a tool, but another agent?

Say your company's travel-booking agent wants to hand work to a partner's "flight-booking agent." Now the other side:

has its own brain (an LLM); it is not a tool that executes your command one-to-one.
given an intent like "lock in a flight to Osaka next week with a seat, under 30,000 yen," decides for itself which booking API to hit and how.
does not finish in one round trip; it asks back, "that day is full, how about within three days either side?" (a multi-turn exchange).

The MCP "call a function once" model cannot express this. This is where A2A (Agent2Agent) comes in.

How A2A came to be

A2A is a protocol Google announced in April 2025. What happened next moved fast.

On June 23, 2025 it became a formal project under the Linux Foundation (backed by 100+ companies). That means it stopped being any one vendor's property and became a neutral standard.
On March 12, 2026 it reached v1.0.0. A stable release.

A2A's goal is to let opaque agents built by different vendors and frameworks collaborate without touching each other's internal state or tools. An agent whose source you cannot import, running somewhere else, owned by someone else. And you can still hand it work.

What is inside A2A: the Agent Card and the Task

The first thing to grasp in A2A is the Agent Card (the agent's business card). Each agent publishes it as JSON at /.well-known/agent-card.json, and it says:

what it can do (skills and capabilities)
where to connect (the endpoint)
what auth you need to call it (Bearer token? mTLS?)

The caller reads this card first. It learns "what this thing can do and how to authenticate" at runtime, then sends the real request. No need to pre-build against the other side's API contract.

The unit of work is the Task. A task has a unique ID and moves through states (submitted → working → input-required → completed, and so on). Even slow work can proceed while you follow its state.

This "1) read the card, 2) send intent, 3) work it out in a back-and-forth" is A2A's basic rhythm. Compare it to MCP's "call a function once and get a result" and you can feel the difference in cadence.

A2A is also about the N×N problem

A2A's real value, just like MCP's, is preventing combinatorial blowup.

Every company has agents and wants to hand work back and forth. With no standard, every pair needs its own connector. The more agents there are, the more the combinations explode (N×N). If everyone aligns on A2A's single card format and single calling convention, you can hand work to an agent you have never met, with no prior arrangement.

Same shape as USB-C. The technology itself is not new; the value is that everyone agreed on the same socket. Vendors have a motive here too: they do not want to expose raw APIs, but they will open up through an "agent" front door.

Where ACP sat, and where it went

So far, two pillars: MCP (vertical) and A2A (horizontal). So where does the ACP from the opening fit?

What ACP was

ACP (Agent Communication Protocol) is a protocol IBM Research announced in March 2025. It was built to drive BeeAI, an open-source agent platform (i-am-bee). Its purpose was nearly the same as A2A's horizontal lane: standardizing agent-to-agent communication.

There were small differences from A2A. ACP was REST-native and lightweight, and declared an agent's capabilities at build time (in contrast to A2A reading a card at runtime). But on the big picture, it was a competing protocol aiming at the same "agent-to-agent" slot as A2A.

And then it merged into A2A

Two standards (A2A and ACP) in the horizontal lane leaves the field asking "which one do I align with?" When a standard splits, the whole benefit of a standard (everyone converging) evaporates.

So in August 2025 the call was made. The IBM/BeeAI team wound down ACP's independent development and announced they would contribute its technology and know-how directly into A2A.

August 25-29, 2025: "ACP Joins Forces with A2A" is announced officially.
August 27, 2025: github.com/i-am-bee/acp is archived (read-only). The README leads with "ACP is now part of A2A" and a pointer to a migration guide.
BeeAI itself lives on, but its communication moves from ACP to A2A (with a migration guide provided).
An IBM Research representative joined A2A's Technical Steering Committee, alongside Google, Microsoft, AWS, Cisco, and others.

So in 2026, lining up ACP as a current, independent protocol next to MCP and A2A is not accurate. The right read is historical: "the horizontal lane briefly split in two, then consolidated onto A2A." If you are building something new, pick A2A for the horizontal lane. There is no reason to adopt ACP today.

Aside: the acronym "ACP" has another, unrelated meaning. The Cisco-led AGNTCY initiative uses "Agent Connect Protocol." It has nothing to do with IBM's Agent Communication Protocol, and online explainers sometimes conflate them. The ACP in this post always means the IBM/BeeAI one.

The whole picture: who does what in a multi-agent system

So how do MCP and A2A live together inside one system? A concrete example is the fastest way to see it.

Picture a system that takes the request "arrange my whole business trip." The shape:

Orchestrator agent: understands the request and parcels work out to specialist agents. The conductor.
Flight agent / Hotel agent: the specialists. Each runs independently.
Each agent uses external tools (a seat-search API, a booking DB) to do its own job.

Now draw the lines. Between the conductor and the specialists (the sideways link) is A2A. Between each agent and its tools (the downward use) is MCP. That maps straight onto the diagram.

The colors split the roles for you. The horizontal links between the pink agents are A2A; the vertical links from an agent down to a green tool are MCP. You cannot build this with only one of them. You need both the sideways collaboration and the downward tool use. Which is exactly why the official line, "MCP and A2A are complementary, not competitors," lands so cleanly in this picture.

A cheat sheet and a decision flow

Let me compress everything down to something you can use while your hands are on the keyboard.

Cheat sheet

Angle	MCP	A2A
Direction	Vertical (agent → tool)	Horizontal (agent ↔ agent)
Other side	A plain function (does not think)	An autonomous agent (has a brain)
What you pass	A function call (arguments)	An intent (what you want done)
Interaction	Usually call once, get a result	Multi-turn, stateful work
Discovery	Connect via server config	Read the Agent Card at runtime
Origin / steward	Anthropic	Google → Linux Foundation
Latest	Spec revision 2025-11-25	v1.0.0 (March 2026)
One-liner	"Give it a tool"	"Hand it a job"

Which one? A decision flow

When in doubt, ask first whether the thing you are connecting to is a "tool" or an "agent."

How it breaks when you pick wrong

A design call is not just "pick the right one." Knowing how it breaks when you pick wrong makes you stronger.

Implementing a tool call over A2A: you take on heavyweight machinery you do not need (fetching the card, task lifecycle management, async exchanges). It is overkill for a simple API call.
Forcing cross-company agent collaboration through MCP: MCP assumes "the other side is a tool," so it cannot express peer multi-turn negotiation or the other side planning on its own. There are bridges that "wrap an A2A agent as an MCP tool and call it once," but treat that as the narrow case where it is fine to demote a peer to a tool.
Adopting ACP today: the repo is archived and independent development has stopped. For the horizontal lane, lean on A2A.

Bonus: AGNTCY sits above all this

MCP and A2A cover the broad strokes. But there is one more name worth dropping to finish the map: AGNTCY.

AGNTCY is an initiative led by Cisco and others, donated to the Linux Foundation in July 2025, aiming at an "Internet of Agents." It is not a single protocol but a layer of infrastructure that sits higher up.

Discovery: a way to find agents, DNS-style.
Identity: cryptographically verifiable agent IDs.
Messaging (SLIM): a low-latency, secure transport between agents.
Observability: monitoring multi-agent workflows.

It is positioned to interoperate with A2A and MCP rather than compete with them. Think of MCP as "the socket to tools," A2A as "the socket between agents," and AGNTCY as "the city infrastructure that finds, connects, and monitors them all." You rarely touch it directly in day-to-day work, but knowing this layer exists gives you a clearer view of the whole ecosystem.

Wrap-up: a map makes it less scary

This ran long, so let me close back on the first map.

An agent reaches out in only two directions: vertical (tools) and horizontal (agents).
Vertical = MCP (Anthropic). The socket that gives an LLM tools. Collapses N×M wiring. Internals are host/client/server and tools/resources/prompts. Lately its weight has shifted toward authn and authz.
Horizontal = A2A (Google → Linux Foundation, v1.0.0 in March 2026). The socket for handing work to an agent. Read the Agent Card, run the Task. Collapses N×N wiring.
ACP was a second standard for the horizontal lane, but it merged into A2A in August 2025 and its repo is archived. In 2026 treat it as history; do not adopt it for new work.
In one system MCP and A2A coexist: A2A for the sideways collaboration, MCP for the downward tool use. That is exactly why they are complementary.

The "pick one of three" framing written last year got re-sorted, in 2026, into "two pillars plus one that flowed in." Standards converge like this, splitting and consolidating, until they settle onto a single socket. The way USB-C did.

Next time you actually write an MCP server or an A2A agent, start by asking yourself: "am I drawing a vertical line right now, or a horizontal one?" That alone tells you, without hesitation, which protocol's docs to open.

The Day client_id Becomes a URL: Client ID Metadata Documents vs Dynamic Client Registration (DCR)

kt — Fri, 26 Jun 2026 12:08:30 +0000

The "who is this client?" problem

In OAuth, the part that bites you is often not user authentication but client authentication.

An OAuth authorization flow has three parties: the user who owns the resource, the authorization server (AS) that guards it, and the client (the app) that wants to act on the user's behalf. The user proves who they are at a login screen. The client cannot do that on its own. Unless the AS already knows something about the client, it has no way to check whether the app sending this request is really the app it claims to be.

That is why OAuth has always had a client registration step. The app developer registers in the AS's dashboard ("this is my app, here is where it redirects") and gets back an identifier called a client_id. The client attaches that client_id to its authorization requests, and the AS recognizes "ah, that registered app."

The problem is that the world where pre-registration is even possible is shrinking.

Bluesky / AT Protocol: a user's data lives on one of countless servers (PDSes) scattered across the network. A client app cannot know in advance which server it will talk to, so registering with all of them is out of the question.
MCP (Model Context Protocol): an AI agent connects to arbitrary MCP servers. There are countless servers and the set keeps growing.
Fediverse (Mastodon and friends): thousands of self-hosted instances, any of which might be the counterparty.

In these "open meshes with no single AS," the classic pre-registration model falls apart. Two mechanisms emerged in response.

DCR (Dynamic Client Registration, RFC 7591): the client registers itself with the AS at runtime. A record gets written into the AS's database.
CIMD (Client ID Metadata Document): the client_id is an HTTPS URL. The AS goes and reads that URL. Nothing is written on the AS side.

This article lays the two out so you can read top to bottom and follow the reasoning. We start from the basics of OAuth client registration, walk through how DCR works and where it hurts, and then see what CIMD's "URL = client_id" idea actually solves.

Background: what client_id and redirect_uri are for

Before comparing CIMD and DCR, it helps to be clear on why client_id exists at all. If that is fuzzy, the rest of the comparison goes fuzzy too.

In the OAuth 2.0 authorization code flow, the browser sends a request like this to the AS's authorization endpoint.

GET /authorize?response_type=code
  &client_id=s6BhdRkqt3
  &redirect_uri=https://app.example.com/callback
  &scope=read
  &state=xyz HTTP/1.1
Host: as.example.com

Two things matter here.

client_id: the identifier for which client this is. The AS uses it to look up the registration.
redirect_uri: the URL the authorization code is returned to. The AS always checks this against the URL registered ahead of time, requiring an exact match.

The redirect_uri check is decisive because if an attacker could swap it freely, they could have the issued authorization code delivered to their own server. So "how does the AS learn the legitimate redirect_uri tied to a client_id" is the real job of client registration.

DCR and CIMD are both answers to that same question, "how do you establish the mapping from client_id to the legitimate redirect_uri (and the rest of the metadata)," approached from different angles.

Read "DCR or CIMD" as a difference in where the client_id to metadata arrow is stored, and who supplies it.

The classic approach: Dynamic Client Registration (DCR, RFC 7591)

How it works

DCR is standardized in RFC 7591. The idea is simple: take the registration a human used to do in a dashboard and automate it over an API.

The client POSTs JSON to the AS's registration endpoint.

POST /register HTTP/1.1
Content-Type: application/json
Host: as.example.com

{
  "redirect_uris": ["https://app.example.org/callback"],
  "client_name": "My Example Client",
  "token_endpoint_auth_method": "client_secret_basic",
  "logo_uri": "https://app.example.org/logo.png",
  "jwks_uri": "https://app.example.org/keys.jwks"
}

The AS takes this, creates a new registration record in its own database, and hands back a client_id (and, for confidential clients, a client_secret).

HTTP/1.1 201 Created
Content-Type: application/json

{
  "client_id": "s6BhdRkqt3",
  "client_secret": "cf136dc3c1fc93f31185e5885805d",
  "client_id_issued_at": 2893256800,
  "client_secret_expires_at": 2893276800,
  "redirect_uris": ["https://app.example.org/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "client_secret_basic"
}

From here the client uses its issued client_id to run authorization flows as usual. Updating or deleting the registration is handled by the sibling spec RFC 7592 (the management protocol). RFC 7592 also returns a registration_access_token and a registration_client_uri at registration time, and the client uses those two to GET / PUT / DELETE its own record.

Where DCR hurts

DCR works well when a client can hold a one-to-one relationship with an AS. The trouble starts when you drop it into one of the open meshes from the intro.

State explosion: one record per client instance, per counterparty server. The same app on Windows and macOS becomes two records; a hundred thousand users becomes a hundred thousand records. The AS database grows without bound.
Garbage registrations accumulate: records used once, or belonging to apps that no longer exist, never get garbage-collected. Revocation is mostly manual.
Registration endpoint abuse and DoS: open registration (anyone can register) lets an attacker mint records en masse. Preventing that needs an initial access token or a software statement (software_statement, a signed JWT) to gate registration, which reintroduces the "hand something out in advance" coordination and takes away much of the appeal of being dynamic.
Weak client-identity assurance: DCR itself does not verify that the app is who it says it is. Both client_name and logo_uri are self-asserted. That is fertile ground for consent phishing on the authorization screen.

In short, DCR assumes you write state on the server side, and the cost and lifecycle of that state break down in an open world.

A different idea: Client ID Metadata Document (CIMD)

The core idea: make client_id a URL

CIMD's idea fits in one line.

Make the client_id the HTTPS URL where the metadata JSON lives.

So it looks like this.

client_id = https://app.example.com/oauth-client-metadata.json

The client does not pre-register. Instead it puts its metadata (the same redirect_uris and so on it used to POST under RFC 7591) into a JSON file and hosts it at a URL it controls. In the authorization request it passes that whole URL as the client_id.

When the AS receives a client_id it has never seen, it goes and reads that URL to obtain the metadata. Nothing is written on the AS side. All the state lives in the document the client publishes.

A database write became "GET a URL once." That is the whole shape of CIMD.

Where this idea came from

"Use a URL as an identifier" is not new. The decentralized web has leaned on it for over a decade. The CIMD draft itself explicitly credits IndieAuth, Solid-OIDC, and OpenID Federation as prior art.

IndieAuth (IndieWeb): has identified clients by URL for 10+ years. It first fetched the client_id URL and read HTML microformats (h-app), then moved to JSON metadata.
Solid-OIDC (Tim Berners-Lee's Solid project): puts a Client Identifier Document, in JSON-LD, at a client-controlled URL. This is the direct ancestor of CIMD.
AT Protocol / Bluesky: adopted URL-based client_id in its OAuth profile in 2024, explicitly citing the draft (draft-parecki).
MCP (Model Context Protocol): in the 2025-11-25 spec, made CIMD the recommended default (SHOULD) and demoted DCR to MAY. That is what accelerated the IETF discussion.

The authors are Aaron Parecki (Okta) and Emelia Smith. Smith comes from the fediverse side, and the fediverse motivation ("an app connects to whatever self-hosted server it finds") is part of CIMD's background. Note that Mastodon itself still uses the DCR-style POST /api/v1/apps and has not shipped CIMD.

CIMD mechanics in detail

From here I follow the normative text of draft-ietf-oauth-client-id-metadata-document (latest is -01, published March 2026 as of June 2026).

1. Rules for the client_id URL

The URL you use as client_id has constraints (draft Section 3).

Must use the https scheme (http is not allowed).
Must contain a path component (e.g. /oauth-client-metadata.json). A host-only URL is not allowed.
Must not contain single-dot or double-dot path segments.
Must not contain a fragment (#...).
Must not contain a username or password (user:pass@).
A query string is discouraged but allowed. A port is allowed.

Short, stable URLs are recommended.

2. The self-reference rule (the anti-impersonation linchpin)

The document must contain a client_id property whose value matches the document URL by simple string comparison (Section 4.1). It must also be served with HTTP 200 OK.

{
  "client_id": "https://app.example.com/oauth-client-metadata.json",
  "...": "..."
}

This "the URL and the document's client_id agree" is the backbone of CIMD's security. Why? Because only whoever controls a domain can put content on it. So the only party that can claim a client_id of https://app.example.com/... is the party that actually controls app.example.com. If an attacker spoofs https://app.example.com/... as a client_id, fetching that URL returns the real document, the contents do not match, and it gets rejected. Domain control is the proof of identity.

3. Fields you can put in the document

The metadata vocabulary is the same as RFC 7591 (DCR) client metadata: redirect_uris, scope, grant_types, response_types, client_name, client_uri, logo_uri, jwks / jwks_uri, and so on. Think "take what you used to POST under DCR and publish it as a file."

There are forbidden fields, though.

client_secret and client_secret_expires_at (the document is public, so you cannot put a secret in it).
The token_endpoint_auth_method values client_secret_post / client_secret_basic / client_secret_jwt (no authentication based on a shared symmetric secret).

4. How the AS fetches

The AS should (SHOULD) fetch the URL indicated by the client_id.
It must not (MUST NOT) automatically follow HTTP redirects while fetching. This closes off SSRF via a redirect to an internal IP (more below).
It may cache (MAY). It should respect HTTP cache headers (SHOULD). It must not (MUST NOT) cache error responses. The cache key is the URL.

5. redirect_uri validation

The AS must require redirect URIs to be registered (MUST), and must require the request's redirect_uri to be an exact match of one of the redirect_uris in the document (MUST, Section 4.5). The AS may additionally constrain redirect_uris to the domain of client_id / client_uri (Section 6.1). The "exact redirect_uri match" from the background section is doing its work here too.

6. Public clients, and going confidential

Because the document is public, a CIMD client is fundamentally a public client. It cannot hold a client_secret.

If you still want to behave as a confidential client, you publish a public key in the metadata (jwks / jwks_uri) and authenticate with private_key_jwt (asymmetric) (Section 6.2). The private key never appears in the public document, so it works out safely. Bluesky's confidential clients use exactly this (ES256 + private_key_jwt).

DCR vs CIMD, head to head

Here is the mechanics so far in a table. The thing to watch is the symmetry between "where the state lives" and "what infrastructure burden it puts on the AS."

Axis	CIMD	DCR (RFC 7591 / 7592)
Where state lives	JSON at a client-hosted URL	A row in the AS database
What `client_id` is	The HTTPS URL itself	An opaque string minted by the AS
Basis of trust	Domain control + exact redirect_uri match	An AS-issued record (optionally a software statement / initial access token)
AS infra burden	Outbound HTTP (fetch + cache)	Write storage + lifecycle management
Secrets	None by default (public client). Confidential via `private_key_jwt` + published JWKS	Can issue a `client_secret` (confidential client)
Revocation	Take down / change the document + cache expiry	DELETE the registration record (RFC 7592)
Rotation	Edit the document (swap the JWKS, etc.)	AS-driven secret / token rotation
Portability	One document serves every AS and every instance	One registration per (instance x AS)
Main failure mode	Availability coupling (document host down means no auth) + an SSRF surface	DB bloat, garbage records, endpoint DoS

The difference in one line:

CIMD trades "the AS needs write storage" for "the AS needs outbound HTTP."

DCR accumulates state on the server. CIMD puts state on the client and the AS reads it. Neither is strictly better; it is a choice of which cost you can pay, or want to pay.

Security: SSRF takes center stage

CIMD's biggest risk is SSRF (Server-Side Request Forgery), because the AS sends an outbound request to a URL the attacker chose. The client_id is fully attacker-controlled. Point it at an internal metadata endpoint like client_id=http://169.254.169.254/... and the AS will fetch it. That is the textbook SSRF setup, verbatim.

The draft pins down SSRF defenses quite strictly (Section 6.5 and others). On the way from the individual draft to the WG draft, many of these were upgraded from SHOULD to MUST.

Block special-use IPs (MUST): the AS must validate that the client_id URL does not resolve to a special-use address from RFC 6890 (private IPs, loopback, link-local, etc.) (Section 6.5). The only exception is when the AS itself runs on loopback and the resolved address matches that same loopback interface. Note the strength split: declining to fetch other URLs written inside the document is SHOULD NOT, not MUST.
Do not follow redirects (MUST NOT): no automatic following of HTTP redirects while fetching. This blocks SSRF / DNS rebinding via a redirect like https://evil.example/ to http://169.254.169.254/.
https only: non-https schemes raise SSRF risk, which is one more reason for the https-only rule.
Response size limit (DoS defense): against returning a huge document to exhaust AS memory, set an upper bound (recommended around 5 KB).
Content-Type / status checks: confirm 200 OK and JSON. AT Protocol requires a "hardened HTTP client."

There are other concerns beyond SSRF.

Mutable metadata and impersonation (Section 6.3): the document is under the client's control and can change at any time. If redirect_uris, jwks, or scope change, the AS should consider revoking tokens or consent. And if the URL passes to a new owner (a recycled domain), that new owner inherits the client identity wholesale. That is an operational landmine.
Consent-screen phishing (Section 6.4): client_name and logo_uri are attacker-settable, unverified values. So the AS should also display the hostname of the client_id on the consent screen (SHOULD). AT Protocol likewise warns plainly that rich metadata is unverified and that you should only render it for allowlisted, trusted clients.

For contrast, the DCR-side security concerns:

Protect the registration endpoint: open registration invites DoS and garbage records. Gate it with an initial access token or a software statement.
registration_access_token is high value: it can read, update, and delete the registration record. Leak it and an attacker can rewrite redirect_uris. Treat it as a secret.
client_secret leakage: risk at rest and in transit. CIMD sidesteps this structurally because (as a public client) it holds no secret at all.

Concrete examples

CIMD: an AT Protocol (Bluesky) confidential client

The JSON you host at https://app.example.com/oauth-client-metadata.json.

{
  "client_id": "https://app.example.com/oauth-client-metadata.json",
  "application_type": "web",
  "client_name": "Example Client",
  "client_uri": "https://app.example.com",
  "redirect_uris": ["https://app.example.com/callback"],
  "response_types": ["code"],
  "grant_types": ["authorization_code", "refresh_token"],
  "scope": "atproto transition:generic",
  "token_endpoint_auth_method": "private_key_jwt",
  "token_endpoint_auth_signing_alg": "ES256",
  "dpop_bound_access_tokens": true,
  "jwks": {
    "keys": [
      { "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "kid": "key-1", "alg": "ES256" }
    ]
  }
}

A public client sets token_endpoint_auth_method to "none" and drops jwks. AT Protocol additionally requires DPoP and PAR. DPoP binds the access token to the client's key so a stolen token cannot be replayed (RFC 9449); PAR pushes the authorization request parameters to the AS over a back channel in advance, preventing front-channel URL tampering (RFC 9126). Neither is required by CIMD; they are extra safety Bluesky layers on top.

DCR: the RFC 7591 request and response

The DCR shape is what we saw earlier: POST, receive a client_id / client_secret. It helps to see the same metadata vocabulary (redirect_uris, grant_types, jwks_uri, ...) showing up as "JSON you publish" in CIMD and as "the body you POST and the record you get back" in DCR.

How it differs from IndieAuth

Even within the "URL as client_id, fetch it" family, IndieAuth differs in the details.

IndieAuth in its older mode reads HTML microformats (the newer mode uses RFC 7591 JSON). CIMD uses the RFC 7591 JSON vocabulary from the start.
IndieAuth requires the stricter rule that client_uri be a prefix of client_id. CIMD uses the simpler "the URL and the document's client_id match exactly" rule, plus an optional domain constraint.

IETF status, and how the two end up splitting the work

Status

CIMD is a WG-adopted Internet-Draft; the latest is -01 (2026-03-02). The -01 document header declares Intended Status: Standards Track, so it is aiming for the standards track (though it is not yet published as an RFC). It is not folded into the OAuth 2.1 core spec; it is moving as a separate extension draft.

Open questions

Points actively discussed on the draft's mailing list and issue tracker.

SSRF has been the biggest driver of revisions: special-use IPs moved to MUST, redirect-following to MUST NOT, the 5 KB limit was added. Feature requests like "allow non-public client_ids" were rejected as too SSRF-risky.
Identity for non-web clients: domain binding works for web apps (a domain backed by TLS / a CA) but not for desktop / CLI / native clients that cannot host a stable URL and use localhost or custom-scheme redirects. The critics' consensus is that CIMD solves registration but not fully the client-trust / identity problem. Complements such as signed software statements and platform attestation (Attestation-Based Client Authentication) are starting to be referenced as things that work with both CIMD and DCR.
Mutable, client-controlled metadata and ecosystem-wide upgrade friction (Emelia Smith's point that you can hardly update a CIMD until every AS in the ecosystem has upgraded).

MCP makes the split clearest

In the 2025-11-25 spec, MCP made CIMD the recommended default, but it deprioritized DCR rather than deprecating it. The reasons DCR survives are exactly the answer to how the two split the work.

Clients that cannot host a public document (desktop / CLI / IDE / internal agents) cannot do CIMD, so they need DCR.
DCR is an enforcement point where an organization can apply policy at registration time (dynamic but not open: managed onboarding).

Wrap-up

OAuth client registration ultimately comes down to one problem: how do you establish the mapping from client_id to a legitimate redirect_uri / metadata.
DCR (RFC 7591) establishes it by writing into the AS database. It works for one-to-one relationships, but in an open mesh it breaks down through state explosion, garbage records, and endpoint abuse.
CIMD makes the client_id an HTTPS URL and has the AS go read it. State lives in the document the client publishes, and domain control becomes the proof of identity.
The two are a symmetric trade-off: "the AS needs write storage" versus "the AS needs outbound HTTP." CIMD's price is SSRF and availability coupling, and the draft pins down SSRF defenses at the MUST level.
It grew up in the decentralized-social world of Bluesky / Solid / IndieAuth, and MCP making it the default pushed it into the mainstream. But DCR stays for clients that cannot host a URL, and the two split the work.

The client_id stops being a string and becomes a URL. That one shift in framing is what makes client authentication work in "the world where you cannot pre-register." If your product is the side that connects out into an open mesh, CIMD is going to be hard to ignore before long.

AgentAuth Deep Dive: Reading the Self-Authenticating UUID for AI Agents from the Source

kt — Thu, 25 Jun 2026 13:44:37 +0000

The trigger: showing an agent a login screen makes no sense

Every time I write an MCP (Model Context Protocol) server, the same problem stops me. The agent that just sent this request: who is it, and how am I supposed to tell?

For a human-facing web service the answer is settled. Show a login form, take an email and password, hand back a session cookie. Or OAuth: redirect the browser to an IdP, show a consent screen, come back holding a token. Every one of these assumes a human is sitting in front of a screen.

An AI agent has no human sitting in front of anything. It fires tools at 3am on its own, and one user might run ten agents in parallel. "Click the consent screen" and "remember the password" both fall apart. Hand every agent the same API key instead, and now you cannot tell who did what.

AgentAuth answers this with a fairly extreme move.

All you need is one UUID. No login, no sessions, no extra infra.

My first reaction was "authenticating with a UUID? that is just an ID, isn't it?" But once I read the source, this is not "just an ID." It is an ID that can prove its own correctness. This article reads that mechanism down to the code.

Here is the whole picture in one diagram first. I will take it apart piece by piece afterward.

Only the Token is secret. The Address and ID are derived from it deterministically. By attaching a Signature to every request, the server can confirm that the real holder of that ID actually sent it. That is what "self-authenticating UUID" means.

Background: identity and authentication are two different things

Before the mechanism, let me pin down one pair of terms. If this stays fuzzy, the interesting part of AgentAuth never lands.

Identity: "who are you." Like a user ID or an employee number. It just has to distinguish people
Authentication: "are you really you." Like a password or a fingerprint. It stops impersonation

In an ordinary system these two are built from separate machinery. Identity is "a user ID in the DB," authentication is "a password check." That is exactly why you need two steps: registration (create the identity) and login (authenticate).

AgentAuth's claim is "you can fold these two into a single UUID." Look at the UUID and you know who it is (identity), and if you attach a signature that only the holder of that UUID could produce, you also get authentication. Registration and login both disappear.

Why is that possible? The key is public-key cryptography. It comes up over and over from here on, so let me get the three minimum properties out of the way first. Skip ahead if you know them.

Keys come in pairs: a "private key" and a "public key" are always born together. You hold the private key alone; the public key can be shown to anyone
One-way: computing the public key from the private key is easy. The reverse (recovering the private key from the public key) is effectively impossible. Picture rolling down a hill versus climbing back up
Only the private key can sign, anyone can verify with the public key: attach a "signature" to some data with the private key, and whoever holds the matching public key can confirm "the holder of this private key made this signature over this data." Someone without the private key cannot forge a valid signature

AgentAuth maps these three properties straight onto "identity (derive it one-way)" and "authentication (signature)." Let me walk through them in order.

Core concept: Token to Address to ID, a one-way slope

AgentAuth has three values. They are easy to confuse, so let me pin their roles and "is it secret" in a table first.

Name	Example	Contents	Secret?	Role
AgentAuth Token	`aa-2337b9fa...bcb602`	secp256k1 private key (32 bytes)	Yes	The source of everything. Password-equivalent
Address	`0x99063225...58285ce`	Public address derived from the private key	No	Public-key material for verifying signatures
AgentAuth ID	`811ec2bf-b653-...dad7`	Stable UUID built from the Address	No	Identity usable as a DB primary key

The point is that these three are derived "one-way" in the order Token to Address to ID. Going down the slope is cheap to compute, but going back up (recovering the Token from the ID) is cryptographically impossible.

Notice this: only the Address and ID reach the server, the Token never leaves once. You keep the private key in your own hand and show the other side only the public values derived from it. This pays off when it combines with the "signature" later.

Let me walk the three steps one at a time through the actual code (@agentauth/core).

Steps 1 and 2: derive the Address from the Token

What deriveAddress does is, in fact, exactly the same as Ethereum's address derivation.

export function deriveAddress(privateKey: string): string {
  // Strip "aa-" or "0x" down to the 32-byte private key
  const cleanPrivateKey = parsePrivateKey(privateKey);
  const privateKeyBytes = hexToBytes(cleanPrivateKey);

  // 1. Uncompressed public key from the private key (65 bytes: 0x04 + X(32) + Y(32))
  const publicKeyBytes = secp.getPublicKey(privateKeyBytes, false);

  // Drop the leading 0x04 to get the 64-byte coordinate pair
  const publicKeyCoords = publicKeyBytes.slice(1);

  // 2. keccak256, then take the "last 20 bytes"
  const addressBytes = keccak_256(publicKeyCoords).slice(-20);

  return '0x' + bytesToHex(addressBytes);
}

Compute the public key with secp256k1 (an elliptic curve), hash it with keccak256, take the last 20 bytes. The resulting 0x... is the same format as an Ethereum wallet address.

One thing not to misread: there is not a single bit of blockchain involved. No on-chain processing, no gas. It just reuses, at the crypto-library level, the well-aged recipe Ethereum has run for years to "derive an address from a private key." The implementation rides on the audited @noble/secp256k1 and @noble/hashes.

Step 3: build a stable UUID from the Address

generateId is very short.

const AGENTAUTH_NAMESPACE = '2f5a5c48-c283-4231-8975-9271fe11e86c';

export function generateId(address: string): string {
  return uuidv5(address, AGENTAUTH_NAMESPACE);
}

UUIDv5 builds a UUID deterministically by hashing "namespace + name" with SHA-1 (unlike the random UUIDv4, the same input always yields the same output). Here the name passed in is the Address.

AGENTAUTH_NAMESPACE is hardcoded as a value that must never change. The source comment spells it out.

DO NOT CHANGE THIS UUID - EVER. (...) If you change this UUID, you will break all existing AgentAuth IDs.

Change the namespace and every agent's ID in the world becomes a different value. So this constant effectively defines "the AgentAuth standard itself." Hold the same Token and the same AgentAuth ID comes out, no matter who computes it or when. That determinism is the foundation for "a stable identity without a login."

Why this removes registration

With that in hand, the reason registration disappears becomes clear.

An ordinary system needs a registration step because "the server assigns a user ID and records it in the DB." In AgentAuth the ID is derived mathematically from the private key, so the client can settle its own ID without asking the server. The server just INSERTs into the DB the first time it sees an ID, with no prior "account creation" flow.

The heart of it: authenticating with a per-request signature

So far we have the identity (the ID). But the ID is public information. If someone knows your AgentAuth ID, can't they just claim it and fire off requests?

The trick that stops that is the signature. It attaches to the request a piece of proof that only the true holder of the AgentAuth ID, the one holding the Token, can produce.

Making the signature (client side)

export function signPayload(payload: object, privateKey: string): string {
  const messageString = JSON.stringify(payload);
  const messageHash = keccak_256(messageString);

  const cleanPrivateKey = parsePrivateKey(privateKey);
  const privateKeyBytes = hexToBytes(cleanPrivateKey);

  const signature = secp.sign(messageHash, privateKeyBytes);

  // EVM-standard signature format: 0x + r(32) + s(32) + recovery(1)
  const signatureHex =
    signature.toCompactHex() +
    signature.recovery.toString(16).padStart(2, '0');
  return `0x${signatureHex}`;
}

Hash the payload (JSON) with keccak256 and sign it with the private key. The output is 0x plus a 65-byte signature. As noted below, the payload always carries a timestamp.

Verifying the signature (server side)

The crux on the verify side is the "recover the public key from the signature" operation. Same idea as Ethereum's ecrecover: from the signature and the message, back-compute "the address corresponding to the private key that could have produced this signature."

export function verifySignature(
  signature: string, payload: object, expectedAddress: string
): boolean {
  // ... pull r, s, recovery out of the signature ...

  const messageHash = keccak_256(JSON.stringify(payload));

  // Recover the public key from the signature (ecrecover-equivalent)
  const sig = new secp.Signature(BigInt('0x'+r), BigInt('0x'+s)).addRecoveryBit(recovery);
  const recoveredPublicKey = sig.recoverPublicKey(messageHash);

  // Convert the recovered public key into an address
  const addressBytes = keccak_256(recoveredPublicKey.toRawBytes(false).slice(1)).slice(-20);
  const recoveredAddress = '0x' + bytesToHex(addressBytes);

  // Does the "claimed address" match the "address recovered from the signature"?
  return recoveredAddress.toLowerCase() === expectedAddress.toLowerCase();
}

Put into words, it goes like this.

The client claims "I am Address 0x9906..."
At the same time it attaches a signature over the payload
The server recovers "the address of whoever made this signature" from the signature
If the recovered address matches the claimed address, it is genuine

A third party without the private key cannot produce a signature that recovers to the right address in step 3. So "just knowing the ID" does not get you through. That is why authentication holds up even with a public ID.

One full round trip of a request

verify() in @agentauth/sdk is the entry point on the server side. The request carries three HTTP headers.

Header	Contents
`x-agentauth-address`	The claimed Address (`0x...`)
`x-agentauth-payload`	base64-encoded JSON, containing a `timestamp`
`x-agentauth-signature`	The signature over the payload (`0x...`)

Following one exchange as a sequence looks like this. The color bands mark the client-side signing (red), the server-side verification (blue), success (green), and failure (gray).

The verify() code is those four steps written out directly.

export function verify(request, options = {}): VerificationResult {
  const freshness = options.freshness ?? 60000; // default 60s

  const agentauth_address = headers['x-agentauth-address'];
  const signature        = headers['x-agentauth-signature'];
  const payloadB64       = headers['x-agentauth-payload'];
  if (!agentauth_address || !signature || !payloadB64) return { valid: false };

  // 1. Restore the payload
  const payload = JSON.parse(Buffer.from(payloadB64, 'base64').toString('utf-8'));

  // 2. Verify the signature (ecrecover, then compare Address)
  if (!verifySignature(signature, payload, agentauth_address)) return { valid: false };

  // 3. Freshness check on the timestamp (replay protection)
  if (Math.abs(Date.now() - new Date(payload.timestamp).getTime()) > freshness) {
    return { valid: false };
  }

  // 4. Generate the stable UUID and return it
  return { valid: true, agentauth_id: generateId(agentauth_address) };
}

What stands out is that the server completes verification without holding any state at all (no session, no recorded nonce). No DB lookup, no cache. It decides on the signature and the timestamp alone. That is why it gets called "zero infrastructure."

What the 60-second timestamp is for

The constraint in step 3, that the timestamp be within 60 seconds, is replay-attack protection.

It stops an attacker who eavesdropped a signed request from re-sending it verbatim (replaying it) to impersonate. Because "when it was made" is part of what was signed, a signature older than 60 seconds cannot be reused. Instead of recording nonces on the server, it rejects by a time window. That is the trade-off with the stateless design, settled here with a "short window."

Hands-on: run the derivation chain yourself

Theory alone does not stick, so let me run it locally. Hit @agentauth/core directly and confirm that Token to Address to ID derives deterministically.

mkdir agentauth-play && cd agentauth-play
npm init -y
npm pkg set type=module
npm install @agentauth/core

Write play.mjs.

import {
  generateIdentity, deriveAddress, generateId,
  signPayload, verifySignature,
} from '@agentauth/core';

// 1. Generate a new agent identity
const id = generateIdentity();
console.log('Token  :', id.agentauth_token);   // aa-... (secret. this is the only thing that matters)
console.log('Address:', id.agentauth_address);  // 0x...
console.log('ID     :', id.agentauth_id);       // UUID

// 2. Determinism check: derive from the Token any number of times, same result
const addr2 = deriveAddress(id.agentauth_token);
const id2   = generateId(addr2);
console.log('re-derive matches:', id2 === id.agentauth_id); // true

// 3. Sign and verify
const payload = { timestamp: new Date().toISOString(), action: 'get-forecast' };
const sig = signPayload(payload, id.agentauth_token);
console.log('valid signature passes:', verifySignature(sig, payload, id.agentauth_address)); // true

// 4. Tamper with the payload by even one character and it fails
const tampered = { ...payload, action: 'delete-everything' };
console.log('tampering is rejected :', verifySignature(sig, tampered, id.agentauth_address)); // false

node play.mjs

Once re-derive matches: true shows up, you feel that the same ID always reproduces from the Token alone. tampering is rejected: false shows that the signature is bound to the payload. The server just has to trust the result of verifySignature.

Wiring it into a server

On the MCP server side you call verify() from @agentauth/sdk in middleware or at the top of each tool. The official weather-server sample is the clearest example.

import { verify as verifyAgentAuth } from "@agentauth/sdk";

// Attach an auth context in Express middleware
app.use(async (req, _res, next) => {
  const authResult = verifyAgentAuth({ headers: req.headers });
  if (authResult.valid) {
    // Authenticated: you have a stable UUID in hand
    req.auth = { clientId: authResult.agentauth_id, extra: { agentauth: authResult } };
  }
  // Do not reject the unauthenticated (let them through as anonymous)
  next();
});

Inside a tool you can change behavior based on "authenticated or not." The weather-server splits a free and premium tier exactly on the presence of this ID.

server.tool("get-alerts", "Weather alerts (auth required)", { state: z.string().length(2) },
  async ({ state }) => {
    const auth = getAuthForCurrentRequest();
    if (!auth) {
      return { content: [{ type: "text", text: "🔒 This feature requires authentication" }] };
    }
    // Use auth.agentauth_id for billing, rate limiting, usage logging
    console.error(`✅ Agent ${auth.agentauth_id} accessed`);
    // ... return the real data ...
  }
);

Client-side config is just dropping the Token into the MCP client's config file. Write it once and you connect to any AgentAuth-aware remote MCP server with the same Token.

{
  "mcpServers": {
    "weather": {
      "command": "agentauth-mcp",
      "args": ["connect", "https://example.com/mcp"],
      "env": { "AGENTAUTH_TOKEN": "aa-..." }
    }
  }
}

The agentauth-mcp proxy signs each request with the Token and attaches the three headers automatically. The Token itself never takes a step outside your machine.

Package layout: who uses which

Putting the division of labor on one page looks like this.

@agentauth/core: the crypto foundation. Just the derive / sign / verify functions. You normally do not touch it directly
@agentauth/sdk: used by MCP server developers. You just call verify({ headers })
@agentauth/mcp: the proxy-plus-CLI used by agent users. generate issues a Token, connect makes a signed connection. It now lives separately at agentauthco/mcp-gateway

Where to use it and where not to: dividing the field with MCP's official OAuth 2.1

This is the most important part. Jump to "so I should use this for MCP auth" and you will crash. AgentAuth and MCP's official authorization cover fundamentally different ground.

The official MCP spec firmed up its authorization on an OAuth 2.1 base over the course of 2025. Worth tracing the flow.

2025-03: put remote MCP server authorization on an OAuth 2.1 base. Introduced authorization-server metadata discovery (RFC 8414)
2025-06-18: classified the MCP server clearly as an "OAuth 2.1 Resource Server." Made Protected Resource Metadata (RFC 9728), Resource Indicators (RFC 8707, binding a token's audience), and PKCE mandatory. Banned token passthrough (forwarding a received token straight to an upstream API as-is) and closed the confused-deputy hole where authority gets misused by mistake
2025-11-25 (the current latest): made PKCE require S256 when technically capable, and the resource parameter always mandatory. Promoted Client ID Metadata Documents (CIMD) to the recommended registration path, demoting the older Dynamic Client Registration (DCR) to a backward-compatible option

In other words, what the official MCP spec is solving is the delegation problem: "as a stand-in for the human Alice, an agent reaches a third-party resource (like GitHub) with narrowed scope." Consent screens, scopes, audience binding, IdP integration are the stars.

What AgentAuth provides is only "who is this agent (identity) plus is it really them (authentication)." No scopes, no consent, no delegation. Putting the positioning in a table:

Dimension	AgentAuth	Official MCP OAuth 2.1	Plain API key
Identity source	self-derived from a local key (no issuer)	issued by an authorization server	issued by the server
Backend	none (stateless verify)	authorization server + metadata endpoints	key store
Registration / login	none	DCR/CIMD + consent flow	manual issuance
Authorization (scopes)	none (identity only)	yes (scopes, audience binding, RBAC)	none
Human in the loop	not needed	needed (consent, redirect)	not needed
Credential lifetime	long-lived private key (password-equivalent)	short-lived scoped tokens	long-lived
Replay protection	signature + 60s time window	TLS + short-lived tokens	none

The decision guide sorts out like this.

AgentAuth fits: you control both ends (client and server) and want to "tell agents apart by a stable ID, block impersonation, but not run authorization infra." Usage tracking, free/paid gating, anonymous-but-consistent analytics
OAuth 2.1 is required: calling third-party APIs on a user's behalf, narrowing scopes, taking consent, integrating with a corporate IdP. The moment delegation enters, this becomes mandatory

The two are not mutually exclusive, they compose. Agent identity by AgentAuth, resource authorization by OAuth is a stacking that holds up in principle. Read AgentAuth as "a self-sovereign API key that is also a verifiable, stable UUID" and you will not misplace it.

Realities to know before adopting

The design is clean, but if you are weighing production, here is the honest part too.

Still very young: @agentauth/core is at v0.1.1. First published June 2025, and quiet since. Monthly npm downloads are in the dozens per package, so a track record in the field is still ahead. Excellent as something to dissect for an interesting design, but not a "battle-aged standard"
The name collision is bad: this space is flooded with "Agent Auth" style names. The AgentAuth at agentauth.co is a different thing from Dick Hardt's AAuth, from Better Auth's Agent Auth plugin, and from Microsoft Foundry's agent identity. Watch out when searching
The long-lived private key trade-off: the Token is password-equivalent and long-lived. Leak it and the ID tied to that key is taken over wholesale. Be aware this runs in the opposite direction from the world of rotating short-lived tokens (WIF, ID-JAG)
Authorization is your own job: "what it is allowed to do" sits outside AgentAuth. After making the ID a DB primary key, you still have to design permission management yourself

Wrap-up

AgentAuth in one line is "a UUID derived deterministically from a private key that can authenticate itself." Stacking the mechanism from the bottom up, it connects like this.

The Token is a secp256k1 private key. From it you derive an Address Ethereum-style, then an AgentAuth ID via UUIDv5 (one-way)
The ID is public, but every request is signed with the private key, so it cannot be impersonated
The server recovers the Address from the signature and compares, plus rejects replays with a 60-second window. It holds no state at all
The result: a "stable identity plus authentication" with no registration, no login, no session DB

I think it is a clean fit of public-key crypto's "keep the private key in hand, show only public values" property onto agent authentication. But this is a tool for authentication (authn), not authorization (authz). Keep the line straight, that it does not compete with MCP's official OAuth 2.1 but covers different ground, and where it lands is clear.

If you want to get your hands on it, run the hands-on above with npm install @agentauth/core first, and see for yourself the determinism of Token to ID and signature verification rejecting tampering. Once that clicks, you are halfway to seeing what is interesting about this design.

Reference links:

JWT (Access Token) vs X.509 Deep Dive: How to Choose What You Present as a Credential

kt — Mon, 15 Jun 2026 13:54:03 +0000

Introduction

I was poking around a service mesh when something struck me as odd.

Inside the mesh, Pod-to-Pod traffic authenticated with mTLS: both sides showed each other an X.509 certificate. But the same request, when it came from outside through an API Gateway, carried a JWT in Authorization: Bearer eyJ.... Same job ("who are you, and may you come in"), yet the thing being handed over changed depending on where you stood.

At first I assumed it was just historical mess. The more I dug, though, the more it turned out to be a clean split that comes down to one axis: "bearer, or proof-of-possession?"

This article lines up JWT (access tokens) and X.509 (mTLS) from the angle of "what do you present as a credential," and walks through when to pick which, top to bottom. It starts from the basics, so you can follow it even if you are not deep into OAuth or TLS.

Setup: what "present a credential to get authorized" actually means

Let me get the vocabulary straight first. The "getting authorized" scene that runs through this whole article has three actors.

Issuer: creates the credential and hands it out. For a JWT that is the IdP (authorization server); for X.509 it is the Certificate Authority (CA).
Presenter: holds the credential it received and shows it to the other side on every request.
Verifier: checks whether the presented credential is genuine and whose it is, then decides to let it through or reject it.

A "credential" is the ID badge you present in step 2. It is structurally the same as showing your driver's license to prove your age. The question is what you use as that badge. Here the path forks into two families.

JWT (access token): a signed JSON, sent in the Authorization header.
X.509 certificate: a digital certificate presented during the TLS handshake. The "m" in mTLS (mutual) is exactly this.

The two differ in how they look and where they ride, but the essential difference is a single thing. That is next.

The core: bearer, or proof-of-possession

Every difference grows from here. Credentials split into two kinds by "can you use it just by holding it."

Bearer type: anyone holding the thing can use it. Like cash. Drop your cash and whoever picks it up can spend it. JWT access tokens are basically this.
Proof-of-possession type: showing the thing is not enough. You have to prove every time that it is really yours. Closer to a bank card with a PIN. Steal the card and you still cannot move money without the PIN (the private key). X.509 + mTLS is this.

This one picture is the most important in the article. Almost everything else is a consequence of it.

If a JWT is stolen, the thief gets to act as "you" directly (a replay attack). That is why the standard move for JWTs is to keep their lifetime short so the damage window stays small.
An X.509 certificate is more or less public information, but you cannot open a TLS session without holding the matching private key. Sniff the wire and copy the certificate, and you still cannot impersonate "you," because you lack the private key.

"So just always use X.509, right?" Not quite. Proof-of-possession carries its own costs (distributing, storing, and rotating private keys, plus the proxy problem covered later). That is exactly why you need to choose.

Cracking each one open

Now that the axis is clear, let me look at the two real artifacts.

JWT (access token): a signed JSON flowing through the app layer

A JWT is a string split into three parts by ..

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9 . eyJzdWIiOiJzdmMtYSIsImF1ZCI6... . SflKxwRJSMeKKF2QT4f...
|------------ header -----------|    |--------- payload --------|    |----- signature ----|
  alg (sign method), typ              sub (who), aud (for whom), exp    signed with private key

The verifier checks the signature using the key set the issuer publishes (the JWKS: JSON Web Key Set). The point is that the verifier does not have to call the issuer. If the signature checks out, it can trust the token's contents (who, until when, for whom). This is stateless verification. Delivery is via an HTTP header.

There are also access tokens whose contents are not a JWT, the opaque tokens. For those the verifier calls the issuer's introspection endpoint on every request to confirm validity (stateful). When this article says "access token," it means the JWT form that supports the stateless verification above.

GET /api/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiI...

Since this lives at the application layer (L7), anything that speaks HTTP can carry it. A proxy or a Gateway can pass it straight through as "just a header." That matters later.

X.509 certificate: an identity proven during the TLS handshake

X.509 is presented in the middle of opening a TLS connection. Ordinary HTTPS has only the server present a certificate, but in mTLS the client presents one too, and on top of that proves possession by signing with its private key.

The verifier walks the certificate up to a CA it trusts (the trust bundle) to confirm legitimacy, and then uses the CertificateVerify signature to confirm the peer "really holds the private key." The defining trait is that authentication finishes before a single byte of application data flows, and this is transport-layer (closer to L4) work.

That pins down where each one lives: a JWT is data flowing through the app layer, and X.509 is an identity carved into the connection itself.

Lining them up on seven axes

With both artifacts in view, let me put them side by side. First a table for the big picture, then notes on the axes that matter most.

Axis	JWT (access token)	X.509 (mTLS)
Trust model	Bearer	Proof-of-possession
Theft resistance	Weak (steal it, use it)	Strong (useless without the private key)
Layer it works at	App layer (L7 / HTTP header)	Transport layer (TLS handshake)
Survives a proxy / LB	Yes (just a header)	No (mTLS is terminated there)
Verification	Check signature via JWKS (stateless)	CA chain (trust bundle) + signature check
Revocation	Let it expire via a short `exp`	CRL / OCSP, or short-lived certs
Operational cost	Low (no key distribution)	High (distribute, store, renew keys). Automated in a mesh

Three axes are worth expanding.

Axis 1: can it cross a proxy

This is the one that bites hardest in production. mTLS is authentication bound to "this point-to-point connection." Put an L7 load balancer or API Gateway in the middle that terminates TLS, and the client's identity vanishes there. From a service deeper than the Gateway, the peer is the Gateway, not the original client.

A JWT is "data," so the Gateway can forward it deeper as a header untouched. So if you want to carry identity end to end across several proxy hops, use a JWT. That is the answer to the mystery from the opening: cross the Gateway and it becomes a JWT.

Axis 2: how you revoke

When you want to cancel a credential, the two strategies are inverted.

JWT: once a signed token is out, the verifier never calls the issuer, so "revoke it after the fact" is hard. So you make the lifetime short from the start (minutes to tens of minutes) and wait for a leaked one to expire on its own. A long-lived JWT is a red flag.
X.509: you can announce "this certificate is no longer valid" via a revocation list (CRL) or OCSP. But the verifier has to go check that, which is operationally heavy. So rather than leaning on CRLs, the current trend is to make the certificate itself short-lived (SPIRE defaults to one hour, for example) and reissue it frequently.

The funny part is that both roads end up in the same place: "keep it short-lived to dodge the problem."

Axis 3: operational cost

X.509 means handing a private key to each workload, storing it safely, and renewing it on a schedule. That is the real source of "certificates are painful." But today a service mesh like Istio or Linkerd, or SPIFFE/SPIRE, does this distribution and renewal fully automatically. The old common sense that "mTLS is operationally heavy," from the days of handing out certificates by hand, has largely faded in a mesh.

The JWT side does not need to distribute a private key to clients (only the issuer holds the signing key), and the verifier just pulls the public key from the JWKS. The barrier to adoption is low.

Know how each one breaks

Before you choose, it helps to know how each gets defeated, so your judgment does not wobble. The entry point for an attacker is completely different between the two.

JWT alg:none: the biggest landmine in JWT. Set the header alg to none and a buggy implementation may accept "valid even without a signature," a classic vulnerability. You close it with a sane library and an operational rule that pins the allowed alg (the SPIFFE JWT-SVID spec limits alg to nine values and rejects none and the symmetric HS* family).
JWT theft and replay: the bearer curse. Minimize the damage with a short exp, sending over TLS, and never logging it.
X.509 private key leak: since possession of the private key is the whole basis of proof, a leaked key is game over. So keep keys off plain disk, ideally locked inside a TPM / HSM or in memory, and rotate them by keeping them short-lived.
X.509 CA compromise: take over the CA and you can mint any fake identity. Managing the trust bundle matters.

X.509 says "as long as you protect the private key, being watched on the wire is fine." JWT says "as long as you protect the channel (TLS) it is easy to adopt, but a leak means instant impersonation." The point you have to defend is different.

The hybrid: bearer ergonomics + proof-of-possession strength

"I want the convenience of a JWT, but I do not want it used after being stolen." Two mechanisms answer that greed. Both bolt proof-of-possession onto a JWT.

Certificate-bound access token (RFC 8705): at issuance, the hash (thumbprint) of the client certificate is stamped into the token. The verifier checks that "the thumbprint written in the token" matches "the certificate on the mTLS connection it currently holds." A stolen token alone is useless because you cannot open the matching mTLS connection. Used in high-security domains like Open Banking.
DPoP: for situations where you cannot run mTLS, it binds the token to a key the client holds, at the app layer. A "proof" signed with that key is attached per request, and the verifier cross-checks it against the token.

In short, "bearer or PoP" is not 0 or 1. You can add PoP to a JWT and slide toward the middle. But every addition costs implementation and operational effort, so for the first decision the plain two-way split is enough.

Choosing by example: the SPIFFE guidance makes it concrete

SPIFFE, the standard for workload identity, carries both formats: the certificate flavor X509-SVID and the JWT flavor JWT-SVID. And the guidance in its docs is blunt, which makes a ready-to-use decision rule. Summarized:

Because they are susceptible to replay attacks, use X.509-SVIDs whenever possible. Use JWT-SVID when mTLS is not practical, such as when an L7 proxy or load balancer sits between workloads.

Walk a worked example. An order service calls an inventory service.

Inside the mesh, Pod to Pod, direct: no L7 proxy in between, and the sidecar rotates certificates for you. Use X509-SVID (mTLS). Sniffing is useless without the private key, so it resists replay.
Across an API Gateway from outside, or with an L7 LB in between: mTLS gets terminated at the Gateway and identity vanishes. Put a JWT-SVID in a header and carry it end to end. In return, keep exp short (a few minutes) to bound the theft risk.

In real production the standard is a hybrid: "JWT (OAuth) at the user edge, mTLS between services." You do not have to commit to one. The right answer is to choose per boundary using the decision tree above.

Quick reference

To put the decision in one place.

When	Pick	Why
Service to service, direct inside a mesh	X.509 + mTLS	Auto-renewal works, resists replay
Crossing an L7 proxy / Gateway	JWT	mTLS is terminated and identity vanishes; a JWT survives as a header
From a browser / mobile	JWT	Distributing a private key to the client is impractical
Many services trust the same issuer	JWT	Verifiable via JWKS, no certificate distribution
Strong defense against replay needed	X.509, or a cert-bound / DPoP JWT	Close the bearer weakness with proof-of-possession
Must revoke immediately	X.509 (CRL/OCSP), or a short-lived JWT	JWT is bad at after-the-fact revocation; substitute short lifetimes

And the one line to remember goes back to the first picture.

A JWT works if you hold it (bearer). X.509 works if you hold it and can prove it with the private key (proof-of-possession). Almost every other difference follows from that.

Conclusion

The two families of credential you hand over for authorization, JWT (access token) and X.509 (mTLS), can be organized along one axis: bearer or proof-of-possession.
A JWT is easy and crosses proxies, but a stolen one gets used. So you protect it by keeping it short-lived.
X.509 is strong, useless even if sniffed without the private key, but its weaknesses are that identity is cut off at a proxy and that keys need operating. In a mesh, automation makes the operations light.
If you want both, you can bolt proof-of-possession onto a JWT with RFC 8705 certificate-bound tokens or DPoP.
In practice it is not either-or; you choose per boundary with the decision tree. SPIFFE's "X.509 whenever possible, JWT when a proxy is in the way" works directly as the rule.

Next time you look at your own system, go boundary by boundary and check, "is what flows here a bearer, or a proof-of-possession?" If a long-lived bearer token is flowing along a near-plaintext path, that is your most dangerous spot.

a2claude: Turn Claude Code Into a Server Other AI Agents Can Call

kt — Sun, 14 Jun 2026 07:54:12 +0000

Introduction

Running a single AI agent is starting to feel dated. You have an agent that researches, one that plans, one that writes code, each with a role, handing work to each other. When I tried to wire up a setup like that, I got stuck on one question: what do I use for the "writes code" slot?

I already had Claude Code. It actually runs tools, edits files, and runs tests for you. The catch is that Claude Code is built to be driven by a human sitting at a terminal. There is no built-in door for another agent to call it automatically.

So I wrote a small tool that exposes Claude Code as an A2A protocol server. It is called a2claude. Another agent sends "implement this feature" over A2A, a real Claude Code session runs against the project you pointed it at, and the result streams back. And what comes back is not a blob of text: it is structured information about which tools ran, which files changed and how, what it cost, and which actions need approval.

The repo is here: github.com/kanywst/a2claude

This article is written so that reading top to bottom takes you from knowing nothing about A2A or the internals of Claude Code to understanding exactly what a2claude bridges and how.

Background 1: What A2A is

A2A (Agent2Agent) is a communication standard for AI agents to talk to each other. Google announced it in 2025, donated it to the Linux Foundation the same year, and it is now governed there under neutral stewardship (v1.0 landed in 2026). It rides on top of HTTP over one of JSON-RPC, gRPC, or REST (the spec requires all three to expose the same operations), and it standardizes the exchange where one agent asks another to do a job.

There are only four terms you need to hold onto.

Agent Card: the business card that states what an agent can do. It lives at a fixed path, /.well-known/agent-card.json, and a caller reads it first to decide whether this agent can handle what it wants done.
Task: one request. It carries state and moves like submitted (received) → working (in progress) → completed (done). Along the way it can also hit input-required (waiting on input) or failed.
Artifact: the output of a Task. Generated text, files, and so on. It can be returned incrementally (streamed).
contextId: the conversation handle. Send the next Task with the same contextId and it is treated as a continuation of the previous one.

The Task state transitions look like this. It pays to keep this in your head, because how a2claude uses these states matters later.

A2A has other states too, such as rejected (the agent declines the request), but the ones a2claude actually uses are in this diagram. The one in red, input-required, becomes the star of the second half.

The point is that A2A is a shared language between agents: it does not matter what an agent runs on the inside (Claude or some other LLM), as long as it honors the Agent Card and the Task exchange, the conversation works.

Background 2: What Claude Code is

Claude Code is Anthropic's coding agent. It is not a chat that only returns prose. It also:

runs commands with Bash
reads and writes files with Read / Edit / Write
stops to ask for approval before risky actions
reports the cost and turn count of a run

In other words, it actually moves its hands. The thing to notice for this article is that when Claude Code runs, a lot of information beyond text comes out: which tool it called, which file it changed and how, what it cost. a2claude does not throw that away. It puts it on A2A.

Background 3: Why a bridge is needed

A2A is the protocol for agents to talk. Claude Code is the powerful tool that actually writes code. The two do not line up. Claude Code has no A2A server door, and from the A2A world Claude Code is invisible.

So you need a translator in between. It takes an A2A Task, drives Claude Code, and translates the events Claude Code emits back into the language of A2A. That is what a2claude does.

How this differs from the usual approach

Adapters that "wrap a coding agent in A2A" are not rare. But most of them flatten both input and output to text. You hand over a prompt and get text back. That erases everything that happened in between. From the calling agent's point of view, you cannot see whether a file was rewritten, what spent money, or whether an action needed approval.

a2claude keeps the structure that comes out of Claude Code and carries it onto A2A. The difference between the left and right of the diagram below is the whole reason this project exists.

What maps to what

The heart of a2claude comes down to one mapping table: "what Claude Code emits" onto "which A2A surface it lands on". This table, which is also in the README, is the core of the design.

What Claude Code emits	The A2A surface it lands on
Assistant text	A streamed artifact (`append` / `last_chunk`)
A tool call (Bash, Edit, ...)	A `working` status update
A file edit	A named artifact carrying the diff
Run result	Cost / turns / usage on the completion message
Session id	Mapped to the A2A `contextId` to resume next time

This mapping is closed up in one place in the code (executor.py). That is what pays off in the next section.

Architecture: the A2A layer does not know Claude directly

a2claude is split into layers. The single most important design decision is that the layer doing the A2A translation never imports the SDK that drives Claude Code.

In between sits an abstraction called a "backend". A backend's job is to drive Claude Code and emit normalized events (text, tool calls, file changes, permission requests, run results). The translation layer looks only at those events and maps them onto A2A. How Claude is invoked (through the SDK today, through the raw CLI later) is none of the translation layer's business.

Because of this split there are two backends.

echo: no API key and no Claude install required. A dummy that just mirrors the input. It lets you exercise the server, the protocol mapping, and the CLI end to end, offline. It reproduces every path, including the permission round trip that comes up later.
claude: drives the real Claude Code through the Claude Agent SDK.

Why is "the translation layer not knowing the SDK" worth it? Because testing gets easy. The echo backend alone can verify all of the A2A behavior. With no API key to call Claude, even in CI, you can check that the design has not broken.

Inside: an event queue and "parking"

This is the most interesting part of a2claude. A backend's drive runs as a background task and pushes the events it produces onto a queue. The translation layer (the consumer) pulls them off in order with drain.

While things are flowing normally it is just a producer / consumer. The interesting case is when you hit a tool that needs approval. Claude Code stops and waits. At that point a2claude parks the background task right at the permission request, and pushes only a "please approve this" event onto the queue. drain returns that one event and then halts.

While it is halted, the Claude session does not die: it waits. Later, when the caller sends its answer, the parked task resumes and starts flowing again. This trick of "keeping the session alive across two separate calls" is what makes the next section's permission exchange possible.

Permissions: do not auto-approve, do not silently skip

How you handle actions that need approval is the most nerve-wracking part of opening a coding agent up to someone else (another agent). A sloppy implementation either "auto-approves everything" or "silently skips anything that needs approval". Both are dangerous.

a2claude uses the A2A input-required state. This is not something a2claude invented: A2A defines it precisely for human-in-the-loop, where a human or the caller makes a decision mid-task. Per the spec, when a Task reaches input-required the processing stops there and control returns to the caller. a2claude rides directly on that.

When a tool that needs approval shows up, the Task stops at input-required and asks the caller "approve this action?". The caller sends its answer as a message on the same Task. allow (or yes, approve, ok) approves; anything else denies.

Thanks to the park from the previous section, the Claude session is still alive while stopped, so when the approval comes back it picks up right where it left off.

One more important point: the server does not inherit the personal Claude settings of whoever runs it. Your local Claude Code has a pre-approved tool allowlist ("this tool is always OK"), but the server does not load it. So when it acts on behalf of another agent, any action needing approval always routes back to the caller for a decision. Read-only actions that are already considered safe still run without a prompt, as before.

Session continuity: remembering "the previous turn"

Claude Code holds a conversation session and can keep working with the prior context. a2claude ties that Claude session id to the A2A contextId and remembers it. Send the next Task with the same contextId and the same Claude conversation resumes.

"Add a /health endpoint" → "now add a test for it" goes through as one continuous piece of work, not two separate requests.

Try it

From here on we actually run it. You need three things.

Python 3.13 or newer
uv
(only for the claude backend) the Claude Code CLI on your PATH

First clone and install dependencies.

git clone https://github.com/kanywst/a2claude
cd a2claude
uv sync

First, offline (the echo backend)

The echo backend needs no API key and no Claude install. Running the whole path offline first puts your mind at ease. Start the server and call it from another mouth.

uv run a2claude serve --backend echo &
uv run a2claude call "fix the failing test"

What comes back looks like this. A Task and context id are assigned, and after the stream the completion metadata (cost and turn count) is attached.

task 189b1c63-1a7b-4908-87c4-c8f3bba8f6b5
context 0b2a901e-2b6f-4c56-bba2-d0da546936e9

  · Echo
fix the failing test
[completed] $0.0 · 1 turns

Point it at a real project (the claude backend)

Now the claude backend. Use --cwd to set the directory Claude Code works in.

uv run a2claude serve --backend claude --cwd /path/to/project
uv run a2claude call "add a /health endpoint" --url http://localhost:9100/

Ask for a follow-up

Pass the context that came back from the previous turn and it becomes a continuation of the same conversation.

uv run a2claude call "now add a test for it" --context <context-id>

Try the permission exchange

Send an action that needs approval and it stops at input-required and asks for an answer. The answer goes to the same Task.

uv run a2claude call "sudo reboot"
# ... [input-required] Permission requested for Bash: $ sudo reboot
#       reply: a2claude call "allow" --task <id> --context <id>
uv run a2claude call "allow" --task <id> --context <id>

The echo backend also asks for approval when the prompt contains sudo, so you can verify just this exchange without driving Claude.

Peek at the Agent Card

This is the business card the other agent reads first.

uv run a2claude card

a2claude does not lump Claude Code's abilities into one "chat box". It lists them as discrete skills on the Agent Card: code generation, refactor, debug, review, test, and code explanation, six of them. The caller can aim a request, "this is a debug job", deliberately.

Wrap-up

What a2claude does comes down to one mapping table: it maps the structured events Claude Code emits onto A2A's Task, Artifact, status, and contextId. It does not flatten them to text.

Three design points to single out:

The translation layer does not know Claude's SDK. With a backend abstraction in between, echo alone verifies the whole path offline, and swapping out how Claude is invoked later leaves the translation layer untouched.
Permissions map to input-required. Keeping a parked session alive across two calls means it never auto-approves and never silently skips. The decision always returns to the caller.
contextId makes the conversation continuous. Mapping the Claude session id to the A2A context remembers "the previous turn".

If you are looking for a "writes code" slot in a setup where agents hand work to each other, you can drop Claude Code straight in as a part. The code is small enough to read all of, so take a look, and if something is off, throw an Issue.

github.com/kanywst/a2claude

DEV Community: kt

What Coding Agents Leave in Public Git Repos

The numbers

Why each one ends up there

Check your own

Stop it at the source

Method

Secret Scanners Look for Credentials. I Wanted One That Looks for Me.

Same repository, two scanners

What kwangmyong shows

It starts from who you are

Stop the agent, not just the commit

CI

Not covered yet

Ransomware in Japan: 61 of 92 Known Entry Points in 2025 Were VPN Appliances

One company, drawn as a floor plan

What happens after the door opens

31 exploited VPN flaws

Where each control actually helps

Cases, in the organizations' own words

How the numbers were checked

How it's built

Mandatum: Making an AI Agent's Authority a Chain You Can Verify

Introduction

The three things

What mandatum does

The sequence part

Three places I'd actually use it

What isn't built

Where I'd like to be wrong

I Made Four Authorization Engines Answer the Same Questions

Where ReBAC stops

What broke

How it runs

Envoy AI Gateway: A Hands-On Tour You Can Run Before Touching Kubernetes

The day we ended up with three places to call an LLM

0. How to read this

1. What makes an "AI gateway" different from a normal API gateway

1-1. The same operation has three different shapes

1-2. Requests are the wrong unit for billing

1-3. Responses stream for a long time

2. Where this sits in the Envoy family

3. Architecture

3-1. Control plane and data plane

3-2. Why ExtProc is wired in twice

3-3. The life of a request

4. The CRDs worth memorizing

5. Hands-on: run it without Kubernetes

5-1. Install aigw

5-2. Stand up a mock LLM to talk to

5-3. Start it with no config file

5-4. Send a request

5-5. Tokens are already being counted

6. Hands-on: watch schema translation happen

6-1. A mock that speaks Bedrock

6-2. Set the egress schema to AWSBedrock

6-3. Send OpenAI format

6-4. The return trip gets translated too

6-5. Where I got stuck: Anthropic is not a valid translation target

7. Hands-on: fallback and model name virtualization

7-1. Stand up an upstream that fails

7-2. Write the config

7-3. Run it

7-4. The metrics keep a record of the virtualization

7-5. Send a model that is not in any route

7-6. Where I got stuck: forgetting retriable-status-codes

8. Hands-on: use it as an MCP gateway

8-1. Try it against a public MCP server that needs no auth

8-2. Narrow the tool list

9. Move it to Kubernetes

9-1. Prerequisites

9-2. AI Gateway itself

9-3. Get traffic flowing

9-4. Look at what got generated

9-5. ExtProc arrives as a native sidecar

9-6. Connect to the real OpenAI

9-7. Raise the buffer limit

9-8. When you do not want API keys in Secrets

10. Token-based rate limiting and quotas

10-1. How it works

6-5. Where I got stuck: `Anthropic` is not a valid translation target

7-6. Where I got stuck: forgetting `retriable-status-codes`