Working with the MCP API - cturner8/kube-mcp GitHub Wiki

To start the MCP API server locally in out-of-cluster mode:

cd api
go mod tidy
go run . \
  --base-url "http://localhost:9000" \
  --oidc-issuer-url "https://auth.localhost:8443" \
  --oidc-client-id "your-client-id" \
  --out-of-cluster

This runs the API with minimal configuration. The server will:

• Listen on port 9000 by default
• Use your local kubeconfig (~/.kube/config)
• Require OIDC authentication for tool requests
• Enable out-of-cluster mode for local development

The MCP API server can be configured via CLI flags, environment variables, or both. CLI flags take precedence over environment variables.

All environment variables must be prefixed with KUBE_MCP_. For a comprehensive reference of all configuration options, see Configuration Options.

For additional configuration options, see Configuration Options.

The MCP Inspector is a web-based debugging tool that helps you interact with the MCP server and test your tools.

Start the inspector using npm:

# Start the inspector (opens automatically in your browser)
npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:9000/mcp

Once the inspector is open:

1. Verify transport and connection: Ensure "HTTP" transport is selected and Connection Type is set to "Via Proxy"
2. View tools: The left panel shows all available tools discovered from the server
3. Execute tools: Click on a tool to see its parameters and execute it
4. View responses: Results and logs appear in the right panel

The MCP Inspector supports OAuth 2.0 authentication flow when your MCP server implements Protected Resource Metadata (PRM).

Modern MCP clients (including the inspector) can authenticate without pre-configured tokens by discovering authentication requirements from the .well-known/oauth-protected-resource endpoint.

When starting your server with OIDC configuration, the PRM endpoint is automatically available:

# Your server must have:
# --oidc-issuer-url <your-issuer>
# --oidc-client-id <your-client-id>
# --base-url <your-base-url>

The inspector will then:

1. Discover authentication requirements from PRM
2. Initiate an OAuth 2.0 flow
3. Prompt you to authenticate with your identity provider
4. Use the obtained token for authenticated requests

To test the OAuth flow in the inspector:

1. Ensure the server is running with proper OIDC configuration
2. Open the inspector in your browser
3. The authentication UI should automatically appear if PRM is properly configured
4. Follow the prompts to authenticate with your identity provider
5. After authentication, tool requests will include your access token

Proxy mode does not apply to authentication requests, CORS must be enabled to ensure reachability from the inspector.

If PRM discovery doesn't work or you need to use a static token:

1. Obtain a valid JWT from your identity provider
2. In the inspector, look for authentication options (usually in settings or headers)
3. Add an Authorization: Bearer <your-token> header
4. Tool requests will now include your token

To test with a token manually:

# Get a token from your OIDC provider, then test the API directly:
curl -H "Authorization: Bearer <your-token>" \
  http://localhost:9000/mcp/resources

You can restrict which tools are available to test permissions and access control.

Allow only specific tools:

go run . \
  --base-url "http://localhost:9000" \
  --oidc-issuer-url "https://auth.localhost:8443" \
  --oidc-client-id "dev-client-id" \
  --out-of-cluster \
  --allowed-tools "list_pods,get_pod,list_deployments,get_deployment"

Or via environment variable:

export KUBE_MCP_ALLOWED_TOOLS="list_pods,get_pod,list_deployments,get_deployment"
go run .

With this configuration, only the specified tools appear in the inspector.

Disallow specific tools:

go run . \
  --base-url "http://localhost:9000" \
  --oidc-issuer-url "https://auth.localhost:8443" \
  --oidc-client-id "dev-client-id" \
  --out-of-cluster \
  --disallowed-tools "list_secrets,get_secret,list_config_maps,get_config_map"

Or via environment variable:

export KUBE_MCP_DISALLOWED_TOOLS="list_secrets,get_secret,list_config_maps,get_config_map"
go run .

Note: You must use either --allowed-tools or --disallowed-tools, not both.

After starting with tool restrictions:

1. Open the inspector
2. Verify that only the allowed/configured tools appear in the tool list
3. Attempt to use a restricted tool (it should be unavailable)
4. Check logs for any permission-related messages

• Debugging - Learn how to troubleshoot issues with the MCP API using the inspector and logging techniques
• Configuration Options - Complete reference for all configuration settings
• Authentication and Authorisation - Detailed authentication setup and OAuth 2.0 configuration
• Development Environment - Setting up your local development environment
• Troubleshooting - Solutions to common problems encountered during development