@ssheleg/agent-stack 0.6.1 → 0.7.1

package/plugins/agent-stack/skills/agent-interop/references/gateway.md

@@ -0,0 +1,161 @@
+# The gateway layer — one controlled seam for agent traffic
+
+**Load this when:** many clients meet many servers, tool access needs to differ per caller,
+or somebody has asked who is allowed to call what and you cannot answer from one place.
+
+**Spec pinned:** agentgateway `1.4.x` from `agentgateway.dev/docs/standalone/latest` · read 2026-08-13
+
+Linux Foundation, Apache-2.0, written in Rust.
+
+This file is **vendor-neutral first**: what a gateway for agent traffic must do, then
+agentgateway as a named reference implementation. Swap the implementation and the first half
+still holds.
+
+## Contents
+
+- Why an API gateway is not enough
+- What a gateway must do
+- Federation and the name-collision problem
+- Where authorization belongs
+- agentgateway, concretely
+- Traps
+
+## Why an API gateway is not enough
+
+A conventional gateway assumes stateless request/response. Agent traffic breaks four of its
+assumptions at once, and each break is a feature you would otherwise build by hand:
+
+| Assumption | What agent traffic does |
+|---|---|
+| one request, one upstream | **multiplexes** across several tool servers and merges the result into one surface |
+| the server answers when asked | servers **initiate** events — SSE streams, change notifications |
+| the protocol is fixed | MCP and A2A **revise**, so the hop has to negotiate versions rather than pass bytes |
+| authorization is per route | authorization is **per tool and per client**, inside one route |
+
+There is also a threat class with no HTTP analogue: **tool tampering, tool shadowing, and
+rug-pull** — where a server's advertised tools change after approval, or one server's tool
+name shadows another's. A proxy that only forwards cannot see any of it happen.
+
+## What a gateway must do
+
+Independent of product:
+
+1. **Terminate and re-establish the protocol**, not tunnel it — otherwise none of the rest is
+   possible.
+2. **Federate many servers behind one endpoint**, with a deliberate answer to name
+   collisions.
+3. **Carry server-initiated events** across the hop, including reconnects, without silently
+   dropping subscriptions.
+4. **Authorize per tool and per caller**, not per route.
+5. **Pin and negotiate protocol revisions**, so one server upgrading does not break every
+   client at once.
+6. **Detect change in the advertised surface.** A tool set that changes after approval is the
+   rug-pull; somebody has to notice.
+7. **Emit one audit trail** across every hop, with the identity that made the call attached
+   to it.
+8. **Route model traffic too**, where the same seam fronts LLM providers — otherwise you run
+   two proxies and two policies.
+
+**The reason to want one at all:** without it, each of these lands in every client
+separately, and the security answer becomes "it depends which client".
+
+## Federation and the name-collision problem
+
+Two servers, both exposing `search`. The model sees one name and the router picks by load
+order — which is a coin flip that looks like a bug in the model.
+
+The general answer is **namespacing at the federation point**, and the general trap is
+**doing it inconsistently**, because tool names are what the model learned. A name that
+changes between sessions invalidates every prompt, cache and eval that referenced it.
+
+agentgateway's shape, as a concrete instance: multiple **targets** combine into one backend —
+"Virtual MCP" — with tool names prefixed by target name (`time_get_current_time`,
+`everything_echo`), controlled by `prefixMode`:
+
+| `prefixMode` | Behaviour |
+|---|---|
+| `conditional` *(default)* | prefix only when the backend has more than one target |
+| `always` | prefix even with a single target |
+| `never` | never prefix — names must already be unique, or initialization fails |
+
+**`conditional` is a friendly default and a latent break.** Add a second target and every
+tool name in the first one changes. If anything persists tool names — a prompt, a cached
+plan, an eval fixture — choose `always` up front and pay the ugliness once.
+
+```yaml
+backends:
+  - mcp:
+      targets:
+        - name: time
+          stdio:
+            cmd: uvx
+            args: ["--with", "mcp<2", "mcp-server-time"]
+        - name: everything
+          stdio:
+            cmd: npx
+            args: ["@modelcontextprotocol/server-everything"]
+```
+
+## Where authorization belongs
+
+**At the gateway, and again at each hop.** A gateway is the right place to express "this
+client may call these tools" because it is the one place that sees every call. It is the
+wrong place to make it the *only* check, because a server reachable by any other path is
+unprotected.
+
+Two rules that survive any product choice:
+
+- **Policy per hop, not only at the entrance.** A chain of agents passes context onward, and
+  authority does not automatically travel with it.
+- **The gateway sees the calls, not the intent.** It can enforce that a tool may be called;
+  it cannot tell whether the model was manipulated into calling it. Content inspection is
+  probabilistic — anything consequential needs a deterministic limit or a human. See
+  `agent-orchestrator/references/governance.md`.
+
+## agentgateway, concretely
+
+A unified HTTP and gRPC proxy written in Rust — a control plane and a data plane — under the
+Linux Foundation, Apache-2.0. It covers three planes at once:
+
+| Plane | What it does |
+|---|---|
+| **LLM providers** | OpenAI-compatible routing across 20+ providers (OpenAI, Anthropic, Bedrock, Azure, Gemini, Cohere, Ollama, …) |
+| **MCP** | tool federation across many servers, per-client authorization |
+| **A2A** | inter-agent calls, capability discovery |
+
+**Local configuration — and read this before copying an example.** The current top-level keys
+are `config`, `gateways`, `routes` / `tcpRoutes`, `llm`, `mcp`, `ui`, plus `services` /
+`workloads` for advanced backends. **`binds` is the deprecated predecessor to `gateways`** —
+and the project's own overview page still introduces it, which is exactly the kind of drift
+this skill's rule zero exists for. A minimal MCP config:
+
+```yaml
+mcp:
+  port: 3000
+  targets:
+    - name: everything
+      stdio:
+        cmd: npx
+```
+
+**Security policies** available as first-class config: JWT authentication, API-key
+authentication, HTTP authorization, external authorization, and **MCP-specific
+authorization** — the last being the per-tool control that a generic gateway lacks.
+
+**On Kubernetes** it is conformant to the **Gateway API** — `HTTPRoute`, `GRPCRoute`,
+`TCPRoute`, `TLSRoute` — so it uses standard resources rather than a proprietary CRD set.
+That is the strongest single argument for it in a cluster that already runs Gateway API: the
+routing objects are ones your platform team already reviews.
+
+## Traps
+
+- **Introducing a gateway and leaving the direct paths open.** The policy is then advisory.
+- **`prefixMode: conditional` plus a second target**, silently renaming every tool.
+- **Copying a config from a blog post.** `binds` versus `gateways` is a live example; the
+  config surface moves faster than the articles.
+- **Treating the gateway as the security boundary.** It is *a* boundary. The sandbox, the
+  credentials and the per-hop policy are the others.
+- **Federating servers you do not trust into one namespace.** Federation makes a hostile
+  server's tools look exactly as legitimate as everyone else's.
+- **Forgetting the reconnect.** MCP notification delivery is best-effort; a hop in the middle
+  makes a dropped subscription more likely, not less. Poll as well.

