SEP: MCP Agent Discovery Extension - #22
Conversation
Define optional two-stage agent discovery with a compact roster, scoped tool schemas, and unchanged tools/call execution. Document extension negotiation, wire types, discovery TTLs, compatibility, security considerations, and the experimental Python SDK reference. Leave notifications, pagination, and error semantics open for WG review.
madhaviai
changed the title
|
@LucaButBoring, can you begin reviewing the above SEP |
| Many agent systems address this by giving a supervisor a concise roster of specialists | ||
| instead of every leaf tool. MCP can provide the same discovery benefit without defining | ||
| how agents reason, execute, retain state, or communicate. A server can describe logical | ||
| agents and their scoped tool sets while preserving the existing MCP execution model. | ||
|
|
||
| The desired user experience is simple: users make ordinary requests, while the host | ||
| performs discovery and routing automatically. The additional discovery steps are host | ||
| plumbing and are not exposed as actions the user must invoke. |
There was a problem hiding this comment.
I think this is good, but to make it stronger, I would also note that many frameworks already support subagents in some capacity (give examples, including Deep Agents), and this is intended to plug directly into that existing host feature.
| The immediate goal is to establish an interoperable foundation for agent-oriented | ||
| capabilities in MCP. The first version focuses on discovery and progressive disclosure: |
There was a problem hiding this comment.
While true, it is also worth noting the immediate usability; the way this is phrased raises the question of if it's actually intended to be used on its own, or if it only becomes useful when other capabilities build on top of it. I would frame this as something that addresses an actual use case, and then note that additional capabilities can build on this as a strong foundation, I think.
We should consider even dropping the "first version" phrasing; SEPs should be written such that they stand alone and don't presume definite future changes (referring to indefinite "future capabilities" is sufficiently open-ended, referring to a definite "first version" that implies subsequent versions is not).
There was a problem hiding this comment.
Updated this section to state the immediate standalone use case and removed the “first version” wording. I’ve kept the broader evolution analysis in research PR #20, referenced as supporting research, so the SEP remains focused. If a specific research conclusion belongs in the Rationale, I’m happy to bring it across.
| performs discovery and routing automatically. The additional discovery steps are host | ||
| plumbing and are not exposed as actions the user must invoke. | ||
|
|
||
| ## Goals and Direction |
There was a problem hiding this comment.
Probably remove this header, it's not part of the template and the content under this reads as a natural continuation of the Motivation section already.
| The direction is to: | ||
|
|
||
| - give hosts a consistent way to discover and route to agent capabilities; | ||
| - reduce context size and routing ambiguity through progressive disclosure; | ||
| - preserve interoperability across different agent frameworks and implementations; | ||
| - support cacheable discovery with clear freshness behavior; | ||
| - remain optional and backward compatible for clients and servers that do not implement | ||
| the extension; | ||
| - create a stable foundation that can accommodate additional agent requirements without | ||
| prematurely prescribing one orchestration architecture. |
There was a problem hiding this comment.
This section is a bit generic, several of the points here (cacheability, backwards-compatibility) are more or less assumed by default in certain contexts and don't benefit from being stated explicitly here. I think the SEP is stronger without this list, but if you do keep it, reduce it to the strongest forms of maybe three key points.
| negotiation mechanism. Supporting the base MCP protocol does not imply support for agent | ||
| discovery. |
There was a problem hiding this comment.
Supporting the base MCP protocol does not imply support for agent
discovery.
This is redundant with the stronger normative requirements beneath this.
| ### Same-Server Tool Execution | ||
|
|
||
| The selected tool is called on the same MCP server through `tools/call`. This avoids | ||
| requiring one deployment, connection, authentication flow, or transport hop per logical | ||
| agent. It also preserves existing tool handlers, middleware, authorization, and result | ||
| semantics. |
There was a problem hiding this comment.
I think the focus here should be on preservation of existing semantics and server design flexibility; the issues in the second sentence don't seem to follow from the premise of the first.
| ### Two-Level Discovery | ||
|
|
||
| Returning agent cards separately from tool schemas keeps the first routing context small. | ||
| If `agents/list` returned every tool schema, hosts would receive nearly the same payload as | ||
| flat tool discovery and the extension would not provide meaningful progressive | ||
| disclosure. | ||
|
|
||
| `agents/get` forms the second level because a host needs complete MCP `Tool` definitions | ||
| before it can expose or invoke the selected tools. This preserves MCP's existing schema | ||
| and execution model rather than introducing a second representation of tools. |
There was a problem hiding this comment.
I think there should be an explanation here for why we aren't making tools/list the single source of truth for tool definitions (it's not because of context bloat). Your comment here has points that might justify this decision.
| **Resources as agent cards.** A resource can describe an agent, but it does not establish | ||
| a standard relationship between that description and a bounded set of callable tools. | ||
| Hosts may still load both the resource and the full tool catalog. |
There was a problem hiding this comment.
There's nothing stopping us from just defining some special kind of resource that has the info we need, I think a stronger point against this might be that it could mislead agents that don't support the extension, maybe.
| **Selector or mega-tools.** A server can expose one tool that privately routes to internal | ||
| agents or APIs. This reduces the visible tool catalog, but hides specialist tool schemas | ||
| and makes composition, authorization, and interoperability dependent on a custom tool | ||
| contract. |
There was a problem hiding this comment.
This seems like an irrelevant consideration, this would be no different from just a regular agent behind a tool, so we should discuss that as an alternative instead of a special case of it.
| **Skills or server cards.** Skills and server metadata can provide useful instructions or | ||
| descriptions, but do not by themselves progressively disclose a selected subset of MCP | ||
| tool schemas. |
There was a problem hiding this comment.
They could, though, we could propose this. We should explain why this would be a bad option even if we proposed exactly what we needed as an extension to these, not just say that they don't have these things today.
| } | ||
| ``` | ||
|
|
||
| Each agent name **MUST** be unique within the roster visible to the requesting client. |
There was a problem hiding this comment.
One thing I couldn't find in the draft, are tool names required to be unique server-wide?
Agent names get a uniqueness requirement here, and the same tool might appear in multiple agents, but nothing says two different tools can't ship under the same name in different agents. Since tools/call still addresses tools by bare name, scoping only exists at discovery time. At execution time it's one flat namespace, resulting in a collision and unexpected behavior .
| 3. **Error handling** — Which existing MCP/JSON-RPC errors should apply to an unknown | ||
| agent, invalid agent request, missing extension support, or an agent definition that |
There was a problem hiding this comment.
Suggestion for the error contract ,these two failures should be distinguishable even if they share the same error code. Unknown agent usually means my cached roster went stale, so the fix is re-list and retry. Agent referencing unavailable tools is a server-side bug, retrying won't help. We run agent platforms behind a gateway and errors that tell the caller which of these two situations they're in is exactly the useful data for oncall
3 participants
Summary
This PR introduces an Agents WG incubation draft for an MCP Agent Discovery extension.
The proposal defines a two-stage discovery flow:
The design uses formal extension negotiation and standard MCP cache metadata for discovery freshness. It does not introduce a separate agent execution protocol or require models to run inside MCP servers.
Motivation
Large, diverse tool catalogs increase context size and make routing more ambiguous. Agent-first discovery provides progressive disclosure while preserving existing MCP tool definitions and execution behavior.
Supporting work
The SDK implementation is experimental and currently uses
capabilities.experimental.agents. It is included as a feasibility prototype, not yet as a conforming implementation of this draft.Open questions for WG review
Review request
This is an incubation draft in the Agents WG repository before any formal submission to the main MCP specification repository.
Luca has agreed to sponsor the draft. Feedback is especially welcome on the initial wire shape, scope, and open questions.