Filter tools/list by toolset and document the feature

Terri Churequested to merge
terrichu/607755-mcp-toolsets-filter into master

What does this MR do and why?

Adds toolset-based filtering to the MCP tools/list endpoint and documents the feature. Consumers send the X-Gitlab-Enabled-Mcp-Server-Toolsets header with a comma-separated list of toolset names to receive only tools from those groups. Names match without regard to case, unrecognized names return 400, the pseudo-value all returns every toolset, and omitting both the toolset and tool headers returns DEFAULT + ALWAYS_ON. The two headers combine via union. Gated by the mcp_toolsets feature flag: with the flag on each tool gains a toolset annotation, and with it off the response payload is unchanged.

References

One logging change ships independently of the feature flag

The unknown-tool warning in API::Mcp::Handlers::ListTools moves from Gitlab::AppLogger to Gitlab::Mcp::Logger, so it writes to mcp.log rather than application_json.log. That is deliberate and not gated by mcp_toolsets, to match the rest of the MCP server logging. The response payload is unaffected, but anything watching application_json.log for Unknown MCP tool names in allowed_tools needs repointing, and disabling the flag does not restore the old destination.

Screenshots or screen recordings

No UI changes.

How to set up and validate locally

  1. Enable the feature flag:

    Feature.enable(:mcp_toolsets)

  2. Send a tools/list request with the toolset header:

     npx -y @modelcontextprotocol/inspector -- env NODE_TLS_REJECT_UNAUTHORIZED=0 mise x -- npx -y mcp-remote https://gdk.test:3443/api/v4/mcp --debug --header "X-Gitlab-Enabled-Mcp-Server-Toolsets: wikis"

  3. Verify only tools from wikis and meta (always-on) toolsets are returned.

  4. Try an invalid toolset name and confirm a 400 response.

     npx -y @modelcontextprotocol/inspector -- env NODE_TLS_REJECT_UNAUTHORIZED=0 mise x -- npx -y mcp-remote https://gdk.test:3443/api/v4/mcp --debug --header "X-Gitlab-Enabled-Mcp-Server-Toolsets: iamnotreal"
    {

"jsonrpc": "2.0", "id": 1, "error": { "code": -32001, "message": "mcp-remote: Error POSTing to endpoint: {"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid params","data":{"params":"Unknown toolsets: iamnotreal. Valid toolsets: meta, core, merge_requests, work_items, repository, ci, duo_agent_platform, wikis, code_security"}},"id":1}" } }

## MR acceptance checklist

Evaluate this MR against the [MR acceptance checklist](https://docs.gitlab.com/development/code_review/#acceptance-checklist).
It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.
Edited by Terri Chu

Merge request reports