Skip to content

Latest commit

 

History

History
83 lines (64 loc) · 3.4 KB

logging.md

File metadata and controls

83 lines (64 loc) · 3.4 KB

MCP Logging

The server supports the MCP logging capability, allowing clients to receive debugging information via structured log messages.

For Clients

Clients can control log verbosity by sending a logging/setLevel request:

{
  "method": "logging/setLevel",
  "params": { "level": "info" }
}

Available log levels (in order of increasing severity):

  • debug - Detailed debugging information
  • info - General informational messages (default)
  • notice - Normal but significant events
  • warning - Warning messages
  • error - Error conditions
  • critical - Critical conditions
  • alert - Action must be taken immediately
  • emergency - System is unusable

For Developers

Automatic Kubernetes Error Logging

Kubernetes API errors returned by tool handlers are automatically logged to MCP clients. When a tool handler returns a ToolCallResult with a non-nil error that is a Kubernetes API error (StatusError), the server categorizes it and sends an appropriate log message.

This means toolset authors do not need to call any logging functions for standard K8s error handling. Simply return the error in the ToolCallResult and the server handles the rest:

ret, err := client.CoreV1().Pods(namespace).Get(ctx, name, metav1.GetOptions{})
if err != nil {
    return api.NewToolCallResult("", fmt.Errorf("failed to get pod: %w", err)), nil
}

The following Kubernetes error types are automatically categorized:

Error Type Log Level Message
Not Found info Resource not found - it may not exist or may have been deleted
Forbidden error Permission denied - check RBAC permissions for {tool}
Unauthorized error Authentication failed - check cluster credentials
Already Exists warning Resource already exists
Invalid error Invalid resource specification - check resource definition
Bad Request error Invalid request - check parameters
Conflict error Resource conflict - resource may have been modified
Timeout error Request timeout - cluster may be slow or overloaded
Server Timeout error Server timeout - cluster may be slow or overloaded
Service Unavailable error Service unavailable - cluster may be unreachable
Too Many Requests warning Rate limited - too many requests to the cluster
Other K8s API errors error Operation failed - cluster may be unreachable or experiencing issues

Non-Kubernetes errors (e.g., input validation errors) are not logged to MCP clients.

Manual Logging

For custom messages beyond automatic K8s error handling, use SendMCPLog directly:

import "github.com/containers/kubernetes-mcp-server/pkg/mcplog"

mcplog.SendMCPLog(ctx, mcplog.LevelError, "Operation failed - check permissions")

Security

  • Authentication failures send generic messages to clients (no security info leaked)
  • Sensitive data is automatically redacted before being sent to clients, covering:
    • Generic fields (password, token, secret, api_key, etc.)
    • Authorization headers (Bearer, Basic)
    • Cloud credentials (AWS, GCP, Azure)
    • API tokens (GitHub, GitLab, OpenAI, Anthropic)
    • Cryptographic keys (JWT, SSH, PGP, RSA)
    • Database connection strings (PostgreSQL, MySQL, MongoDB)
  • Uses a dedicated named logger (logger="mcp") for complete separation from server logs
  • Server logs (klog) remain detailed and unaffected