Connect external AI tools to the MCP server

You can connect external MCP-compatible AI tools (like Claude Code) directly to the SUSE® Observability MCP server. This lets the client use SUSE® Observability read-only tools for topology, events, health, logs, traces, and metrics, as well as built-in prompts and guidance that help the LLM use those tools effectively.

Using AI Assistant generates costs because it invokes external AI models. Larger investigations can take several minutes and may generate significant costs.

Prerequisites

Make sure all of the following are in place:

  • AI Assistant is enabled in your SUSE® Observability installation. See AI Assistant.

  • You have either:

    • a SUSE® Observability user API token copied from the CLI page in the SUSE Observability UI. See CLI: sts.

    • a SUSE® Observability Service token created with sts service-token. See Service tokens.

  • The token has permission to access the data you want the MCP client to read.

The MCP server exposes read-only observability tools and ability to create dashboards. It authenticates to SUSE® Observability using the same token you provide to the MCP client.

MCP endpoint

When AI Assistant is enabled, the Helm chart exposes the MCP server at the /mcp path of your SUSE® Observability base URL.

Example:

https://observability.example.com/mcp

Authentication

For remote MCP clients such as Claude Code, use one of the following authentication methods:

  • user API token in the X-API-Token header, the token can be copied from the CLI page in the SUSE® Observability UI.

  • Service token in the X-API-Key header

Example Service token creation:

> sts service-token create --name my-service-token --roles stackstate-k8s-troubleshooter
✅ Service token created: svctok-aaaaa-bbbb-ccccc-ddddd

All MCP operations are executed in SUSE® Observability with the permissions assigned to that token. The MCP client can only read data that the token is allowed to access.

To follow least-privilege principles, create or use a token that has only the permissions and data access scopes needed for the intended AI workflows.

Configure other MCP-compatible clients

Any MCP client that supports remote HTTP servers can use the same connection details:

Example: Claude Code

Add the SUSE® Observability MCP server as a remote MCP server in your Claude Code configuration:

  • User API token

  • Service token

{
  "mcpServers": {
    "suse-observability": {
      "type": "http",
      "url": "https://observability.example.com/mcp",
      "headers": {
        "X-API-Token": "<your-api-token>"
      }
    }
  }
}
{
  "mcpServers": {
    "suse-observability": {
      "type": "http",
      "url": "https://observability.example.com/mcp",
      "headers": {
        "X-API-Key": "<your-service-token>"
      }
    }
  }
}

After saving the configuration, restart Claude Code or reload its MCP servers.

Verify the connection

Once connected, the MCP client should should discover SUSE® Observability tools such as topology, health, logs, traces, metrics.

Try a simple prompt in Claude Code, for example:

Show me the Kubernetes namespaces visible in SUSE Observability.

If the connection works, Claude Code will call the MCP tools and return data from your SUSE® Observability instance.

Usage

The MCP client uses the available tools and resources when they are relevant to your request. This allows you to ask questions about the applications and infrastructure observed by SUSE® Observability, and to let the agent investigate issues or create dashboards based on the available telemetry.

For example, you can ask:

Give me a top 5 of resource usage in namespace my-app
What are the dependencies of the checkout pod in the sock-shop namespace?
Is there anything in a critical state?
Create a dashboard for the most important metrics of my checkout service

When you ask the agent to create a dashboard, it can use the metrics tools to determine which available metrics make sense for the requested dashboard.

Investigating an incident or problem

The MCP server also includes an investigate prompt that gives the agent detailed guidance on how to use SUSE® Observability to investigate a problem thoroughly. This usually gives better results than only asking the AI to investigate, because the prompt steers the agent to follow a more structured investigation approach.

Use it by explicitly mentioning the prompt together with the subject to investigate. In Claude Code, /investigate auto-completes to /suse-observability:investigate.

/investigate The critical pod in the my-app namespace

Depending on the complexity of the problem and the available information, the investigation can take a few minutes. It finishes with a report of the findings.

Troubleshooting

If the MCP client cannot connect or discover tools, check the following:

  • AI Assistant is enabled, which also deploys and exposes the MCP server.

  • The MCP URL ends with /mcp.

  • The client sends either the X-API-Token or X-API-Key header.

  • The token is valid and not expired.

  • The user or service account behind the token has the required permissions to read the requested data.

  • If you use self-signed certificates, configure your MCP client to trust the certificate. See Self-signed certificates.

For more information about supported tokens, see: