From 678a9b6a9d7fbd27ebcf970ece90da15b4de58be Mon Sep 17 00:00:00 2001 From: Yuan Teoh Date: Thu, 25 Jun 2026 16:17:48 -0700 Subject: [PATCH 1/2] feat: add flag to enable draft specs --- cmd/internal/flags.go | 1 + docs/en/documentation/introduction/_index.md | 39 ++++++++++++++++++++ docs/en/reference/cli.md | 3 +- internal/server/config.go | 2 + internal/server/mcp.go | 4 +- internal/server/mcp/mcp.go | 13 +++---- internal/server/server.go | 6 +++ 7 files changed, 57 insertions(+), 11 deletions(-) diff --git a/cmd/internal/flags.go b/cmd/internal/flags.go index b0d4d0f822a8..b63c22fde60d 100644 --- a/cmd/internal/flags.go +++ b/cmd/internal/flags.go @@ -72,4 +72,5 @@ func ServeFlags(flags *pflag.FlagSet, opts *ToolboxOptions) { flags.StringVar(&opts.Cfg.McpPrmFile, "mcp-prm-file", "", "Path to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation.") flags.StringSliceVar(&opts.Cfg.AllowedOrigins, "allowed-origins", []string{"*"}, "Specifies a list of origins permitted to access this server. Defaults to '*'.") flags.StringSliceVar(&opts.Cfg.AllowedHosts, "allowed-hosts", []string{"*"}, "Specifies a list of hosts permitted to access this server. Defaults to '*'.") + flags.BoolVar(&opts.Cfg.EnableDraftSpecs, "enable-draft-specs", false, "Opt-in and test upcoming draft MCP specifications.") } diff --git a/docs/en/documentation/introduction/_index.md b/docs/en/documentation/introduction/_index.md index 521472dc304b..9b84c5389552 100644 --- a/docs/en/documentation/introduction/_index.md +++ b/docs/en/documentation/introduction/_index.md @@ -762,3 +762,42 @@ For more detailed instructions on using the Toolbox Go SDK, see the [README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md). For more details, see the [Agent Skills guide](https://mcp-toolbox.dev/documentation/configuration/skills/). + +## Supported MCP Version + +Toolbox is fully compatible with the Model Context Protocol (MCP) and maintains support for multiple protocol revisions to ensure seamless integration with most MCP clients. + +### Stable Releases +The following official MCP specification versions are currently supported for production use: + +* `2025-11-25` +* `2025-06-18` +* `2025-03-26` +* `2024-11-05` + +{{< notice note >}} +If no protocol version is negotiated or provided, the Toolbox server defaults to +the legacy custom transport protocol established on `2024-11-05`, which does not +require initialization. +{{< /notice >}} + +### Draft Specifications +We actively develop against upcoming protocol specifications. You can opt-in to +test these forthcoming revisions before their official release using the +`--enable-draft-specs` flag during server startup. + +To test these draft specifications, enable the startup flag and use this version +string during negotiation: +* `DRAFT-2026-v1` + +Description: Enables experimental support for upcoming draft MCP specifications, +allowing you to test new schema standards and transport adjustments before they +become stable. + +{{< notice note >}} +Once the draft specification is finalized and released as a stable version, the +draft implementation will be permanently removed. There will be no automatic +redirects or backwards compatibility from the draft spec to the stable release. +Developers must manually migrate their clients to the stable version once it is +available. Do not use this flag in production environments. +{{< /notice >}} diff --git a/docs/en/reference/cli.md b/docs/en/reference/cli.md index 8723d76cb787..209023a4eaae 100644 --- a/docs/en/reference/cli.md +++ b/docs/en/reference/cli.md @@ -13,7 +13,7 @@ description: > | `-a` | `--address` | Address of the interface the server will listen on. | `127.0.0.1` | | | `--disable-reload` | Disables dynamic reloading config. | | | `-h` | `--help` | help for toolbox | | -| | `--ignore-unknown-tools` | Log warnings and skip unknown/unsupported tool types instead of failing to start. | | +| | `--ignore-unknown-tools` | Log warnings and skip unknown/unsupported tool types instead of failing to start. | | | | `--log-level` | Specify the minimum level logged. Allowed: 'DEBUG', 'INFO', 'WARN', 'ERROR'. | `info` | | | `--logging-format` | Specify logging format to use. Allowed: 'standard' or 'JSON'. | `standard` | | | `--mcp-prm-file` | Path to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation for MCP Server-Wide Authentication. | | @@ -35,6 +35,7 @@ description: > | | `--allowed-hosts` | Specifies a list of hosts permitted to access this server to prevent DNS rebinding attacks. | `*` | | | `--user-agent-metadata` | Appends additional metadata to the User-Agent. | | | | `--poll-interval` | Specifies the polling frequency (seconds) for configuration file updates. | `0` | +| | `--enable-draft-specs` | Opt-in and test upcoming draft MCP specifications. | `false` | | `-v` | `--version` | version for toolbox | | ## Sub Commands diff --git a/internal/server/config.go b/internal/server/config.go index bc30426dcb5c..b8e9fd9fd547 100644 --- a/internal/server/config.go +++ b/internal/server/config.go @@ -95,6 +95,8 @@ type ServerConfig struct { UserAgentMetadata []string // PollInterval sets the polling frequency for configuration file updates. PollInterval int + // EnableDraftSpecs allow users to opt-in and test upcoming draft MCP specs. + EnableDraftSpecs bool } type logFormat string diff --git a/internal/server/mcp.go b/internal/server/mcp.go index 17bd09c3ccff..99faf98ee044 100644 --- a/internal/server/mcp.go +++ b/internal/server/mcp.go @@ -813,7 +813,7 @@ func processMcpMessage(ctx context.Context, body []byte, s *Server, protocolVers version = mcputil.LATEST_PROTOCOL_VERSION } - result, err := mcp.ProcessMethod(ctx, version, baseMessage.Id, baseMessage.Method, tools.Toolset{}, prompts.Promptset{}, nil, body, nil) + result, err := mcp.ProcessMethod(ctx, s.enableDraftSpecs, version, baseMessage.Id, baseMessage.Method, tools.Toolset{}, prompts.Promptset{}, nil, body, nil) if err != nil { span.SetStatus(codes.Error, err.Error()) if rpcErr, ok := result.(jsonrpc.JSONRPCError); ok { @@ -843,7 +843,7 @@ func processMcpMessage(ctx context.Context, body []byte, s *Server, protocolVers span.SetAttributes(attribute.String("error.type", metricErrorType)) return "", rpcErr, err } - result, err := mcp.ProcessMethod(ctx, protocolVersion, baseMessage.Id, baseMessage.Method, toolset, promptset, s.ResourceMgr, body, header) + result, err := mcp.ProcessMethod(ctx, s.enableDraftSpecs, protocolVersion, baseMessage.Id, baseMessage.Method, toolset, promptset, s.ResourceMgr, body, header) if err != nil { span.SetStatus(codes.Error, err.Error()) // Set error.type based on JSON-RPC error code diff --git a/internal/server/mcp/mcp.go b/internal/server/mcp/mcp.go index 86328eeece54..16c5ee27cf42 100644 --- a/internal/server/mcp/mcp.go +++ b/internal/server/mcp/mcp.go @@ -19,7 +19,6 @@ import ( "encoding/json" "fmt" "net/http" - "slices" "github.com/googleapis/mcp-toolbox/internal/prompts" "github.com/googleapis/mcp-toolbox/internal/server/mcp/jsonrpc" @@ -47,10 +46,13 @@ func NotificationHandler(ctx context.Context, body []byte) error { // ProcessMethod returns a response for the request. // This is the Operation phase of the lifecycle for MCP client-server connections. -func ProcessMethod(ctx context.Context, mcpVersion string, id jsonrpc.RequestId, method string, toolset tools.Toolset, promptset prompts.Promptset, resourceMgr *resources.ResourceManager, body []byte, header http.Header) (any, error) { +func ProcessMethod(ctx context.Context, enableDraftSpecs bool, mcpVersion string, id jsonrpc.RequestId, method string, toolset tools.Toolset, promptset prompts.Promptset, resourceMgr *resources.ResourceManager, body []byte, header http.Header) (any, error) { switch mcpVersion { case mcputil.VERSION_DRAFT: - return vdraft.ProcessMethod(ctx, id, method, toolset, promptset, resourceMgr, body, header) + if enableDraftSpecs { + return vdraft.ProcessMethod(ctx, id, method, toolset, promptset, resourceMgr, body, header) + } + return jsonrpc.NewUnsupportedProtocolVersionError(id, mcpVersion) case mcputil.VERSION_20251125: return v20251125.ProcessMethod(ctx, id, method, toolset, promptset, resourceMgr, body, header) case mcputil.VERSION_20250618: @@ -63,8 +65,3 @@ func ProcessMethod(ctx context.Context, mcpVersion string, id jsonrpc.RequestId, return jsonrpc.NewUnsupportedProtocolVersionError(id, mcpVersion) } } - -// VerifyProtocolVersion verifies if the version string is valid. -func VerifyProtocolVersion(version string) bool { - return slices.Contains(mcputil.SUPPORTED_PROTOCOL_VERSIONS, version) -} diff --git a/internal/server/server.go b/internal/server/server.go index 50e1a8a3df7b..a45a8b53b416 100644 --- a/internal/server/server.go +++ b/internal/server/server.go @@ -61,6 +61,7 @@ type Server struct { sseManager *sseManager ResourceMgr *resources.ResourceManager mcpPrmFile string + enableDraftSpecs bool } func InitializeConfigs(ctx context.Context, cfg ServerConfig) ( @@ -403,6 +404,11 @@ func NewServer(ctx context.Context, cfg ServerConfig) (*Server, error) { ResourceMgr: resourceManager, toolboxUrl: cfg.ToolboxUrl, mcpPrmFile: cfg.McpPrmFile, + enableDraftSpecs: cfg.EnableDraftSpecs, + } + + if s.enableDraftSpecs { + s.logger.WarnContext(ctx, "Flag --enable-draft-specs is active. Please note that draft specs are subject to breaking changes and will be completely removed (not redirected) once stable MCP specifications are released. Do not use this configuration in production.") } // cors From 2c343f20f96c50a1d6d17b7e4210308df4d65342 Mon Sep 17 00:00:00 2001 From: Yuan Teoh Date: Fri, 26 Jun 2026 17:25:50 -0700 Subject: [PATCH 2/2] implement comment; --- docs/en/documentation/introduction/_index.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/en/documentation/introduction/_index.md b/docs/en/documentation/introduction/_index.md index 9b84c5389552..7aefef33f186 100644 --- a/docs/en/documentation/introduction/_index.md +++ b/docs/en/documentation/introduction/_index.md @@ -796,8 +796,12 @@ become stable. {{< notice note >}} Once the draft specification is finalized and released as a stable version, the -draft implementation will be permanently removed. There will be no automatic -redirects or backwards compatibility from the draft spec to the stable release. -Developers must manually migrate their clients to the stable version once it is -available. Do not use this flag in production environments. +draft implementation will be permanently removed. The flag itself will not be +removed, but its functionality will remain dormant (having no effect on the +server) until a new draft specification becomes available. + +There will be no automatic redirects or backwards compatibility from the draft +spec to the stable release. Developers must manually migrate their clients to +the stable version once it is available. Do not use this flag in production +environments. {{< /notice >}}