Add Python SDK for interceptors

[olaservo]

Adds the Python SDK for authoring interceptor servers and clients, built on the released MCP Python SDK v2 (mcp>=2.0.0,<3).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a draft Python SDK for MCP Interceptors (SEP-2624) on top of the MCP Python SDK v2 beta, including server-side hosting as an extension, invoker-side helpers, and a chain orchestrator, with accompanying tests, docs, and examples.

Changes:

• Introduces interceptor wire types/constants (camelCase-on-wire Pydantic models) and helper functions (hook matching, priority resolution, tolerant invoke-result parsing).
• Adds server-side Interceptors extension plus invoker-side list_interceptors/invoke_interceptor helpers and a multi-server Chain orchestrator.
• Replaces placeholder tests with real unit/integration coverage, plus README/docs and runnable examples.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/sdk/src/mcp_ext_interceptors/types.py	Defines SEP-2624 wire models, constants, and helper functions (priority/hook matching, invoke parsing).
python/sdk/src/mcp_ext_interceptors/interceptor.py	Author-facing interceptor API (Invocation, Validator, Mutator) and hook construction helper.
python/sdk/src/mcp_ext_interceptors/server.py	Hosts interceptors as an MCP v2 Extension implementing list/invoke and capability settings.
python/sdk/src/mcp_ext_interceptors/client.py	Invoker helpers for list/invoke plus capability reading, tolerant of unknown result types.
python/sdk/src/mcp_ext_interceptors/chain.py	Implements multi-server discovery, ordering, and trust-boundary-aware execution model with overrides.
python/sdk/src/mcp_ext_interceptors/init.py	Exposes public SDK surface via re-exports and __all__.
python/sdk/tests/test_types.py	Unit tests for wire serialization, parsing, hook matching/subset checks, and author API enforcement.
python/sdk/tests/test_server_extension.py	Integration tests for hosting on in-memory server, wire shape, errors/timeouts, and capability behavior across modes.
python/sdk/tests/test_client.py	Tests client helper ergonomics and capability parsing.
python/sdk/tests/test_chain.py	Tests chain ordering, parallel validation, blocking/audit semantics, fail-open, atomicity, timeouts, and overrides.
python/sdk/tests/conftest.py	Configures anyio backend for async tests.
python/sdk/tests/test_interceptors.py	Removes the placeholder test file.
python/sdk/README.md	Adds usage/docs for hosting, invoking, chaining, capability notes, and dev workflow.
python/sdk/docs/CONFORMANCE.md	Documents SEP clause-to-implementation mapping and known divergences.
python/sdk/examples/validator_server.py	Example validator server + client driving via Chain.
python/sdk/examples/mutator_server.py	Example mutator server demonstrating phase-specific priority and chain execution.
python/sdk/pyproject.toml	Updates dependencies for MCP v2 beta + adds dev tooling group and uv prerelease config.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated no new comments.

Suppressed comments (1)

python/sdk/src/mcp_ext_interceptors/server.py:233

• anyio.fail_after() raises anyio.exceptions.TimeoutError (AnyIO-specific), which is not guaranteed to be caught by except TimeoutError:. If it isn’t caught, interceptor timeouts will be reported as INTERCEPTOR_MUTATION_FAILED instead of INTERCEPTOR_TIMEOUT, breaking the intended error code behavior (and the test_timeout expectation).

            if params.timeout_ms is not None:
                with anyio.fail_after(params.timeout_ms / 1000):
                    result = await interceptor.handler(invocation)
            else:
                result = await interceptor.handler(invocation)
        except TimeoutError:
            raise MCPError(
                code=INTERCEPTOR_TIMEOUT,
                message="Interceptor execution timeout",
                data={"interceptor": params.name, "timeoutMs": params.timeout_ms, "phase": params.phase},
            ) from None

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated no new comments.

Suppressed comments (2)

python/sdk/src/mcp_ext_interceptors/types.py:53

• INTERCEPTOR_MUTATION_FAILED is used as the general "interceptor execution failed" code (-32603) for both validators and mutators (see server _handle_invoke). The name is misleading for API consumers. Consider introducing a clearer constant (e.g. INTERCEPTOR_EXECUTION_FAILED) and keeping INTERCEPTOR_MUTATION_FAILED as a backward-compatible alias.

# JSON-RPC error codes assigned by the SEP.
INTERCEPTOR_TIMEOUT: Final = -32000
INTERCEPTOR_VALIDATION_FAILED: Final = mcp_types.INVALID_PARAMS  # -32602
INTERCEPTOR_MUTATION_FAILED: Final = mcp_types.INTERNAL_ERROR  # -32603

python/sdk/src/mcp_ext_interceptors/server.py:241

• anyio.fail_after(...) raises TimeoutError, but this except TimeoutError: will also catch a user handler that raises TimeoutError for its own reasons, and incorrectly translate it into an INTERCEPTOR_TIMEOUT. Prefer anyio.move_on_after(...) and check scope.cancelled_caught so only actual deadline timeouts are mapped to INTERCEPTOR_TIMEOUT, while handler-raised TimeoutError continues to surface as an execution failure.

        try:
            if params.timeout_ms is not None:
                with anyio.fail_after(params.timeout_ms / 1000):
                    result = await interceptor.handler(invocation)
            else:
                result = await interceptor.handler(invocation)
        except TimeoutError:
            raise MCPError(
                code=INTERCEPTOR_TIMEOUT,
                message="Interceptor execution timeout",
                data={"interceptor": params.name, "timeoutMs": params.timeout_ms, "phase": params.phase},
            ) from None

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated no new comments.

Suppressed comments (2)

python/sdk/pyproject.toml:22

• This package imports mcp_types (e.g., src/mcp_ext_interceptors/types.py, src/mcp_ext_interceptors/client.py) but mcp-types is not listed as a direct runtime dependency. If mcp ever stops re-exporting/depending on it transitively, installs of this package can fail with ImportError: mcp_types.

Add an explicit mcp-types requirement to dependencies.

dependencies = [
    "mcp>=2.0.0,<3",
    "anyio>=4.9",
    "pydantic>=2.12.0",
]

python/sdk/src/mcp_ext_interceptors/chain.py:351

• ChainExecutionParams.timeout_ms enforces a chain-level deadline, but the per-invocation timeout_ms sent to servers is currently only sourced from InterceptorOverrides. That means a chain timeout does not get communicated to interceptor servers via the SEP timeoutMs field, so remote servers may continue executing after the invoker has timed out.

Consider defaulting each invoke's timeout_ms to params.timeout_ms when no per-entry override is set (and still keeping the chain-level guard).

            config=(params.config or {}).get(entry.interceptor.name),
            timeout_ms=entry.effective_timeout_ms(),
            context=params.context,

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated no new comments.

[jeongukjae]

i think we need to discuss about "both" phase. it's missing in sep, but go and c# have that phase.

experimental-ext-interceptors/csharp/sdk/src/ModelContextProtocol.Interceptors/Protocol/InterceptorPhase.cs

Lines 29 to 34 in 7cf90c9

	/// <summary>
	/// Attribute-only convenience value meaning the interceptor runs on both request and response phases.
	/// The reflection layer expands this into two hook entries; it must not appear on the wire.
	/// </summary>
	[JsonStringEnumMemberName("both")]
	Both,

cc @PederHP @Degiorgio

[PederHP]

Well it doesn't appear on the wire, so I am not sure the SEP needs to mention it for it to exist.