agents-wg

This document captures observations from building and operating production deep-agent systems and compares those capabilities against existing MCP primitives and emerging MCP extensions. The goal is not to propose a specific solution, but to understand: Which production agent capabilities are already covered by MCP Which capabilities can be modeled using existing MCP patterns Where protocol gaps may exist for agent-oriented systems Which areas may benefit from future agent definitions, delegation primitives, capability discovery, or orchestration-related extensions

Summary This PR introduces an Agents WG incubation draft for an MCP Agent Discovery extension. The proposal defines a two-stage discovery flow: 1. Retrieve a compact roster containing agent names, descriptions, and capability labels. 2. Retrieve instructions and scoped MCP tool schemas only for the selected agent. 3. Execute tools through the existing MCP tool-calling mechanism on the same server. 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 Research and architecture: agents-wg PR #20 Python SDK prototype: commit ff1f5ac Runnable example and setup instructions The SDK implementation is experimental and currently uses . It is included as a feasibility prototype, not yet as a conforming implementation of this draft. Open questions for WG review Should V1 define agent change notifications, or rely on TTL-based freshness? Does the compact roster require pagination in V1? Which MCP/JSON-RPC errors should apply to agent discovery? 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.

SEP-2133 establishes that extensions evolve independently of the core protocol and SHOULD be versioned, but it leaves the versioning approach unspecified and defers extension dependency declaration to future work. This proposal fills both gaps with a single mechanism. Each extension carries a semantic version in its settings object, and MAY declare the core protocol version its behavior depends on. A difference in the major version means the two peers are incompatible; they negotiate a shared major version through inline retry, as they negotiate a protocol version (see protocol version negotiation). A difference in the minor version is not a conflict: each peer uses the features common to both, and neither rejects the other. A difference in the patch version changes nothing about how the peers interoperate. A new error code, (Unsupported Extension Version), reports a major-version mismatch and tells the client which major versions the server supports, so it can retry against one of them. Motivation and Context SEP-2133 scoped itself narrowly: it defined how extensions are governed, identified, and negotiated, but excluded two compatibility concerns from its scope. Under _Not Specified_, it omits both extension dependencies on core protocol versions and a concrete versioning approach, recording only that "Extensions SHOULD be versioned, but exact versioning approach is not specified here." Three problems follow from those omissions, and each currently surfaces as a runtime failure rather than a negotiated outcome. 1. An extension's protocol-version dependency is undiscoverable. 2. An extension cannot roll out a breaking change of its own. 3. Optional, non-breaking features cannot be advertised. This proposal address all three issues by introducing a versioning scheme and negotiation pattern that can generalize across extensions. Based on #11 from and my previous versioning draft. How Has This Been Tested? Hasn't. Breaking Changes Technically if extensions are already using as a settings field, but as far as I've seen they aren't. Types of changes [ ] Bug fix (non-breaking change which fixes an issue) [x] New feature (non-breaking change which adds functionality) [x] Breaking change (fix or feature that would cause existing functionality to change) [ ] Documentation update Checklist [x] I have read the MCP Documentation [x] My code follows the repository's style guidelines [x] New and existing tests pass locally [x] I have added appropriate error handling [ ] I have added or updated documentation as needed Additional context AI Use Disclosure: Claude wrote this and I made it revise its own work for several hours after I tore it apart.