MCP Server Authentication Methods Beyond Kubeconfig Files

The MCP server supports token-based authentication using the MCP_AUTH_TOKEN environment variable and X-MCP-AUTH HTTP header, providing a secure alternative to kubeconfig-based cluster access.

The flux159/mcp-server-kubernetes repository implements a Model Context Protocol (MCP) server that exposes Kubernetes operations via HTTP endpoints. While the server relies on standard kubeconfig files for Kubernetes cluster authentication, it implements separate authentication methods to secure its own MCP API endpoints and Server-Sent Events (SSE) streams.

Token-Based Authentication for MCP Endpoints

The primary authentication method for the MCP server itself is a simple token-based scheme that protects the /mcp REST API and /sse streaming endpoints. When the MCP_AUTH_TOKEN environment variable is defined, the server requires all incoming requests to include the X-MCP-AUTH header with a matching secret value.

This authentication layer operates independently of Kubernetes cluster credentials. The MCP_AUTH_TOKEN secures the MCP server's external HTTP interface, while kubeconfig files or service account tokens continue to handle Kubernetes API authentication.

Authentication Middleware Implementation

The token validation logic is implemented as Express middleware and integrated across all public endpoints.

Core Logic in auth.ts

The createAuthMiddleware() function in src/utils/auth.ts (lines 17-45) generates the authentication middleware. This function checks for the presence of MCP_AUTH_TOKEN in the environment:

• If the variable is set, the middleware validates that incoming requests contain the X-MCP-AUTH header with an exact string match to the token value.
• If the variable is not set, the middleware allows all requests to pass through, effectively disabling authentication.

The isAuthEnabled() helper function provides a simple boolean check to determine whether the authentication layer is active.

Endpoint Registration in streamable-http.ts and sse.ts

The authentication middleware is registered for both transport protocols in src/utils/streamable-http.ts (lines 5-14) and src/utils/sse.ts (lines 4-13). This ensures consistent protection across the REST API and Server-Sent Events streaming endpoints.

Configuring Token Authentication

To enable authentication on the MCP server, set the environment variable before starting the process:

export MCP_AUTH_TOKEN="your-secure-random-token-string"
npm start

Clients must then include the token in the X-MCP-AUTH header for every request:

import fetch from 'node-fetch';

const response = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-MCP-AUTH': 'your-secure-random-token-string',  // Required when MCP_AUTH_TOKEN is set
  },
  body: JSON.stringify({
    // MCP request payload
  }),
});

Disabling Authentication

To run the server without authentication (useful for local development or when running behind a reverse proxy that handles authentication), simply ensure the MCP_AUTH_TOKEN environment variable is unset:

unset MCP_AUTH_TOKEN
npm start

When the variable is absent, the middleware created by createAuthMiddleware() automatically permits all requests, and the isAuthEnabled() function returns false.

Summary

• The MCP server supports token-based authentication via the MCP_AUTH_TOKEN environment variable and X-MCP-AUTH HTTP header.
• Authentication is optional; omitting MCP_AUTH_TOKEN disables the security layer entirely.
• The middleware implementation in src/utils/auth.ts validates headers, while src/utils/streamable-http.ts and src/utils/sse.ts apply protection to REST and streaming endpoints.
• This authentication method operates independently of Kubernetes cluster credentials (kubeconfig files), securing only the MCP server's external HTTP interface.

Frequently Asked Questions

What happens if I set MCP_AUTH_TOKEN but forget to send the X-MCP-AUTH header?

The server returns a 401 Unauthorized response. The createAuthMiddleware() function in src/utils/auth.ts checks for the presence and exact value match of the X-MCP-AUTH header when MCP_AUTH_TOKEN is configured. Missing or incorrect values trigger an immediate rejection before the request reaches the MCP handlers.

Can I use multiple authentication tokens or rotate secrets without restarting the server?

No, the current implementation supports only a single static token defined at startup. The MCP_AUTH_TOKEN value is read once when the middleware initializes in src/utils/auth.ts. To change the token, you must restart the server process with the new environment variable value. There is no hot-reload mechanism for secrets.

Is this authentication method related to Kubernetes cluster authentication?

No, the MCP_AUTH_TOKEN mechanism is completely separate from Kubernetes authentication. The token validates access to the MCP server's HTTP endpoints (/mcp and /sse), while Kubernetes cluster operations rely on standard kubeconfig files, service account tokens, or certificate-based authentication configured separately in the cluster context.

Does the MCP server support mTLS or OAuth2 authentication?

No, the repository currently implements only the simple token-based scheme described above. The authentication layer in src/utils/auth.ts does not include middleware for mutual TLS certificate validation, OAuth2 token introspection, or JWT verification. For production deployments requiring these protocols, a reverse proxy (such as Nginx or Envoy) should handle authentication before forwarding requests to the MCP server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}