Skip to main content
This feature is in and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
Cockroach Aegis exposes its analysis of your CockroachDB clusters to your own AI agents through a hosted Model Context Protocol (MCP) endpoint. An agent such as Claude Code or Codex CLI can retrieve Aegis’s cluster and workload reports and its recommendations, and combine that CockroachDB-specific context with application code, metrics, and incident information from your other tools. Benefits of connecting your agent to Aegis include:
  • Analyzed context. Your agent receives the reports and recommendations that Aegis’s CockroachDB-specific agent harness has already produced from its check-ins and investigations, rather than raw database signals.
  • A standard integration. The endpoint uses MCP over HTTP with OAuth, so it works with any MCP client that supports remote servers.
  • No cluster access. The Aegis MCP endpoint doesn’t interact with your cluster or issue any queries to it, even read-only ones. It gives your agent recommendations and reports that Aegis has already generated, and lets it update recommendation status in Aegis.
  • Persistent context. Reports and recommendations are stored in the hosted Aegis service, so your agent can retrieve them at any time, including when Aegis cannot currently reach the cluster.
This page describes: For information about how Aegis works, see Cockroach Aegis Overview. For information about connecting a cluster, permissions, and data handling, see Security and Administration.

​
Bring your own agent

Connect your AI agents to Aegis to use its cluster reports, recommendations, and other context in your existing workflows. For example, you can use Aegis context to:
  • Review query and schema changes alongside the workload report.
  • Investigate a capacity problem using the cluster’s configuration and resource observations.
  • Assess cluster health when an incident alert arrives, using Aegis reports and recommendations.
  • Build an event timeline with Aegis context to identify signals worth investigating.
  • Compare reports from different environments to find similar anomalies or assess whether CockroachDB contributes to an incident.
Aegis gathers observations during check-ins, maintains cluster and workload context, and investigates anomalies. Through MCP, your agent uses the resulting reports and recommendations alongside its own tools and context. The MCP tools return Aegis’s stored analysis and are separate from the tools Aegis uses to observe the cluster. Reports and recommendations live in the hosted Aegis service. Aegis needs its connection to the monitored cluster only to make new observations. When that connection is unavailable, your agent can still retrieve the stored reports over MCP. Check their observation times before using them to reason about a live incident.

​
Connect through MCP

Aegis exposes a hosted MCP endpoint:
Use an MCP client that supports remote HTTP servers and OAuth. Aegis supports dynamic client registration, PKCE, refresh tokens, and a consent screen. Authenticate with the CockroachDB Cloud account associated with your Aegis organization. To connect an agent:
  1. Connect a cluster to Aegis and allow it to produce its initial reports. For instructions, see How do I connect a cluster?.
  2. Add the Aegis endpoint to your agent’s MCP client, as described for Claude Code and Codex CLI.
  3. Complete the sign-in and consent flow.
  4. Verify access with the read-only instance and report tools, as described in Verify the MCP connection.

​
Claude Code setup

Register the hosted server with your Claude Code client:
Complete the client’s OAuth sign-in and consent flow. If the new server’s tools do not appear, restart the client.

​
Codex CLI setup

Register Aegis as a remote HTTP MCP server:
If registration did not already start the OAuth sign-in flow, start it:
Sign in with the CockroachDB Cloud account associated with your Aegis organization and complete the consent flow. This sign-in is separate from the cluster’s SQL credentials, which the MCP client never needs.

​
Verify the MCP connection

You can use the following read-only operations to check the connection:
  1. Confirm that the client lists the six tools in Available operations. If tools are missing, verify the remote HTTP URL, inspect the client’s startup error, and reload or restart the client after configuration changes.
  2. Ask the agent to call list_instances and select the intended instance by name. Use the returned Aegis instance id for subsequent calls. This is a different identifier from the CockroachDB Cloud cluster ID.
  3. Call get_instance for that instance to inspect its status and check-in count, and confirm that it is the cluster you intended to monitor.
  4. Call get_reports for the same instance to retrieve the cluster and workload reports from its latest completed check-in. Check the returned check_in_id and as_of timestamp. If the first check-in has not yet produced reports, confirm its progress in the Aegis web UI.
  5. Call list_recommendations for that instance. A successful response can contain an empty list. To interpret that result alongside the reports, see Why might there be no recommendations?.
The check_in_id identifies the check-in represented by the response, and as_of identifies the report snapshot’s timestamp. A check-in can carry reports forward unchanged, so these two fields tell you which check-in you are looking at, and each report’s changed, created_at, and version_id fields tell you whether that check-in rewrote it. Read the observation times and metric windows inside each report to see what period it describes. The cluster and workload reports can have different update times.
A report retrieved after a workload stops can still describe the running workload, even when the check-in completed after the stop. To confirm recovery, use a report whose observation window covers the period after the workload stopped.
For example, try giving the agent this verification request:
Replace {workspace_name} with the cluster’s name in Aegis. Tool discovery shows which operations the client knows about, and a successful tool call confirms access to the selected instance. Aegis delivers reports and recommendations through tool calls, so an empty Resources or Resource templates list in your MCP client is expected.

​
Available operations

The hosted endpoint exposes the following operations: Resolving a recommendation or marking it read updates Aegis’s record of that recommendation. The monitored cluster is unchanged by this action, since you must separately apply any recommended changes through your normal change process. For more information about how Aegis controls access to cluster data, see SQL permissions and data access.

​
Analyze a workload change through MCP

This section describes a high-level workflow for comparing Aegis reports from before and after a workload change, to assess the change’s effect on query performance and cluster health. The workflow is read-only and assumes a cluster that is already connected to Aegis. For detailed examples that follow this workflow with real workloads and measurements, see Aegis Example Workflows. To compare reports around a workload change:
  1. Select the intended instance with list_instances and retrieve the current reports with get_reports. Record the returned check_in_id as the baseline. Aegis stores every check-in’s reports, so your agent does not need to keep the baseline in its own context; it can retrieve it again later by passing that check_in_id to get_reports.
  2. Make the workload change through your normal operating process, and record its time and application name. The MCP report tools read analysis only; the workload runs separately.
  3. Check progress with get_instance. After a later check-in completes, retrieve its reports with get_reports, and retrieve the baseline reports by passing the baseline check_in_id. Confirm that the new reports were updated and that their observations cover the change. If they do not yet cover it, wait for a later check-in and record the gap.
  4. Compare workload characteristics, query latency, contention, and cluster resource observations. Distinguish Aegis’s stated findings from conclusions your agent infers. When comparing with application measurements, account for differences in observation windows and in units, such as SQL statements per second versus transactions per second.
  5. Retrieve recommendations with list_recommendations and review any proposed actions alongside the reports. If the list is empty, summarize the available analysis and its limitations. Apply changes through your normal review process.
Set meaningful application_name values in your application’s SQL connection settings, such as workload-loader and workload-runner, so that Aegis can distinguish traffic sources in its workload observations. For example, after recording the baseline check-in and making the workload change, ask your agent to assess the evidence:
Replace {workspace_name} with the cluster’s name in Aegis, {baseline_check_in_id} with the check-in ID you recorded before the change, and {change_time_utc} with the workload change’s UTC timestamp. To assess recovery after a workload stops, repeat the comparison with reports whose observations cover the period after it stopped. For a worked example, see Step 6. Check recovery and choose a next action in the transaction contention workflow.

​
See also