> For the complete documentation index, see [llms.txt](https://docs.cleric.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cleric.ai/integrations/mcp.md). # MCP Server Work with Cleric issues, changes, the service catalog, and usage, and connect integrations, from MCP clients Cleric exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets coding agents work with your Cleric data: issues with their root cause, evidence, and proposed fixes; changes Cleric verified after deploy; the service catalog and its dependency map; the knowledge base; and usage stats. A coding agent can also start an investigation, follow up on one, and connect your tools. Your agent needs this guide, your instance URL, and a personal Cleric API key. ## Getting Your API Key 1. Open **Settings** in the Cleric web app (`.app.cleric.ai`) and select the **Personal** tab. 2. Under **Personal API key**, click **Generate API key**. 3. In the **API key created** dialog, click **Copy**, and store the key securely. The dialog will not be shown again. 4. Use the key as the Bearer token in your MCP client config (see below). {% hint style="warning" %} This is your personal API key. It authenticates as your user account, and any actions taken through the MCP server are attributed to you. Do not share it with other users or commit it to source control: each user should generate their own key. {% endhint %} You can only have one API key configured per user at a time. To rotate it, click **Revoke** on the existing key, confirm, then **Generate API key** again. Any MCP client configurations using the old key will stop working immediately on revoke. ## Setup ### Claude Code Add a `.mcp.json` file to your project root (or `~/.claude.json` for global config): ```json { "mcpServers": { "cleric": { "type": "http", "url": "https://.app.cleric.ai/mcp", "headers": { "Authorization": "Bearer ${CLERIC_API_KEY}" } } } } ``` Set the environment variable with your API key: ```bash export CLERIC_API_KEY="" ``` Restart Claude Code after adding the configuration. You should see Cleric listed as a connected MCP server. {% hint style="info" %} Using `${CLERIC_API_KEY}` keeps the key out of files that might be committed to version control. You can also replace it with the literal key value if you prefer. {% endhint %} ### Cursor Add a `.cursor/mcp.json` file to your project root: ```json { "mcpServers": { "cleric": { "type": "http", "url": "https://.app.cleric.ai/mcp", "headers": { "Authorization": "Bearer ${CLERIC_API_KEY}" } } } } ``` Alternatively, add the server through **Cursor Settings > MCP** using the URL and headers above. ## Available Tools Once connected, the following tools are available to the AI assistant. The server returns only what your user can see in the web app: issues and changes from private Slack channels you are not a member of are hidden. | Tool | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_issues` | List issues, most recently occurring first. Merged duplicates are rolled into their issue. Filter by `status` (`investigating`, `suggested_fix`, `inconclusive`, `pending_verification`, `resolved`), `service`, `resolved_reason` (`suggested_fix`, `other_fix`, `self_resolved`, `false_positive`), and `min_alert_count`. `sort` by `last_occurred_at` (default), `created_at`, or `alert_count`. `since` (default 7 days ago, at most 90) counts an issue when it or a duplicate merged into it occurred after that time. | | `get_issue` | Get one issue by slug (for example `ISS-123`) or ID: status, alert, Cleric's latest answer with citations, remediation actions with the current one marked, and the repository of the affected service when the service catalog knows it. `include` adds `hypotheses`, `occurrences`, and the thread (`timeline`). `wait_seconds` (up to 60) waits for a running investigation to finish. | | `search_issues` | Search issues by text. Returns keyword matches on the title, alert, and thread (default last 30 days), and on the first page, semantically similar issues from completed investigations seen in the last 30 days. | | `create_issue` | Start a new Cleric investigation. Pass a description of what to investigate. Uses credits, as an investigation started from the web app does. | | `follow_up` | Send a follow-up message to an issue's investigation, as if replying in its thread. | | `list_changes` | List changes Cleric tracked after deploy, newest first, with their verification status and, for anomalies, the issue Cleric opened. Filter by `author` (`me` or a GitHub login), `status`, `service`, and `since` (default 7 days ago). | | `get_change` | Get one change by slug (for example `CHG-123`): intent, release, links, and every expectation Cleric is verifying with its status and evidence summary. | | `get_service` | Look up a service in the service catalog: where it runs, its source repository, and the services it depends on or is depended on by, up to 3 hops. | | `search_knowledge` | Search Cleric's knowledge base (facts learned from past incidents, Slack discussions, and ingested docs/runbooks) for information relevant to a query. | | `get_usage_stats` | Usage for the last 7 or 30 days and the period before: issue counts and outcomes as on the Performance page, result ratings, and active users. Counts only; no issue contents. | | `query_usage` | Credit usage, filtered and grouped like a SQL query. `where` filters by billing month range (`from_month`, `to_month`, from July 2026 to the current month, default the current month), `kind` (`issue`, `chat`, `release`, `change`), `channel`, `user`, and `item`. `group_by` takes up to 4 of `month`, `kind`, `channel`, `user`, and `item`. Each row reports credits, distinct items, and its share of the filtered total; grouping by `item` adds each item's title and link. | | `list_integration_schemas` | List the integrations available on your instance. Pass `toolkit_type` for one integration's configuration and credential JSON schemas, setup instructions and documentation link. | | `list_integration_connections` | List the connected integrations with what each points at and whether its last connection check passed. Credentials are never included. Pass `toolkit_type` for one integration. | | `create_integration_connection` | Test an integration with the supplied `configuration` and save it as a new connection if the test passes. Nothing is saved when validation or the test fails. An existing connection with the same name is never changed. | | `update_integration_connection` | Change a connection's `description`, `config` or `credentials`, or set `enabled`. Fields you omit keep their saved values. An enabled connection is tested first and nothing is saved if the test fails. | | `test_integration_connection` | Test a saved connection now instead of waiting for the hourly check, and return the provider's error if it fails. | | `delete_integration_connection` | Remove a connection and its credentials. This cannot be undone. | Limitations: * **Changes** exist only for deploys whose notification Cleric picked up and verified. A deploy Cleric did not see does not appear in `list_changes`. * **Service dependencies** come from discovery and can be incomplete. Managed databases and SaaS dependencies are often missing, and catalog data can be up to a day old. * **Alert counts** cover an issue's whole history, including duplicates merged into it, not just the `since` window. * **Usage by user** credits the person who started the thread. Alerts posted in Slack count against the bot that posted them, alerts received by webhook show as `(webhook alert)`, and follow-ups count against the thread's starter. Usage outside Slack shows channel `(web app)` for threads started in the web app and `(none)` for threads with no channel, such as webhook alerts. Usage in private Slack channels you are not a member of is counted in totals but shown as `(private)`, without its channel or item. ## Prompts The server also provides prompts for common workflows. Claude Code shows them as slash commands, for example `/mcp__cleric__fix_open_issues`. | Prompt | What it does | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `fix_open_issues` | Works through open issues with a suggested fix and drafts each fix in the current repository. Takes `count` (default 5). | | `check_my_changes` | Checks whether changes you deployed caused problems Cleric detected, starting with unaddressed anomalies. Takes `days` (default 7). | | `find_noisy_alerts` | Finds alerts that fire often and resolve without action, and suggests how to tune them. Takes `days` (default 30). | | `weekly_usage_report` | Summarizes this week's Cleric usage against the previous week. | ## Connect an Integration Ask your coding agent to connect an integration: ``` Connect my Kubernetes cluster to Cleric as production-cluster, using the endpoint, CA certificate and read-only token I provide. ``` The agent calls `list_integration_connections` to see what is already connected, `list_integration_schemas` with `{"toolkit_type": "kubernetes"}` for the fields the integration takes and the link to its guide in [Supported Integrations](/integrations/supported-integrations.md), then `create_integration_connection`: ```json { "configuration": { "name": "production-cluster", "description": "Production Kubernetes", "toolkit_type": "kubernetes", "config": { "host": "https://kubernetes.example.com", "certificate_b64": "" }, "credentials": { "api_token": "" } } } ``` Cleric tests the connection with these credentials before saving it. `description` is optional and `enabled` defaults to `true`. Fields outside the schema are rejected, and so are fields the schema marks `readOnly`, such as the AWS `external_id`: Cleric fills those in. A field with a `prefix` or `suffix` in the schema, such as `https://` for a Kubernetes host, is completed with it when the value omits it. For private endpoints, complete [Connecting Private Resources](/integrations/private-resources.md) first. The test may provision firewall access and contacts the provider. The provider side of each integration, such as the service account, IAM role or API token Cleric needs, is in that integration's section of [Supported Integrations](/integrations/supported-integrations.md), linked as `docs_url` from `list_integration_schemas`. An agent with your cloud CLI can do that setup too. For AWS and EKS: 1. `list_integration_schemas` with `{"toolkit_type": "aws"}` returns, in `instructions_markdown`, the trust policy for your instance, including its external ID. The web app shows the same policy. 2. Create the IAM role with that trust policy, the validation policy from the [AWS guide](/integrations/supported-integrations.md#amazon-web-services), which lets Cleric verify the role is read-only, and the read-only policies you want. Add `eks:Describe*` and `eks:List*` for EKS. 3. `create_integration_connection` for `aws` with the role ARN and default region. The test assumes the role and fails if its policies grant write access. 4. For each EKS cluster, grant the role access to the cluster as a member of the `cleric` group and apply the `cleric-role` ClusterRole as in the [EKS guide](/integrations/supported-integrations.md#elastic-kubernetes-service), then `create_integration_connection` for `eks` with the cluster ARN and API server host. The AWS connection for the cluster's account must exist first; the EKS test authenticates through it. Common credential fields: | Integration | Configuration Fields | Credential Fields | | ----------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Kubernetes | `host`, `certificate_b64` (base64-encoded PEM CA certificate; optional for a public CA) | `api_token` | | Generic MCP | `url` (Streamable HTTP endpoint) | `authorization_header` (full header, such as `Authorization: Bearer `) | | Grafana | `host` | `api_token` | | Datadog | `host` | `api_key`, `app_key` | Use `list_integration_schemas` for the fields of other integrations. Give credentials to your agent through its secure local configuration, and keep them out of investigation descriptions and source control. Tool results never include submitted credentials. ### Handle Results A connection that is created returns what `list_integration_connections` reports for it, including what it points at and that its test passed. Otherwise the tool returns an error that says what to change: * **Invalid configuration** names each missing, unknown, read-only or invalid field, without its value. * **Connection failed** gives the provider's error, for example a rejected key, an unreachable endpoint, or an AWS role whose policies grant write access. * **Already exists** names the integration and endpoint of the existing connection. If it is the one you meant, the integration is already connected; otherwise choose another name. `list_integration_connections` reports each connection as `healthy` when its last connection check, run every hour, passed within the last two hours. After fixing access on the provider side, `test_integration_connection` re-tests it at once. To rotate a credential, `update_integration_connection` with only that credential field. Pointing a connection at a different endpoint needs every credential replaced; otherwise create a new connection. ### Provider Consent Integrations that need consent from the provider are connected in the web app: * **Slack:** a workspace administrator approves **Add to Slack**. * **GitHub:** install the Cleric GitHub app and approve repository access. To connect your own GitHub app instead, supply its `app_id`, `private_key_b64` and `installation_id`. * **Linear and Notion:** supply an API or internal integration token as `access_token`, or complete their OAuth flow in the web app. * **Generic MCP servers that use OAuth:** connect them through the web app's OAuth flow. Your personal Cleric key authenticates you to your instance; provider credentials authenticate Cleric to the integration. Connections you create are attributed to your Cleric user. ## Example Usage Once configured, you can ask your AI coding tool questions like: ``` What did Cleric find about the payment API latency spike? Which open issues does Cleric have a fix for in this repository? Did any of my changes from this week cause problems? What does the checkout service depend on? How many people used Cleric last week, and how did they rate it? ``` The AI tool calls the appropriate Cleric MCP tools to retrieve the data and include it in its response.