[Enhancement] Return structured Kubernetes status for tool execution errors

[jordigilh]

Problem

Kubernetes API errors returned by core resource tools are currently reduced to server-specific text in an MCP CallToolResult with isError: true. For example, the resources_create_or_update and resources_get handlers wrap the underlying Kubernetes error with fmt.Errorf and return it through api.NewToolCallResult.

That loses the machine-readable fields from metav1.Status / apierrors.StatusError, including:

• HTTP status code
• Kubernetes reason (NotFound, Forbidden, Invalid, Conflict, etc.)
• resource and name details
• field causes and other structured details

Downstream clients must parse prose such as field is immutable or not found. This is brittle across server versions, Kubernetes libraries, alternate MCP servers, and gateway formatting.

Proposal

When a Kubernetes operation fails, include a structured Kubernetes Status object in the MCP tool result structuredContent, while retaining the existing text content and isError: true response for backward compatibility.

Example:

{
  "apiVersion": "v1",
  "kind": "Status",
  "status": "Failure",
  "reason": "Invalid",
  "code": 422,
  "message": "...",
  "details": {
    "group": "batch",
    "kind": "Job",
    "name": "example"
  }
}

The structured payload should preserve the original Kubernetes status information where available, including details.causes for validation failures. It should apply consistently to the core resource operations (resources_get, resources_list, resources_create_or_update, resources_delete, and resources_scale).

Compatibility and semantics

• Keep the current human-readable TextContent response for existing clients.
• Keep isError: true for tool execution failures.
• Do not reinterpret resources_create_or_update errors as AlreadyExists: that tool is documented as server-side apply and should retain the actual Kubernetes reason/code. A separate create-only tool would be a distinct enhancement if Kubernetes Create semantics are needed.
• Add tests covering at least NotFound, Forbidden, Invalid, and conflict/status payloads.
• Document the structured error contract so clients do not need to parse server-specific prose.

Downstream motivation

Kubernaut currently needs to translate remote MCP errors into controller-runtime-compatible errors. The downstream hardening is tracked in PR #2435, but a structured upstream response would remove the need for any text-based fallback.

References

• MCP tool result structured content: https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content
• Kubernetes metav1.Status: https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Status

[Cali0707]

@jordigilh I like this idea - just not 100% sure about the schema. Is there any way to make it a bit more token efficient? Structured output already greatly increases our token hit from the server

[jordigilh]

@jordigilh I like this idea - just not 100% sure about the schema. Is there any way to make it a bit more token efficient? Structured output already greatly increases our token hit from the server

Let me take a look

[jordigilh]

Would it work to have the json schema stripped down to just code and reason?

{
  "type": "object",
  "required": [
    "code",
    "reason"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "description": "Kubernetes/API status code"
    },
    "reason": {
      "type": "string",
      "description": "Kubernetes status reason, such as NotFound, Forbidden, Invalid, or Conflict"
    }
  }
}

{
  "code": 404,
  "reason": "NotFound"
}

Alternatively, if you think it might be worth carrying more information, the schema could be expanded to include resource, namespace, name , field and fieldReason:

JSON schema:

{
  "type": "object",
  "required": [
    "code",
    "reason"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "description": "Kubernetes/API status code"
    },
    "reason": {
      "type": "string",
      "description": "Kubernetes status reason, such as NotFound, Forbidden, Invalid, or Conflict"
    },
    "resource": {
      "type": "string",
      "description": "Kubernetes resource identifier, such as jobs.batch"
    },
    "namespace": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "field": {
      "type": "string",
      "description": "Primary invalid field, when applicable"
    },
    "fieldReason": {
      "type": "string",
      "description": "Primary field validation reason, when applicable"
    }
  }
}

Example:

{
  "code": 422,
  "reason": "Invalid",
  "resource": "jobs.batch",
  "namespace": "default",
  "name": "example",
  "field": "spec.template",
  "fieldReason": "FieldValueInvalid"
}

But as a minimum I'd suggest just code and reason and then decide to expand based on feedback. What do you think?

[Cali0707]

IMO having resource/namespace is probably not needed, since most models will already have set that info in the tool input. But will have to think on it a bit more

[jordigilh]

All I need is code and reason. If you're ok with these 2 for now I can raise a PR. Additional fields can be added later on as needed.