Add a pluggable server extension API with MCP Apps

Merged
KL
5mo ago
+2598-24

Summary

A pluggable, opt-in extension API for MCPServer (SEP-2133), with MCP Apps as the reference extension. (Tasks was dropped from this PR — see below.)

An extension is a narrow base class (HTTPX Transport/Auth style) whose methods default, so it overrides only what it needs:

class Extension:
    identifier: str
    def settings(self) -> dict[str, Any]: ...           # advertised under capabilities.extensions
    def tools(self) -> Sequence[ToolBinding]: ...        # additive
    def resources(self) -> Sequence[ResourceBinding]: ...
    def methods(self) -> Sequence[MethodBinding]: ...     # new request verbs
    async def intercept_tool_call(self, params, ctx, call_next): ...  # wraps tools/call

You opt in declaratively at construction:

mcp = MCPServer("demo", extensions=[Apps()])

The server applies a closed set of contribution kinds and never hands itself to an extension.

What's included

  • Extensions capability map (ServerCapabilities.extensions, SEP-2133): threaded through get_capabilities/create_initialization_options, advertised over server/discover, checked in Connection.check_capability, and advertised client-side via Client(extensions=...).
  • Apps (io.modelcontextprotocol/ui) — additive: @apps.tool(resource_uri=...) binds a tool to a ui:// resource via _meta.ui.resourceUri; client_supports_apps(ctx) drives the SEP-2133 text-only fallback.
  • A runnable apps example story (in-memory + http-asgi) and a migration-guide entry.

Tasks deferred to a follow-up (SEP-2663)

This PR originally included a Tasks extension, but it was built against the 2025-11-25 in-core Tasks design still carried (types-only) in mcp_types, not SEP-2663 — the extension that actually ships in 2026-07-28. They diverge on nearly every wire-observable detail (server-decided augmentation vs params.task; {tasks/get, tasks/update, tasks/cancel} vs tasks/list+tasks/result; CreateTaskResult / resultType: "task" vs CallToolResult + _meta; execution.taskSupport gating; ttlMs). Rather than ship a spec-violating example, Tasks is removed here and returns as a separate PR rewritten to SEP-2663 with the conformance tasks-* scenarios wired in.

Design notes

The shape is the pluggable-interface pattern: declarative wiring (extensions=[...]), a narrow named interface with defaults, behaviour flowing through as plain values — chosen over a generic plugin framework (no other official SDK builds one) and over an app= kwarg on @tool (which would couple core MCPServer to one extension).

Testing

In-memory Client(server) e2e tests, 100% coverage maintained, strict-no-cover clean, pyright + ruff + markdownlint green. The apps story legs pass.

AI Disclaimer

This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.