Return 403 instead of 404 when MCP server is disabled

What does this MR do?

When the MCP server is turned off, POST /api/v4/mcp and GET /api/v4/mcp returned a plain 404 Not Found. A 404 is ambiguous, so users could not tell it apart from a wrong URL

Why 403 and not 503:

  • lib/api/helpers.rb already states the rule the API follows: time bounded reasons are retryable and use 503 with Retry-After, indefinite reasons use 403. An administrator turning the MCP server off is indefinite, not a temporary outage
  • Gitlab::Metrics.server_error? counts any status at or above 500 as a server error, so a 503 would raise the rails_request error rate for the mcp_server feature category. Gitlab::Metrics.record_duration_for_status? only covers 200 to 499, so a 503 would also drop out of apdex. Any user who tries MCP while it is turned off would burn the error budget for a normal configuration state

Why changing 404 to 403 is acceptable

  • This is a status code change on a Beta feature, not on a stable one.
  • .ai/principles/distilled/rest-api.md allows different rules for beta endpoints, keyed on the route_setting :lifecycle, :beta tag.
  • The MCP server is documented as Beta in doc/user/model_context_protocol/mcp_server.md and mcp_server_troubleshooting.md, but lib/api/mcp/base.rb does not carry that tag yet. Should we add it as a follow-up?
  • The change touches only the response returned when the MCP server is not available to the caller. Both 404 and 403 tell the client it cannot use the feature right now.
Edited by Amr Taha

Merge request reports

Loading
Loading