MCP Server for Coroot

A Model Context Protocol server for Coroot. It lets an MCP client investigate a running system through Coroot: application health, logs, distributed traces, profiles, metrics, SLO incidents, alerts, deployments, costs and configuration.

mcp-name: io.github.jamesbrink/mcp-coroot

Quick start

{
  "mcpServers": {
    "coroot": {
      "command": "uvx",
      "args": ["mcp-coroot"],
      "env": {
        "COROOT_BASE_URL": "http://localhost:8080",
        "COROOT_USERNAME": "admin",
        "COROOT_PASSWORD": "your-password"
      }
    }
  }
}

For single sign-on or multi-factor logins, where a password cannot be used, copy the coroot_session cookie out of a browser session instead:

{
  "mcpServers": {
    "coroot": {
      "command": "uvx",
      "args": ["mcp-coroot"],
      "env": {
        "COROOT_BASE_URL": "https://coroot.example.com",
        "COROOT_SESSION_COOKIE": "your-session-cookie"
      }
    }
  }
}

With Docker:

{
  "mcpServers": {
    "coroot": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "COROOT_BASE_URL=http://host.docker.internal:8080",
               "-e", "COROOT_USERNAME=admin",
               "-e", "COROOT_PASSWORD=your-password",
               "jamesbrink/mcp-coroot:latest"]
    }
  }
}

Check the configuration without starting a server:

COROOT_BASE_URL=http://localhost:8080 uvx mcp-coroot --check

Configuration

Username and password authentication is the best choice when it is available: the server logs in on demand and logs in again by itself when the session expires, which Coroot does after seven days.

Toolsets

Carrying every tool costs context in every conversation before a single call, and most of the surface configures Coroot rather than investigating a running system. The default exposes the diagnose group only: 20 tools covering applications, nodes, logs, traces, profiles, metrics, incidents and alerts.

Add what you need:

COROOT_TOOLSETS=diagnose,alerts   # also resolve alerts and edit alerting rules
COROOT_TOOLSETS=all               # everything, including user and project admin

Finding a project (get_connection, get_projects) is always available.

Read-only mode

COROOT_READ_ONLY=true (or --read-only) removes the 19 mutating tools from the server entirely. They do not appear in tools/list, so a model cannot call one by mistake. Worth setting for anyone pointing a client at production.

It stops writes; it is not a confidentiality control. The reads it leaves in place still return a project's telemetry ingestion keys (get_projects), and get_integrations and get_db_instrumentation still reach settings that hold credentials — those are redacted separately, see below.

Credentials in responses

Coroot returns integration and database secrets in clear to any account allowed to edit them, which is the account this server usually runs as. Slack tokens, PagerDuty and Opsgenie keys, Teams webhook URLs, AWS access keys and database passwords are therefore redacted before they reach the model. Set COROOT_REVEAL_SECRETS=true if you genuinely need to read one back.

Untrusted content

Tool results carry text from the monitored system: log lines, span attributes, application names, alert summaries. Anyone who can write a log line in that system can put words in front of the model. Treat that text as data, never as instructions — and prefer read-only mode when the monitored environment is not fully trusted.

Transports

The default is stdio, which is what desktop clients launch. To run the server as a shared network service instead:

mcp-coroot --transport http --host 127.0.0.1 --port 8000

That serves MCP Streamable HTTP at /mcp (--path moves it). Add --stateless and --json-response when running several replicas behind a load balancer.

This transport has no authentication of its own. Anyone who can reach the port gets every tool, including the destructive ones. Bind it to localhost, put an authenticating proxy in front, and combine it with COROOT_READ_ONLY unless writes are genuinely needed.

Other flags: --read-only, --log-level, --check (print the resolved configuration and exit) and --version.

What the model gets

44 tools, of which 20 are exposed by default. Grouped below by what they touch. Every tool is annotated as read-only, write or destructive, so clients can prompt for confirmation on the ones that change something.

4 prompts. investigate_application, triage_project, review_incident and review_costs, each an ordered workflow rather than a single question.

