modelcontextprotocol/experimental-ext-interceptors

Watch

Kurt Degiorgio 074dc6cdbd

Rename mcpserver package to extension, remove *mcp.Server field (#11 )

## Summary

- Rename `interceptors/mcpserver/` → `interceptors/extension/`,
replacing the `Server` wrapper with a lightweight `Extension` that can
install itself on any `*mcp.Server`
- Remove the stored `*mcp.Server` field — `Extension` is now a pure
interceptor container with no server reference
- Add `Install(server)` method to register JSON-RPC methods and init
middleware on a given server
- Update `LocalChain(ctx)` → `LocalChain(ctx, server)` to accept the
server as a parameter
- Remove `MCPServer()`, `Run()`, and `NewStreamableHTTPHandler()`
wrapper methods — users interact with `mcp.Server` directly
- Update all examples, tests, and documentation to use the new API

## Why

`mcpserver.Server` pretended to *be* the server — it had `Run()`,
`NewStreamableHTTPHandler()`, etc. — but it could never cover the full
`*mcp.Server` API, so users constantly needed `MCPServer()` to unwrap
it.

`Extension` doesn't pretend to be the server. It's a pure interceptor
container that can install itself on any server (or multiple servers)
on the fly. No stored server reference, no wrapping, no delegation
surface to maintain.

### Before

```go
mcpServer := mcp.NewServer(...)
srv := mcpserver.NewServer(mcpServer)
srv.AddInterceptor(v)
chain, err := srv.LocalChain(ctx)
```

### After

```go
mcpServer := mcp.NewServer(...)
ext := extension.New()
ext.AddInterceptor(v)
ext.Install(mcpServer)
chain, err := ext.LocalChain(ctx, mcpServer)
```

Signed-off-by: Kurt Degiorgio <kdegiorgio@bloomberg.net>

2026-04-30 15:57:18 +01:00

1.9 KiB

Raw Blame History

MCP Interceptors - Go Implementation

Go implementation of the MCP Interceptor Extension based on SEP-1763.

Note: Currently the MCP SDK is vendored, in-order to add the Protocol Methods needed for interceptors.

Quick Start

mcpServer := mcp.NewServer(&mcp.Implementation{
    Name:    "my-server",
    Version: "0.1.0",
}, nil)

// Create an extension and register interceptors.
ext := extension.New()

// Register a validator that blocks dangerous tool calls.
ext.AddInterceptor(&interceptors.Validator{
    Metadata: interceptors.Metadata{
        Name: "block-dangerous",
        Hook: interceptors.Hook{
            Events: []string{interceptors.EventToolsCall},
            Phase:  interceptors.PhaseRequest,
        },
        Mode: interceptors.ModeEnforce,
    },
    Handler: func(_ context.Context, inv *interceptors.Invocation) (*interceptors.ValidationResult, error) {
        raw := inv.Payload.(json.RawMessage)
        var params struct{ Name string `json:"name"` }
        json.Unmarshal(raw, &params)
        // validate the request...
        return &interceptors.ValidationResult{Valid: true}, nil
    },
})

// Install on the server and create a chain for middleware.
ext.Install(mcpServer)
chain, err := ext.LocalChain(ctx, mcpServer)
mcpServer.AddReceivingMiddleware(gomiddleware.Middleware(chain))

mcpServer.Run(context.Background(), &mcp.StdioTransport{})

See examples/ for complete working examples.

Documentation

DESIGN.md — architecture, execution model, integration with the go-sdk.
PERFORMANCE.md — per-request cost model, allocation summary, and optimization notes.
CONFORMANCE.md — SEP conformance status.

Package API documentation is available via go doc:

go doc github.com/modelcontextprotocol/ext-interceptors/go/sdk/interceptors

1.9 KiB Raw Blame History

MCP Interceptors - Go Implementation

Quick Start

Documentation

1.9 KiB

Raw Blame History