MCP Server

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://<org name>.chronosphere.io/api/mcp/mcp",
            "headers": {
                "Authorization": "Bearer <chronosphere api token>",
                "X-Chrono-MCP-Disable-Tools": "<optional list of tools to disable>"
            }
        }
    }
}

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: <list of tools to disable>" \
  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://<org_name>.chronosphere.io/api/mcp/mcp"
bearer_token = "<chronosphere api 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=<your org>
CHRONOSPHERE_API_TOKEN=<your 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: <list of tools to disable>"

# 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": "<PATH/TO/REPO>/bin/chronomcp",
      "args": [
        "-c",
        "<PATH/TO/REPO>/config.yaml"
      ],
      "env": {
        "CHRONOSPHERE_ORG_NAME": "<your org here>",
        "CHRONOSPHERE_API_TOKEN": "<your api token here>"
      }
    }
  }
}

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=<your org here> CHRONOSPHERE_API_TOKEN=<your api token here>

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=<path to monorepo checkout>
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=<your org here>
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

Group	Tool Name	Description
configapi	get_classic_dashboard	Get classic-dashboards resource
configapi	get_dashboard	Get dashboards resource
configapi	get_drop_rule	Get drop-rules resource
configapi	get_mapping_rule	Get mapping-rules resource
configapi	get_monitor	Get monitors resource
configapi	get_notification_policy	Get notification-policies resource
configapi	get_recording_rule	Get recording-rules resource
configapi	get_rollup_rule	Get rollup-rules resource
configapi	get_slo	Get slos resource
configapi	list_classic_dashboards	List classic-dashboards resources
configapi	list_dashboards	List dashboards resources
configapi	list_drop_rules	List drop-rules resources
configapi	list_mapping_rules	List mapping-rules resources
configapi	list_monitors	List monitors resources
configapi	list_notification_policies	List notification-policies resources
configapi	list_recording_rules	List recording-rules resources
configapi	list_rollup_rules	List rollup-rules resources
configapi	list_slos	List slos resources
configapi	update_dashboard	Replace a dashboard identified by slug. Use dry_run to validate without saving.
events	get_events_metadata	List properties you can query on events
events	list_events	List events from a given query
events	list_events_label_values	List values for a given label name
logs	get_log	Get a full log message by its ID. The ID is the unique identifier for the log. Searches the last 7 days unless start or end is set; set them to find an older log.
logs	get_log_histogram	Get histogram of logs from a given query
logs	list_log_field_names	Deprecated: no longer supported, always returns an error. List field names of logs
logs	list_log_field_values	List field values of logs, most frequent first, with the number of matching logs that have each value. To see which fields a log has, pass its logID to the get_log tool.
logs	query_logs_range	Execute a range query for logs. This endpoint returns logs as either timeSeries or gridData. It may return a large amount of data, so be careful putting the result of this direction into context. U...
metric_usage	list_metric_usages_by_label_name	Lists metric usage statistics grouped by label name. Use this to find unused or high-cardinality labels that could be dropped. Response fields: - label_name: The name of the label - dpps: Data poin...
metric_usage	list_metric_usages_by_metric_name	Lists metric usage statistics grouped by metric name. Use this to find unused or underutilized metrics that could be dropped to reduce costs. Response fields: - metric_name: The name of the metric ...
metric_usage	list_rule_evaluations	Lists rule evaluation issues for monitors and recording rules. Use this to identify rules that are failing or having problems. Response fields: - rule_slug: Unique identifier of the rule - rule_typ...
metrics	list_prometheus_label_names	Returns the list of label names (keys) available on metrics that match the given selectors. Use this tool when you need to discover what labels are available on specific metrics or services. Exampl...
metrics	list_prometheus_label_values	Returns the list of values for a specific label name, optionally filtered by selectors. Use this tool when you know the label name and want to discover what values it has across your metrics. Commo...
metrics	list_prometheus_series	Returns the complete time series (full label sets with all key-value pairs) that match the given selectors. Each result shows the exact combination of labels for an active time series. Use this too...
metrics	list_prometheus_series_metadata
metrics	query_prometheus_instant	Evaluates a Prometheus instant query at a single point in time
metrics	query_prometheus_range	Executes a Prometheus PromQL query over a specified time range and returns time series data points as JSON. Supports standard PromQL syntax plus Chronosphere custom functions: - cardinality_estimat...
metrics	render_prometheus_range_query	Evaluates a Prometheus expression query over a range of time and renders it as a PNG image.
monitors	list_alerts	Lists alerts raised by monitors and SLOs in Chronosphere, newest first by default. The five search filters (monitor_slugs, monitor_name_contains, slo_slugs, slo_name_contains and alert_title_contai...
monitors	list_monitor_statuses	Lists the current status of monitors in Chronosphere. Returns every monitor matching the filters with a firing alert. Monitors that are not firing are omitted from the results. Each status carries ...
traces	list_traces	List traces from a given query

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