package/plugins/agent-stack/skills/agent-interop/references/mcp-scale.md

@@ -0,0 +1,162 @@
+# MCP at scale — when there are more tools than context
+
+**Load this when:** the host connects to more than a handful of servers, tool definitions are
+eating the context window, or chained tool calls are pushing large intermediate results
+through the model.
+
+**Spec pinned:** MCP `2026-07-28`, `docs/2026-07-28/develop/clients/client-best-practices` · read 2026-08-13
+
+## Contents
+
+- The two costs, and which pattern fixes which
+- Progressive tool discovery
+- Dynamic server management
+- The prompt-cache interaction nobody expects
+- Programmatic tool calling (code mode)
+- Security surface
+- Traps
+
+## The two costs, and which pattern fixes which
+
+They are different problems and confusing them wastes a rewrite:
+
+| Cost | Symptom | Pattern |
+|---|---|---|
+| **Definitions** — *when* tools enter context | the window is largely consumed before the user's message is read | **progressive discovery** |
+| **Results** — *how* tools are invoked | every intermediate result flows through the model on the way to the next call | **programmatic tool calling** |
+
+The published illustration is stark: loading everything upfront at ~150,000 tokens of
+definitions against ~2,000 for discovering on demand. They compose — discovery narrows what
+the model knows about, code mode narrows what it has to read.
+
+## Progressive tool discovery
+
+The naive host passes every connected server's `tools/list` output to the model at the start
+of every conversation. For a handful of tools this is correct and you should not do anything
+cleverer.
+
+**The switch is a threshold, and the guidance is explicit:** express it as a percentage of
+the context window — **1%–5%** — load definitions normally until it is reached, then switch.
+
+Once switched, the host fetches definitions as usual but **defers injecting them**, exposing
+a `search_tools` meta-tool instead. Three layers:
+
+1. **Catalog** — `search_tools({query: "update salesforce record"})` returns names and
+   one-line descriptions only.
+2. **Inspect** — `get_tool_details({name: "salesforce_updateRecord"})` returns the full
+   schema for that one tool.
+3. **Execute** — the model calls it, having loaded only what it needed.
+
+**Retrieval strategy**, and none is automatically right:
+
+| Strategy | Good at | Cost |
+|---|---|---|
+| Keyword (BM25, regex) | descriptive names; simple, predictable | misses synonyms |
+| Embedding | synonyms and semantic matches | index to build and maintain |
+| Subagent (small fast model picks) | works very well | the most expensive |
+| Hybrid | scoring across rankings, or per use case | complexity |
+
+**Check the provider first.** OpenAI and Anthropic both ship built-in tool search; prefer the
+platform's over a hand-rolled one unless you need access-control filtering or domain-specific
+ranking in the retrieval itself.
+
+**Implementation guidance worth obeying:** offer multiple detail levels (name-only,
+name+description, full schema); cache definitions host-side so re-injection needs no round
+trip; **re-index on `notifications/tools/list_changed`**; group tools by their source server
+so the model can reason about related capability.
+
+## Dynamic server management
+
+The same idea one level up. Rather than connecting to everything at startup: keep a registry
+of available servers with high-level descriptions, connect when the model asks for that
+capability, and **disconnect when it is no longer relevant** to free context.
+
+This suits general-purpose agents, where intent is unknown at the start. It also composes
+with Agent Skills: a skill file can declare which servers it needs, and the host connects
+them only when that skill is invoked.
+
+## The prompt-cache interaction nobody expects
+
+This is the part that turns a clever discovery implementation into a regression, and it is
+easy to ship without noticing.
+
+Most providers cache the prompt prefix — **including the `tools` array**. Adding or removing
+a definition mid-conversation **invalidates that cache**, and the resulting miss can cost more
+tokens than the definitions you so carefully removed.
+
+Three mitigations, in the order they are usually right:
+
+- **Append** newly discovered definitions after the cache breakpoint rather than re-sorting
+  the array.
+- Or route every call through **one stable `call_tool({name, args})` meta-tool**, so the
+  array never changes at all.
+- Treat **server disconnection as a conversation-boundary operation**, not a per-turn one.
+
+**Measure this rather than reasoning about it.** Whether your discovery scheme is a net win
+depends on your provider's caching and your conversation shape, and the loss is invisible in
+a token count that only sums definitions.
+
+## Programmatic tool calling (code mode)
+
+Instead of the model calling tools, the model **writes code that calls tools**; the code runs
+in a sandbox and only its output returns to the model.
+
+**How it is wired:**
+
+1. The host generates a typed API from each server's tool schemas. Where a tool declares
+   `outputSchema`, the generated return type is precise — which is the concrete reason to
+   provide one.
+2. The model writes a script against those functions.
+3. The sandbox executes it. Calls are **intercepted and routed back through the host broker**
+   to the right MCP server. Intermediate data flows server-to-server without entering
+   context. Only `console.log` output returns.
+
+The canonical example: "find all error logs from the past hour and file a ticket for each
+unique error." Direct calling pushes thousands of log entries through the model; code mode
+filters and deduplicates inside the sandbox and returns one summary line.
+
+**When `outputSchema` is missing**, prefer the simple path — accept a generic type and handle
+it downstream; the real fix belongs to the server author. A typed extraction via a small
+fast model is available for single-shot calls outside loops, but it adds latency, can
+hallucinate or drop fields, and its result must be validated before use.
+
+**Sandbox options**, listed as examples rather than endorsements — evaluate maturity
+yourself: Deno or `isolated-vm` for JavaScript; Monty (experimental) for Python; pctx
+(early-stage) for TypeScript; Wasmtime for anything compiled to Wasm. Whichever you pick, the
+integration is the same: inject stubs, intercept over an in-process or stdio channel so
+network permission can stay fully denied, dispatch as `tools/call`.
+
+**Errors:** convert `isError: true` into a thrown exception in the generated wrappers so
+model-authored code can `try`/`catch`. If an uncaught error kills the script, surface it as
+the script's result so the model can self-correct — and note that the model is then
+responsible for reporting side effects already committed.
+
+## Security surface
+
+Code mode adds a code-execution surface, and each of these is a real control rather than
+advice:
+
+- **Per-call authorization.** The broker is still the MCP host for specification purposes.
+  Approving the *script* does not approve every call it makes at runtime. Categorical grants
+  are fine ("allow `ticketing_createIssue` for this run"); evaluating each call against the
+  grant is not optional.
+- **Cross-server data flow.** A result from server A is untrusted input to server B. Apply
+  the same review policy to brokered calls as to direct ones — **truncating output does not
+  prevent exfiltration**.
+- **Network isolation.** The sandbox gets no direct network access; everything goes through
+  the broker.
+- **No credential exposure.** Keys live with the host; generated code calls typed functions
+  and the host attaches auth when forwarding.
+- **Resource limits.** Timeouts and memory caps, or one runaway script is an outage.
+- **Output filtering.** Validate and truncate console output before it re-enters the model.
+
+## Traps
+
+- **Switching to discovery too early.** Below the threshold it is pure overhead plus a
+  failure mode: the model cannot use a tool it never found.
+- **A search index that never re-indexes.** Without honoring `list_changed`, discovery
+  confidently returns tools that no longer exist.
+- **Counting definition tokens and calling it a saving.** See the prompt-cache section.
+- **A sandbox with network access.** It is then not a sandbox, it is a proxy for the model.
+- **Assuming the sandbox bounds authorization.** It bounds *execution*. Authorization is the
+  broker's job, per call.

package/plugins/agent-stack/skills/agent-interop/references/mcp-ship.md

@@ -0,0 +1,142 @@
+# Shipping an MCP server — mount it, and debug the client that cannot reach it
+
+**Load this when:** the server is written and now has to reach someone — mounting it inside
+an existing web app, or fixing a client that will not connect.
+
+**Spec pinned:** MCP `2026-07-28` transports; FastMCP/Starlette mounting shapes · read 2026-08-13
+
+`mcp.md` is the protocol. This file starts where that one stops, and covers the part that
+is not in any specification: where the endpoint actually lands, and why the client says 404.
+For **publishing** to the registry, see `registry.md`. For designing the tool set in the
+first place, Anthropic's `mcp-server-dev` plugin is built for it and this file does not
+repeat it.
+
+## Contents
+
+- Mounting into an existing web app
+- Auth middleware and a health endpoint
+- Client configuration
+- Debugging a client that will not connect
+
+## Mounting into an existing web app
+
+The common production shape: you already run a FastAPI/Starlette app, and the MCP server
+should live at `/mcp` on the same host. It is also where the single most common bug lives.
+
+**The double-path pitfall.** FastMCP defaults its internal `streamable_http_path` to
+`/mcp/`. Mount that app at `/mcp` and the real endpoint becomes `/mcp/mcp` — so every
+client pointed at `/mcp` gets 404, and the SSE fallback 404s too, which reads like the
+server is down.
+
+```python
+mcp = FastMCP(
+    "my_server",
+    streamable_http_path="/",   # REQUIRED when mounting as a sub-app
+    stateless_http=True,
+    json_response=True,
+)
+
+app.mount("/mcp", mcp.streamable_http_app())
+```
+
+Set `streamable_http_path="/"` whenever the app is mounted rather than served standalone.
+Standalone servers keep the default.
+
+## Auth middleware and a health endpoint
+
+**Wrap the mounted ASGI app rather than adding auth inside tool handlers.** The transport
+handshake happens before any tool runs, so handler-level auth leaves the protocol surface
+open — an unauthenticated caller can still enumerate what you expose.
+
+```python
+class MCPAuthMiddleware:
+    _PUBLIC_PATHS = {"/health"}
+
+    def __init__(self, app, *, store):
+        self._app, self._store = app, store
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] not in ("http", "websocket"):
+            return await self._app(scope, receive, send)
+        if scope.get("path", "") in self._PUBLIC_PATHS:
+            return await self._app(scope, receive, send)
+
+        headers = dict(scope.get("headers", []))
+        auth = headers.get(b"authorization", b"").decode()
+        if not auth.startswith("Bearer "):
+            return await self._send_401(send, "Missing Bearer token")
+        if not await self._store.validate_api_key(auth[7:]):
+            return await self._send_401(send, "Invalid API key")
+        return await self._app(scope, receive, send)
+
+app.mount("/mcp", MCPAuthMiddleware(mcp.streamable_http_app(), store=key_store))
+```
+
+Keep a health endpoint **outside** the mount and exempt from auth. It is what tells "the app
+is up, the MCP path is wrong" apart from "the app is down" — the two produce identical
+client errors.
+
+```python
+@app.get("/mcp/health")
+async def mcp_health():
+    return {"status": "ok", "server": "my_server", "transport": "streamable-http"}
+```
+
+## Client configuration
+
+Remote (Streamable HTTP):
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer ${MY_SERVER_KEY}" }
+    }
+  }
+}
+```
+
+Local (stdio):
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/project", "run", "python", "-m", "my_server"],
+      "env": { "API_KEY": "..." }
+    }
+  }
+}
+```
+
+**Ship both forms in your README.** A user who has to derive the config from prose files an
+issue instead.
+
+## Debugging a client that will not connect
+
+**404 — by far the most common.** Symptom: `Error POSTing to endpoint: Not Found`, then the
+SSE fallback 404s as well. Bisect the path directly:
+
+```bash
+curl -X POST https://your-host/mcp/     -H 'Content-Type: application/json' -d '{}'
+curl -X POST https://your-host/mcp      -H 'Content-Type: application/json' -d '{}'
+curl -X POST https://your-host/mcp/mcp  -H 'Content-Type: application/json' -d '{}'
+```
+
+If `/mcp/mcp` answers — **even 401** — while `/mcp/` 404s, it is the double path. A 401 is a
+*success* for this test: it proves routing reached the server.
+
+**307.** Starlette redirects `/mcp` → `/mcp/`. Most clients follow it on POST; some do not,
+and the failure looks like a hang. Either document the trailing slash or add an explicit
+no-slash route.
+
+**401.** Check the Bearer prefix and the key, then check that the client is actually sending
+headers — several clients drop custom headers on the SSE fallback specifically, so the
+initial POST authenticates and the stream does not.
+
+**Version rejection.** Under `2026-07-28` a server that cannot speak the client's revision
+answers `UnsupportedProtocolVersionError` listing what it does support. That is a readable
+error, not a connection failure — read the list and retry on a common version rather than
+treating it as the server being broken.