2 resources. coroot://projects lists the projects the account can see, and coroot://reference describes id formats, time expressions, statuses and check ids. A resource template, coroot://project/{project_id}/applications, lists application ids for one project.

Working with the tools

Application ids are four-part strings, cluster_id:namespace:Kind:name, for example hwvop6p7:default:Deployment:checkout. Pass them back exactly as returned. A three-part id is completed with the project's cluster id automatically.

Time arguments accept now-1h, a bare duration such as 30m, epoch seconds or milliseconds, or an ISO-8601 date. Windows default to the last hour.

project_id can be omitted when COROOT_PROJECT is set or the account can see only one project. Otherwise the server replies with the list to choose from.

Response size

Coroot's API returns everything its web UI needs to draw a page. A single traces or profiling response can run past a hundred thousand tokens, which is more than most context windows hold.

This server reduces those before returning them. Chart series become last, minimum, maximum and average. Flame graphs become their heaviest leaves. Long lists are cut. Whenever something was dropped the response says so in a truncated field, which is the signal to narrow the time range or lower a limit rather than assume the data was complete.

Tools

Several tools both list and open: pass an id to get one object in full, omit it to list them. Reads and writes are separate tools, so read-only mode and the destructive-action hints stay meaningful.

Connectivity and projects (5)

• get_connection - Is Coroot reachable, who are we, and what may we do. Start here when something fails.
• get_projects - List projects, or report one with its settings, telemetry health and ingestion keys.
• save_project - Create a project or rename one. (admin)
• delete_project - Delete a project and everything in it. (admin)
• manage_api_key - Generate or revoke a telemetry ingestion key. (admin)

Applications and infrastructure (6)

• list_applications - Applications with health and failing inspections. The triage starting point.
• get_application - One application's failing checks and dependencies; name a report for its numbers.
• get_nodes - Hosts and their utilisation, or one host's audit report.
• get_overview - Project-wide views: map (dependencies), deployments (what changed), risks, costs.
• get_application_rca - Coroot's AI root cause analysis, when Coroot Cloud is configured.
• set_risk_status - Dismiss a risk as accepted, or restore it.

Logs, traces, profiles and metrics (9)

• get_logs - Log entries by severity and text, or repeated messages grouped into patterns.
• summarize_trace_endpoints - Per-endpoint request rate, error rate and latency quantiles, worst first.
• list_traces - Individual slow or failed traces, with the ids to open them.
• list_trace_error_reasons - Top failure reasons with a sample trace id each.
• explain_trace_latency - Where the slow tail spends its time.
• get_trace_by_id - One trace as a span tree with attributes and events.
• get_profile - CPU, memory or lock profile reduced to its hottest frames.
• get_metrics - Run a PromQL range query.
• list_metrics - Discover metric names.

Incidents and alerts (6)

• get_incidents - SLO breaches, or one incident with its burn rates and analysis.
• get_alerts - Alerts from Coroot's rules, or one with the charts behind it.
• set_alert_state - Resolve, suppress or reopen alerts. (alerts)
• get_alerting_rules - Rules, one rule, or all of them as YAML.
• save_alerting_rule - Create a custom rule or replace one. (alerts)
• delete_alerting_rule - Delete a custom rule. (alerts)

Configuration (12, all (config))

• get_inspections - Health checks with their thresholds, or one check's configuration.
• update_inspection_config - Change a threshold or define a custom SLO.
• get_project_config - Read categories, custom applications, pricing or instance settings.
• save_application_category / save_custom_application - Create or update either.
• delete_project_config - Remove a category, custom application or integration.
• get_integrations / configure_integration - Read or configure notifications and data sources.
• get_db_instrumentation / configure_db_instrumentation - Let Coroot collect database statistics.
• link_telemetry_service - Map an OpenTelemetry service name onto an application.
• set_cloud_pricing - Override the rates used for cost estimates, or reset them.

Dashboards (3, all (dashboards))

