Chronosphere MCP Server

MCP server for Chronosphere. Serves tools for fetching logs, metrics, traces, events as well as select entities.

This project uses semver for release versions. We have not graduated to 1.0, so breaking changes may occur for minor version bumps.

MCP config with popular hosts (claude desktop, cursor)

Remote Server

The easiest way to use the MCP server is using our remote hosted server:

Auth

You can use either a Chronosphere API token or OAuth with the Chronosphere MCP server. To use MCP with OAuth, the MCP client must support OAuth.

OAuth support is new and have not been tested with all clients. If it does not work for you, please raise the issue to Chronosphere support in slack with the following information:

1. MCP client you’re using (e.g. VS code, codex, cursor, etc)
2. What steps you took to attempt authentication
3. What error you’re seeing.

Header-based configuration

Some MCP hosts let you attach custom HTTP headers to requests sent to the MCP server. The Chronosphere MCP server supports the following user-facing headers.

Disable tools (X-Chrono-MCP-Disable-Tools)

Use this header to hide specific tools from the tool list exposed to your MCP client.

• Format: comma-separated list of MCP tool names (the Tool Name column in the Available Tools table)
• Example value: query_logs_range,render_prometheus_range_query
• Notes: whitespace is ignored; unknown tool names are ignored

Enable writes (X-Chrono-MCP-Enable-Writes)

Write tools are hidden and cannot be called by default. The server operator must first permit writes with server.tools.enableWrites: true. HTTP and SSE clients must additionally set this header to true; the header cannot override a disabled server setting. Other values do not enable writes.

Stdio has no request headers, so the server setting alone enables writes for that transport. The Chronosphere credentials used by the server must still authorize the underlying API operation.

Cursor/VSCode

{
    "mcpServers": {
        "chronosphere": {
            "url": "https://.chronosphere.io/api/mcp/mcp",
            "headers": {
                "Authorization": "Bearer ",
                "X-Chrono-MCP-Disable-Tools": ""
            }
        }
    }
}

This configuration should work for Cursor and VSCode. Leave out the headers section to use OAuth instead of a Chronosphere API token. Remove X-Chrono-MCP-Disable-Tools to expose all tools.

More details for VSCode here and Cursor here

Claude code

Adding chronosphere MCP server to claude code

claude mcp add -t http \
  -H "Authorization: Bearer ${CHRONOSPHERE_API_TOKEN}" \
  -H "X-Chrono-MCP-Disable-Tools: " \
  chronosphere "https://${CHRONOSPHERE_ORG_NAME}.chronosphere.io/api/mcp/mcp"

You can leave out the Authorization header if you are using OAuth. Once you’re in claude type /mcp and select the server to login to trigger the OAuth flow. Remove the X-Chrono-MCP-Disable-Tools header to expose all tools.

More details here

Codex CLI

experimental_use_rmcp_client = true
[mcp_servers.chronosphere]
url = "https://.chronosphere.io/api/mcp/mcp"
bearer_token = ""

For oauth login, you must enable experimental_use_rmcp_client = true and then run codex mcp login chronosphere

More details here

Gemini CLI

CHRONOSPHERE_ORG_NAME=
CHRONOSPHERE_API_TOKEN=
gemini mcp add chronosphere "https://${CHRONOSPHERE_ORG_NAME}.chronosphere.io/api/mcp/mcp" \
  -H "Authorization: Bearer ${CHRONOSPHERE_API_TOKEN}" \
  -H "X-Chrono-MCP-Disable-Tools: "

# Drop the -H authorization header option if you want to use OAuth.

See Gemini MCP docs for more information.

Building from source

First build the binary

make chronomcp

{
  "mcpServers": {
    "chronosphere-mcp": {
      "command": "/bin/chronomcp",
      "args": [
        "-c",
        "/config.yaml"
      ],
      "env": {
        "CHRONOSPHERE_ORG_NAME": "",
        "CHRONOSPHERE_API_TOKEN": ""
      }
    }
  }
}

Developing

Running the server

Authentication to Chronosphere

This MCP server uses the same authentication methods as chronoctl. By default, the Makefile expects the API token to be stored in .chronosphere_api_token.

Run the mcp server

make run-chronomcp CHRONOSPHERE_ORG_NAME= CHRONOSPHERE_API_TOKEN=

API specs

The API clients in generated/ are built from the Chronosphere public API specs: generated/configv1/spec.json, generated/datav1/spec.json and generated/statev1/spec.json are copies of the monorepo’s exports in src/gateway/publicapiswagger/data/. To update them, sync all three from a monorepo checkout and regenerate:

make swagger-sync MONOREPO=
make all-gen

Debugging MCP Tools

The MCP project provides an inspector useful for directly calling tools APIs. To use:

1. Start the MCP server with streamable http transport make run-chronomcp CONFIG_FILE=./config.http.yaml CHRONOSPHERE_ORG_NAME=
2. Run npx @modelcontextprotocol/inspector node build/index.js.
3. Open http://localhost:6274/#resources , fill in http://0.0.0.0:8081/mcp in the URL, with transport type Streamable HTTP.

Available Tools

Note: To regenerate this table after tool updates, run: make tools-gen && go run scripts/generate-tools-table.go

Releases

We use goreleaser to manage releases.

You’ll need a github token and put it in a .github_release_token file. The token needs at least the following permissions

• content: write
• issues: write

To create a new release, first create a tag:

git tag vX.Y.Z
git push origin vX.Y.Z

Then run the following command to perform a dry run of the release:

```sh
make release-dry-run
# verify the release looks good, then run:
make release