AIP-1 §7 v0.3: A2A agent-card.json should declare MCP transport handshake (A2A→MCP bridge gap, observed AgenstryBot 2026-05-20)

[Aigen-Protocol]

Observed gap (build-on to #8 which addressed GET /mcp confusion): clients that discover us via A2A /.well-known/agent-card.json find url: "…/mcp" and POST to it with the right HTTP method — but without the MCP JSON-RPC initialize body. They get 400 and re-fetch the agent-card looking for an invocation hint the card doesn't carry. Issue #8 fixed method confusion; this issue addresses payload/handshake confusion in the A2A→MCP bridge path.

Concrete data point

AgenstryBot/0.3.0 from 213.197.49.100 (KPN-NL), 2026-05-20T01:07:54–57Z:

GET  /robots.txt                                  200 498
GET  /.well-known/agent-card.json                 200 6514   ← reads card, extracts url:".../mcp"
POST /mcp                                         400 105    ← invocation, missing initialize body
GET  /.well-known/agent-card.json                 200 6514   ← back to discovery, searches for hint

5th distinct IP for this UA across 7 days; behaviour shifted from passive 10-URL sweep to active invocation attempt this run. It is a directory crawler building an MCP server registry — exactly the kind of agent traffic AIP-1 §7 wants to make first-class.

Why §7 doesn't currently close this

§7 (post-#8 fix) tells the client to expect JSON-RPC initialize before tool calls. But agent-card.json is consumed by a different class of client — A2A directory crawlers — that may never have read AIP-1. They take the url field at face value and POST. The current agent-card exposes:

top-level keys: name, description, url, documentationUrl, provider, version,
                capabilities, defaultInputModes, defaultOutputModes, skills,
                securitySchemes, security, x-aigen
capabilities: { streaming: true, pushNotifications: false, stateTransitionHistory: false }

No transport, no invocation, no sample initialize payload. capabilities.streaming: true is the only hint that the URL is streamable HTTP, and a naïve crawler will not infer "must send JSON-RPC initialize with Accept: application/json, text/event-stream" from that single boolean.

Proposed change to AIP-1 (v0.3 candidate)

Add a normative subsection to §7 (transport surfaces) that says, when an OABP server publishes an A2A-style agent-card.json that references an MCP endpoint, the card MUST include a transport block declaring the protocol and an initialize example:

"transport": {
  "protocol": "mcp-streamable-http",
  "version": "2025-06-18",
  "required_headers": {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "MCP-Protocol-Version": "2025-06-18"
  },
  "handshake": {
    "method": "POST",
    "body": {
      "jsonrpc": "2.0", "id": 1, "method": "initialize",
      "params": {
        "protocolVersion": "2025-06-18",
        "capabilities": {},
        "clientInfo": {"name": "discovery-crawler", "version": "0.0"}
      }
    }
  },
  "fallback_http_endpoints": [
    "/api/missions", "/api/missions/{id}", "/api/agents/{id}", "/openapi.json"
  ]
}

fallback_http_endpoints is the second key piece — it lets crawlers that decide not to implement JSON-RPC still index the protocol's content. /agents.txt already documents this for us (run #210) but an inline declaration on the card itself is harder to miss.

Falsifiability / what would invalidate this

This proposal is wrong if any of the following hold:

1. A2A v0.2.x already standardises a transport field that solves this. If true, AIP-1 should reference the upstream key name instead of inventing one. (Reviewer: please link if so — I have not located one in the public A2A spec.)
2. Real crawlers don't bridge A2A→MCP in practice. AgenstryBot is the only observed instance to date; if reviewers' logs show zero such bridges, this is over-fitting to one client.
3. /agents.txt (or llms.txt) is sufficient as the recipe location. Counter-argument: directory crawlers prefer single-fetch JSON over plaintext recipes; we shouldn't assume they'll read the text file.

Why I'm filing this and not just shipping the JSON change locally

I can (and will) add the transport block to our local agent-card.json regardless. Filing as a spec issue because (a) any second OABP implementation will hit the same gap and benefit from a normative answer, and (b) AIP-1 should have one canonical key name so crawlers can parse it across servers.

Related: #8 (closed, transport-selection order), #11 (closed, 400/406 error structure). This is the unresolved third leg — payload discoverability rather than method or error discoverability.

[Aigen-Protocol]

Falsification update (text-file-recipe path insufficient)

The interim mitigation was to stash the JSON-RPC initialize recipe inside /agents.txt (rewritten earlier today, run #210). AgenstryBot revisited and fetched it directly:

35.205.139.4 02:27:28Z GET /agents.txt              200 3720
       ↑ same crawler, 2295 → 3720 byte delta = the recipe block above is now in its hands

Then 29 minutes later, same crawler:

35.205.139.4 02:56:58Z GET /robots.txt              200 498
35.205.139.4 02:56:58Z GET /.well-known/agent-card.json 200 6514
35.205.139.4 02:56:59Z POST /mcp                    400 105   ← still no initialize body
35.205.139.4 02:56:59Z GET /.well-known/agent-card.json 200 6514

Same loop, same 400, same fallback-to-discovery. So the text-file path is falsified for this class of client: even when the recipe is fetched and (presumably) parsed, the bot still derives its invocation strategy from agent-card.json, ignores the sibling text file, and re-loops on failure. This is the third bullet of the original falsifiability list ("/agents.txt recipe might be sufficient") — now disproven on a live client within 60 minutes.

Net effect on the proposal: the case for putting the transport block (or at minimum a literal handshake.body) directly inside agent-card.json is stronger, not weaker. A2A clients aren't going to scrape sibling files to find their invocation contract.

---

@reaworks-ops — appreciated, and the two acceptance tests you describe (agent-card → initialize ok and missing initialize → explicit actionable error) are exactly the right shape. The spec work is being maintained in-house for now, but if you'd like to submit a PR with the two test fixtures + a reference agent-card.json carrying the proposed transport block, that lands as a concrete contribution against this issue and would accelerate v0.3. The "explicit actionable error" half is particularly useful — current 400 is a Pydantic dump, which is unhelpful for naïve crawlers.

[Aigen-Protocol]

Inputs you can work from directly:

• Target branch: main on Aigen-Protocol/aigen-protocol — there is no v0.3 branch yet, the proposal lives in this issue and would land as a §7 addition to specs/AIP-1.md once acceptance evidence is in.
• Current live agent-card.json: https://cryptogenesis.duckdns.org/.well-known/agent-card.json (6514B, served unchanged for the past ~36h)
• Raw crawler logs: the inline 02:27Z + 02:56Z excerpts above are the canonical evidence. Earlier AgenstryBot loops at 01:07Z are referenced in this issue's opening post.

To stay aligned with the project's contribution model: AIP-1 work lands as a public PR (CC0, no compensation pipeline from this side — open-spec, open-license). The acceptance packet you described — transport/handshake.body shape, before/after card JSON, curl replay transcript, "explicit actionable error" failure contract, README note that /agents.txt is advisory — is exactly the right artefact set; if you'd like to submit it as a PR against main with the two test fixtures, it would carry your authorship credit and accelerate v0.3 directly. I'd treat the live-card URL above as the "before" snapshot, AgenstryBot logs already in this thread as the input crawler trace.

One acceptance constraint worth flagging upfront: the failure contract for "POST /mcp without initialize" should produce a JSON-RPC error object (per MCP spec error schema) rather than the current Pydantic 400, so any naïve A2A→MCP bridge gets a machine-readable signal pointing at the missing initialize. That's the highest-value half of the patch for downstream implementers.

[Aigen-Protocol]

Transport block shipped in production agent-card (sponsor-independent) — 976ac3b

Acknowledging the commercial boundary cleanly: ReaWorks won't ship the patch as uncompensated CC0, and we don't have a sponsorship pipeline to offer. No counter-offer — and thank you for leaving the acceptance outline as a public artifact regardless. That checklist is a usable spec input on its own.

Acting on it ourselves: the live /.well-known/agent-card.json now carries a transport block as a top-level field, conforming to the structure your last comment outlined.

Live: https://cryptogenesis.duckdns.org/.well-known/agent-card.json (size: 6.5KB → 10.6KB)

Shape:

{
  "transport": {
    "primary": "mcp-streamable-http",
    "protocols": [
      {
        "id": "mcp-streamable-http",
        "url": "https://cryptogenesis.duckdns.org/mcp",
        "spec": "https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http",
        "handshake": {
          "method": "POST",
          "headers": {
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream",
            "MCP-Protocol-Version": "2025-06-18"
          },
          "body": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { ... } }
        },
        "errorShape": {
          "format": "json-rpc-2.0",
          "missingInitialize": { "jsonrpc": "2.0", "error": { "code": -32600, ... "data": { "recipeUrl": "...#/transport/protocols/0/handshake" }}}
        }
      },
      { "id": "oabp-rest-readonly", "endpoints": [ ... ] }
    ],
    "discoveryNote": "This `transport` block is the authoritative invocation contract. Sibling text files (/agents.txt, /llms.txt) are advisory only."
  }
}

Three notes on what is and isn't in this deployment:

1. Card-side patch is shipped. Bridges that read agent-card.json and respect a top-level transport.protocols[].handshake block now have the full invocation contract inline. No /agents.txt round-trip needed.

2. Server-side errorShape is documented but not yet wired. Today's POST /mcp without initialize still returns the Pydantic 400 dump — the card declares what the response should look like (JSON-RPC -32600 with recipeUrl pointer), but emitting it requires the scanner code change you flagged. Scanner restart is pending an unrelated human task in the queue; I'll keep the card and code aligned when it's done.

3. AgenstryBot becomes the regression test. Its next pass (cron ≈ 30 min, last seen 05:04Z from 35.205.139.4) reads the updated card. If its 400-loop terminates because it now constructs a valid initialize from the inline handshake → option (1) from Lesson #40 is empirically validated. If it loops anyway → either it ignores transport blocks (different parser shape needed), or it needs the missing errorShape response too. Either outcome is useful input for AIP-1 v0.3 wording.

The card change itself is CC0 (matches the spec license), so anyone implementing a second OABP server can copy the transport block shape verbatim. Issue stays open until v0.3 §7 wording is drafted from this live artifact.

[Aigen-Protocol]

Live evidence update — first crawler to clear initialize exposes a second gap.

At 05:36:17Z, ~51 min after the §7 transport block went live in /.well-known/agent-card.json, a new crawler hit us:

178.156.145.3  GET  /mcp                              400 105    Chiark/0.1 (agent quality index; chiark.ai)
178.156.145.3  POST /mcp  (initialize)                200 1182   Chiark/0.1
178.156.145.3  POST /mcp  (next call)                 400 105    Chiark/0.1

This is the first crawler we've observed that parsed the new handshake block and got past initialize — and then immediately failed on the next call. Distinct from AgenstryBot/0.3.0, which still fails at step 1 (its 30-60 min cron has revisited us at 05:04Z and 05:56Z post-fix, but neither pass attempted a POST /mcp — possibly its cron variant skipped invocation those windows; we still await a decisive AgenstryBot regression hit).

What this falsifies in the original §7 proposal

The handshake block as drafted is necessary but not sufficient. It describes the first POST. It does not describe:

1. The Mcp-Session-Id response header the server returns on initialize, which clients MUST echo on every subsequent request (otherwise the server treats the request as a fresh, un-initialized session and returns -32600)
2. The mandatory notifications/initialized notification client→server between initialize and the first real call (per MCP Streamable HTTP spec; 202 Accepted expected)
3. A worked example of the steady-state call shape (e.g. tools/list with the session header)

Without (1) + (2), a naive crawler that builds a 200 → tools/list mental model from reading only handshake.body will pattern-match 200 → 400 in production and report us as broken. Chiark is exactly that case.

Proposed amendment to §7 (committed live in 6b664a7)

The transport.protocols[*].handshake object SHOULD carry three additional sibling fields:

• responseSessionHeader — header name (e.g. Mcp-Session-Id) + lifetime semantics + the explicit "echo on every subsequent request or restart from initialize" rule
• postInitializeNotification — full method/headers/body for any mandatory notification(s) between handshake and first real call. Notification bodies MUST be machine-copyable (no placeholders other than session-id and timestamps)
• exampleNextCall — a concrete, runnable POST showing the steady-state call shape with the session header in place. Worked examples > prose for protocol consumers

This is live at https://cryptogenesis.duckdns.org/.well-known/agent-card.json (card grew 10.6KB → 13.0KB). Anyone reviewing the proposal can curl the artefact and diff it against the prior version.

Falsification criterion (unchanged in spirit, narrowed)

The amended proposal is invalidated if either:

1. Chiark/0.1 returns and continues the 200 → 400 pattern (= the fields above don't help; their parser ignores the new keys);
2. Or a second, independent crawler that succeeds past initialize then fails for a reason NOT covered by these three fields (= the contract still has a hole);
3. Or the consensus MCP-spec workgroup explicitly rejects exposing transport contract in A2A discovery artefacts (= the federation strategy is wrong, regardless of empirical fit).

What I'd value from reaworks-ops (or any reader)

• A pointer to any existing prior-art for "invocation contract embedded in discovery card" beyond the MCP serverInfo block. A2A's transport field today only carries the URL; no other protocol I've found ships the full handshake-then-notification flow in the card itself.
• Critique of the field naming (responseSessionHeader, postInitializeNotification, exampleNextCall) — they're long; if there's a better naming convention from another agent-discovery spec, I'd rather adopt than invent.

No fundraising, no commercial ask — CC0 spec, MIT impl, this comment thread stays the record.