> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cockroach Aegis Agentic Ecosystem

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

<Note>
  **This feature is in <InternalLink version="releases" path="cockroachdb-feature-availability">private preview</InternalLink>** and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
</Note>

Cockroach Aegis exposes its analysis of your CockroachDB clusters to your own AI agents through a hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](/docs/continuum/aegis-overview#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:

* Ways to [bring your own agent](#bring-your-own-agent) to Aegis.
* How to [connect through MCP](#connect-through-mcp), including setup for [Claude Code](#claude-code-setup) and [Codex CLI](#codex-cli-setup), how to [verify the connection](#verify-the-mcp-connection), and the [available operations](#available-operations).
* How to [analyze a workload change through MCP](#analyze-a-workload-change-through-mcp).

For information about how Aegis works, see [Cockroach Aegis Overview](/docs/continuum/aegis-overview).

For information about connecting a cluster, permissions, and data handling, see [Security and Administration](/docs/continuum/aegis-security-and-data-access).

## 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:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
https://aegis.crdb.dev/mcp
```

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?](/docs/continuum/aegis-security-and-data-access#how-do-i-connect-a-cluster).
2. Add the Aegis endpoint to your agent's MCP client, as described for [Claude Code](#claude-code-setup) and [Codex CLI](#codex-cli-setup).
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](#verify-the-mcp-connection).

### Claude Code setup

Register the hosted server with your Claude Code client:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
claude mcp add --transport http aegis https://aegis.crdb.dev/mcp
```

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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
codex mcp add aegis --url https://aegis.crdb.dev/mcp
```

If registration did not already start the OAuth sign-in flow, start it:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
codex mcp login aegis
```

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](#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?](/docs/continuum/aegis-overview#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.

<Note>
  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.
</Note>

For example, try giving the agent this verification request:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
Use Aegis MCP to find {workspace_name} with list_instances. Use its returned
instance ID to call get_instance, get_reports, and list_recommendations.
Report the check_in_id and as_of timestamp, each report's changed,
created_at, and version_id fields, and the observation windows inside each
report. If there are no recommendations, summarize the reports instead.
This is a read-only check: leave recommendation state unchanged.
```

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:

| Data            | MCP tool                   | Operation                                                              |
| --------------- | -------------------------- | ---------------------------------------------------------------------- |
| Instances       | `list_instances`           | List instances visible to the signed-in user.                          |
| Instances       | `get_instance`             | Get an instance's metadata, status, and check-in count.                |
| Reports         | `get_reports`              | Get the latest or a specified check-in's cluster and workload reports. |
| Recommendations | `list_recommendations`     | List recommendations, optionally filtered by status.                   |
| Recommendations | `resolve_recommendation`   | Mark an open recommendation done or dismissed.                         |
| Recommendations | `mark_recommendation_read` | Mark a recommendation read or unread.                                  |

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](/docs/continuum/aegis-security-and-data-access#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](/docs/continuum/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](/docs/stable/connection-parameters#additional-connection-parameters), 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:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
Use Aegis MCP to retrieve the status, reports, and recommendations for
{workspace_name}. Compare the latest reports with the baseline reports from
check-in {baseline_check_in_id} and with the workload change at
{change_time_utc}. Report the
check_in_id, as_of, each report's changed/created_at/version_id, and its
observation windows. Explain changes in workload performance and cluster
health, separating Aegis's findings from your inferences. If the reports
do not yet cover the change, say so. If there are no recommendations,
explain the relevant report findings instead. This is a read-only
analysis: leave the cluster, the workload, and recommendation state
unchanged.
```

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](/docs/continuum/aegis-example-workflows#step-6-check-recovery-and-choose-a-next-action) in the transaction contention workflow.

## See also

* [Cockroach Aegis Overview](/docs/continuum/aegis-overview)
* [Security and Administration](/docs/continuum/aegis-security-and-data-access)
* [Aegis Example Workflows](/docs/continuum/aegis-example-workflows)