Commit graph experimental-ext-interceptors/docs
Author SHA1 Message Date
monikaicampbell
bd57572579
Go SDK: Align mode with SEP (#40)
<!-- Provide a brief summary of your changes -->

## Motivation and Context
The SEP-2624 spec defines interceptor modes as "active" | "audit". This
change aligns the Go SDK's interceptor `Mode` value with the SEP spec.

## How Has This Been Tested?
- go test ./... from go/sdk — all packages pass (chain, extension,
integrations/gomiddleware).
- gofmt -l . — clean.
- go vet ./... — clean.

## Breaking Changes
Yes:
- The exported constant interceptors.ModeEnforce is removed and replaced
by interceptors.ModeActive. Callers referencing ModeEnforce must rename.
- The serialized mode value changes from "enforce" to "active". Any
config expecting "enforce" must be updated.

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [x] I have added or updated documentation as needed

## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->

Signed-off-by: monikaicampbell <mcampbell350@bloomberg.net>
2026-08-21 15:56:07 +01:00
Ola Hungerford
39a8f0e073
Docs: Add MCP Dev Summit talk link and fix issues URL typo (#38)
Fixing and adding a couple of links

(btw @PederHP I couldn't find a video for your talk yet but please add a
link if you have one.)
2026-08-19 10:18:42 -07:00
Ukjae Jeong
eebd2ac6a2
Introduce InterceptorOverrides in the chain execution model (#24)
Introduce InterceptorOverrides in the chain execution model to separate
interceptor capability (server-declared) from execution policy
(invoker-declared).

## Why

The SEP currently locks all execution policy (failOpen, priorityHint,
mode) into the interceptor's own definition. This means:
- If an interceptor declares `failOpen: false` but is known to be flaky
in your deployment, you can't make it fail-open without changing the
server
- If you want the same interceptor in audit mode in staging but active
in production, there's no mechanism
- If you want to restrict an interceptor to only `tools/call` even
though it declares support for `tools/call` + `llm/completion`, you have
to invoke it and hope the chain filters correctly
- Priority is fixed by the author, so platform teams can't reorder
interceptors for their deployment topology

In short: the chain interface had no policy layer, making it impractical
for real-world multi-environment deployments.

## Changes

1. New "Capability vs Policy" subsection explaining the two-layer model
2. New `InterceptorOverrides` interface (failOpen, priorityHint, mode,
timeoutMs, hooks)
3. ChainEntry gains `overrides?: InterceptorOverrides`
4. `resolvePriority()` updated to check overrides first
5. Orchestration steps updated — new step 2 "Resolve Policy"
6. New example showing overrides in action (priority override, mode
promotion, fail-open for fragile interceptor)
7. New rationale entry (Design Decision 4) explaining why both layers
exist

Signed-off-by: Ukjae Jeong <jeongukjae@gmail.com>
Co-authored-by: Kurt Degiorgio <Degiorgio@users.noreply.github.com>
2026-07-17 10:55:21 +01:00
Ukjae Jeong
99bc7c9bb0
Align capability key to SEP-2133 extensions format (#25)
Both SDKs now use Capabilities.Extensions with key
"io.modelcontextprotocol/interceptors". Previously C# used the short key
"interceptors" and Go used Capabilities.Experimental. SEP capability
example updated to match.

https://modelcontextprotocol.io/seps/2133-extensions

---------

Signed-off-by: Ukjae Jeong <jeongukjae@gmail.com>
2026-07-06 10:29:21 +01:00
Ukjae Jeong
2b1d10093e
Import revised sep and update the sep number (#21)
Interceptor SEP has been moved from
https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1763
to
https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2624
.
This PR updates the SEP references over the codebase and import revised
SEP

Signed-off-by: Ukjae Jeong <jeongukjae@gmail.com>
2026-06-16 05:16:21 +01:00
Kurt Degiorgio
c9900f02ab
Implement Go interceptor chain (#4)
## Summary

Implements the Go SDK for MCP interceptors — validation and mutation
middleware for any MCP server.

The framework treats interceptors as first-class MCP primitives: they
are registered on an MCP server, discoverable via `interceptors/list`,
and invocable via `interceptor/invoke` — the same JSON-RPC pattern as
tools, prompts, and resources. A chain engine orchestrates execution
across one or more interceptor servers, and an optional go-sdk
middleware integration applies interceptors automatically on every
matching request/response.

## Architecture

**Three-layer design:**

1. **`interceptors`** — Protocol-agnostic core. Defines interceptor
types (validators, mutators), metadata, invocation, wire types, and
results. Zero MCP dependencies.

2. **`interceptors/mcpserver`** — MCP server integration. Wraps
`mcp.Server` to register `interceptors/list` and `interceptor/invoke` as
custom JSON-RPC methods and advertise interceptor capabilities during
`initialize`.

3. **`interceptors/chain`** — Chain engine. Orchestrates execution
across N interceptor servers with trust-boundary-aware ordering,
priority-based mutation sequencing, parallel validation, audit-mode
isolation, and fail-open/fail-closed semantics.

4. **`interceptors/integrations/gomiddleware`** — Optional go-sdk
middleware. Installs on `mcp.Server` via `AddReceivingMiddleware()` to
automatically run the interceptor chain on every matching
request/response.

**Key design decisions:**

- **Trust-boundary ordering** — request phase: validate → mutate;
response phase: mutate → validate. Validation always guards the boundary
crossing.
- **Wire-level invocation** — the chain calls `interceptor/invoke` over
the MCP transport (even in-process via `LocalChain()`), so local and
remote interceptor servers use the same interface.
- **Audit-mode isolation** — audit-mode mutators compute transformations
without applying them. Only audit mutators pay the serialization cost.
- **Concurrency** — validators run in parallel; mutators run
sequentially in priority order.

### Package Structure

| Package | File | Responsibility |
|---------|------|----------------|
| `interceptors` | `interceptor.go` | Enums, Metadata, Interceptor
interface, Validator/Mutator structs, handler types, Invocation |
| `interceptors` | `wire.go` | Wire types: ListParams/Result,
InvokeParams/Result, InterceptorInfo, event/method constants |
| `interceptors` | `priority.go` | Priority with phase-aware resolution
and JSON marshaling |
| `interceptors` | `doc.go` | Package documentation with examples |
| `interceptors/chain` | `chain.go` | Chain engine: discovery,
filtering, sorting, execution orchestration |
| `interceptors/chain` | `result.go` | ExecutionResult, AbortInfo |
| `interceptors/chain` | `doc.go` | Sub-package documentation |
| `interceptors/mcpserver` | `server.go` | MCP server wrapper,
interceptor registry, capability advertisement, `LocalChain()` |
| `interceptors/mcpserver` | `rpc.go` | `interceptors/list` and
`interceptor/invoke` JSON-RPC handlers |
| `interceptors/mcpserver` | `doc.go` | Sub-package documentation |
| `integrations/gomiddleware` | `middleware.go` | go-sdk `Middleware`
that runs the chain on every request/response |
| `integrations/gomiddleware` | `errors.go` | Abort-to-JSONRPC error
conversion |
| `integrations/gomiddleware` | `doc.go` | Sub-package documentation |

### Documentation

- `doc/DESIGN.md` — architecture, execution model, integration with
go-sdk
- `doc/CONFORMANCE.md` — SEP conformance status
- `doc/PERFORMANCE.md` — per-request cost model

### Examples

- `examples/validator` — blocks dangerous tool calls, demonstrates
`WithContextProvider`
- `examples/mutator` — tags tool responses with audit trail

## Vendor: go-sdk v1.4.0 with custom method support

Vendors `go-sdk` with minimal extensions for custom JSON-RPC methods:

- `Server.AddCustomMethod` — registers a handler that bypasses the typed
pipeline
- `ClientSession.CallCustom` — sends raw JSON-RPC calls for custom
methods

These changes are generic (not interceptor-specific) and enable any MCP
extension to define its own JSON-RPC methods.

## TODO

- More integration tests
- Unit tests
- Support wildcards for event interception (separate PR)

---------

Signed-off-by: Kurt Degiorgio <kdegiorgio@bloomberg.net>
2026-04-29 15:29:25 +01:00