Skip to content

MCP Server Validation Errors: Optional fields incorrectly required in response schemas

Summary

The MCP GitLab server is failing validation for multiple endpoints due to incorrect schema validation that treats optional/nullable fields as required. This affects core functionality for CI/CD pipeline debugging.

Bug Report 1: get_merge_request validation failure

Expected Behavior:

  • Should return merge request details successfully
  • Optional fields should be allowed to be null/undefined

Actual Behavior:

  • Returns MCP error -32603 with validation errors for optional fields

Repro Steps:

  1. Call mcp__gitlab-git-haley-io__get_merge_request
  2. Use parameters: project_id: "john/melange-mvp-template", merge_request_iid: 15

Error Log:

MCP error -32603: Invalid arguments: should_remove_source_branch: Expected boolean, received null, force_remove_source_branch: Expected boolean, received null, pipeline.tag: Required, pipeline.user: Required

Bug Report 2: get_pipelines validation failure

Expected Behavior:

  • Should return list of pipelines with their current status
  • Nested objects with null fields should be handled gracefully

Actual Behavior:

  • Returns MCP error -32603 with validation errors for required nested fields

Repro Steps:

  1. Call mcp__gitlab-git-haley-io__get_pipelines
  2. Use parameters: project_id: "john/melange-mvp-template", per_page: 5

Error Log:

MCP error -32603: Invalid arguments: 0.tag: Required, 0.user: Required, 1.tag: Required, 1.user: Required, 2.tag: Required, 2.user: Required, 3.tag: Required, 3.user: Required, 4.tag: Required, 4.user: Required

Bug Report 3: get_jobs validation failure

Expected Behavior:

  • Should return list of CI jobs with their status
  • Optional nested fields (artifacts, runner details) should be nullable

Actual Behavior:

  • Returns MCP error -32603 with validation errors for optional nested fields

Repro Steps:

  1. Call mcp__gitlab-git-haley-io__get_jobs
  2. Use parameters: project_id: "john/melange-mvp-template", per_page: 5

Error Log:

MCP error -32603: Invalid arguments: 0.artifacts.0.file_format: Expected string, received null, 0.runner.name: Expected string, received null, 1.artifacts.0.file_format: Expected string, received null, 1.runner.name: Expected string, received null, [pattern continues...]

Root Cause Analysis

The issue appears to be in the response schema validation where:

  1. Optional fields are treated as required: Fields like should_remove_source_branch, force_remove_source_branch should be optional
  2. Nested object validation is too strict: Fields like pipeline.tag, pipeline.user, artifacts.file_format, runner.name should allow null values
  3. Array element validation fails on null: When GitLab API returns null values in arrays, the schema validation rejects them

Impact

  • Critical: Cannot debug CI pipeline failures through MCP server
  • Blocks development: Must fall back to direct GitLab API or glab CLI
  • Affects core workflows: Pipeline monitoring, job log analysis, MR status checking

Suggested Fix

Update the response schemas to:

  1. Mark optional fields as optional: true or allow null values
  2. Handle nested object validation more gracefully
  3. Allow null values in array elements where GitLab API permits them

Environment

  • GitLab CE Self-hosted at git.haley.io
  • Project: john/melange-mvp-template (ID: 2)
  • MR #15 with multiple failed CI pipelines
  • Using Claude Code with MCP GitLab server integration