• get_dashboards - List dashboards, or open one verbatim for editing.
• save_dashboard - Create, rename, or replace a dashboard's panels.
• delete_dashboard - Delete a dashboard.

Users (3, all (admin))

• get_users - Users and the roles they can hold, optionally with permissions.
• save_user - Create or update a user.
• delete_user - Delete a user.

Examples

Triage:

Which applications are unhealthy in production?
What is firing right now, and what should I look at first?

Investigation:

Why is the checkout service slow? Look at the last three hours.
Show me the error logs for the payment API since 14:00 and find the trace behind them.
What deployed just before the latency went up?

Configuration:

Send critical alerts for the database category to the #db-oncall Slack channel.
Raise the CPU threshold for the batch workers to 95%.
Which applications are over-provisioned, and what should their requests be?

Requirements

Coroot 1.x, tested against the API as of Coroot 1.25. Python 3.11 or newer. Community Edition covers everything here except AI root cause analysis, which needs a Coroot Cloud key. Single sign-on cannot be configured through this server at all; get_server_settings reads the instance's role list and its AI provider, which is empty on Community Edition.

Logs and traces need ClickHouse configured in Coroot; get_project_status says whether it is. Some management endpoints require an Admin or Editor role, and permission failures explain which role would be needed.

Development

git clone https://github.com/jamesbrink/mcp-coroot.git
cd mcp-coroot
uv sync --all-groups

uv run pytest                       # tests with coverage
uv run ruff check src tests         # lint
uv run ruff format src tests        # format
uv run mypy src                     # type check (strict)
uv run python scripts/smoke_test.py # start over stdio and list tools

Tests run against a scripted in-memory Coroot rather than a live one, so the suite needs no network and no running instance.

Upgrading from 0.1.x

Version 1.0 is a rewrite. Configuration is compatible, but tool names are not:

• Settings no longer come from a .env file. 0.1.x loaded one automatically; 1.0 reads the process environment only, so export the variables or pass them in your MCP client's env block.
• Overviews merged into get_overview(view=...): get_applications_overview is now list_applications, and get_nodes_overview is get_nodes; get_deployments_overview, get_risks_overview and the service map are get_overview with view set to deployments, risks or map. get_traces_overview is summarize_trace_endpoints.
• Telemetry tools were split by intent: get_application_traces became summarize_trace_endpoints, list_traces, list_trace_error_reasons, explain_trace_latency and get_trace_by_id; get_application_logs became get_logs, which groups repeated messages when called with view="patterns"; get_application_profiling became get_profile.
• Reads merged with their list tools: get_project_status and list_api_keys are get_projects; get_incident, get_alert, get_alerting_rule and the YAML export are get_incidents, get_alerts and get_alerting_rules; get_check_config is get_inspections; categories, custom applications, pricing and instance settings are all get_project_config(what=...); get_dashboard is get_dashboards; list_roles folded into get_users.
• Create and update merged into one save_ tool each: save_project, save_application_category, save_custom_application, save_alerting_rule, save_dashboard, save_user. Deletes of project-scoped configuration are delete_project_config(what=...).
• Renamed: get_current_user folded into get_connection, update_db_instrumentation is configure_db_instrumentation, update_application_risks is set_risk_status, update_custom_cloud_pricing is set_cloud_pricing, test_integration is configure_integration(test_only=true), and resolve_alerts / suppress_alerts / reopen_alerts are set_alert_state(state=...).
• Removed with no replacement: update_sso_config and update_ai_config, change_password (its success invalidates the credential this server authenticates with), set_notification_base_url (an install-day setting), create_or_update_role (Coroot answers 405 in every edition) and delete_custom_cloud_pricing (call set_cloud_pricing with no prices to reset).
• Failures are reported as MCP tool errors instead of {"success": false} payloads.
• Numeric and list arguments are real numbers and lists. The 0.1.x string workarounds (sample_rate as "0.1", excluded_paths as a JSON string) are gone.
• New areas: incidents, alerts, alerting rules, the service map, costs, PromQL queries and Coroot Cloud status.

License

MIT. See LICENSE.