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) 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 (<your-company>.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).

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.

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

{
  "mcpServers": {
    "cleric": {
      "type": "http",
      "url": "https://<your-company>.app.cleric.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${CLERIC_API_KEY}"
      }
    }
  }
}

Set the environment variable with your API key:

export CLERIC_API_KEY="<your-api-key>"

Restart Claude Code after adding the configuration. You should see Cleric listed as a connected MCP server.

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.

Cursor

Add a .cursor/mcp.json file to your project root:

{
  "mcpServers": {
    "cleric": {
      "type": "http",
      "url": "https://<your-company>.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	Discover available integrations, configuration and credential JSON schemas, setup instructions, documentation links, and manual consent steps. Optionally filter by toolkit_type.
test_integration_connection	Test the supplied configuration without saving a connection or reusing stored credentials.
create_integration_connection	Validate, test, and save the supplied configuration. Returns connection_name as the identifier. Existing names are never overwritten.

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

Integration setup through MCP is pending release. Until the three integration tools appear in your client's tool list, add connections in Integrations in the web app.

Ask your coding agent to discover the schema, test the connection, and create it:

Connect my Kubernetes cluster to Cleric. Discover its integration schema,
use the endpoint, CA certificate and read-only token I provide, test the
connection, and create it as production-cluster.

First call list_integration_schemas with {"toolkit_type": "kubernetes"}. Each schema includes config and credentials, with required fields, defaults, and field hints. Only integrations available on your instance are returned. Follow the linked integration guide for provider permissions.

Both connection tools take a configuration object:

{
  "configuration": {
    "name": "production-cluster",
    "description": "Production Kubernetes",
    "toolkit_type": "kubernetes",
    "config": {
      "host": "https://kubernetes.example.com",
      "certificate_b64": "<base64-encoded PEM CA certificate>"
    },
    "credentials": {
      "api_token": "<read-only service-account token>"
    }
  }
}

Use a connection name of 1–128 letters, digits, periods, underscores, or hyphens, starting with a letter or digit. description is optional and enabled defaults to true. Supply only fields from the schema and omit fields marked readOnly. The test uses the credentials in this request even if a connection with the same name already exists. For private endpoints, complete Connecting Private Resources first. Testing may provision firewall access and contact the provider.

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 <token>)
Grafana	host	api_token
Datadog	host	api_key, app_key

Use discovery for the current schemas and the fields of other integrations. Give credentials to your agent through its secure local configuration. Keep them out of investigation descriptions and source control. Cleric does not include submitted or stored credentials in these tool results.

Handle Results

The tools return JSON as MCP structured content and text. Check status before continuing:

Status	Next Step
ok	Read the returned schemas.
connected	The test passed. Call create_integration_connection with the same configuration to save it.
created	Save connection_name. The connection is ready. Creation also tests the connection.
invalid_configuration	Use errors[].field, errors[].code, the message and the schema to correct the request. Error values are omitted.
connection_failed	Follow the message and docs_url to check provider credentials, permissions, endpoint reachability or connector setup, then retry.
already_exists	A connection with that name exists. Inspect it in the web app or choose another name. The request did not change it.
manual_setup_required	Complete manual_action with the provider, then retry or finish setup in the web app.
unavailable	Discover the integrations enabled on your instance.
unauthenticated	Configure a valid personal key. Invalid or revoked Bearer keys are rejected with HTTP 401.

For example, a missing Kubernetes token returns:

{
  "status": "invalid_configuration",
  "message": "Correct the fields using list_integration_schemas.",
  "connection_name": "production-cluster",
  "toolkit_type": "kubernetes",
  "errors": [{"field": "credentials.api_token", "code": "missing"}]
}

If creation times out, retry with the same name. already_exists indicates that a connection with that name is present; inspect it before assuming the earlier request succeeded. MCP creation does not update or replace an existing connection. Manage updates and removals in Integrations in the web app.

Provider Consent

Slack requires a workspace administrator to approve Add to Slack in the web app. GitHub requires app installation and repository selection before an installation_id can be used. Generic MCP servers that require OAuth consent must be connected through the web app's OAuth flow. For Linear and Notion, use an API or integration token directly, or complete their OAuth flow in the web app. OAuth refresh credentials are managed through the web app rather than these connection tools.

Discovery and connection results provide manual_action instructions where consent is needed. Your personal Cleric key authenticates you to your instance; provider credentials authenticate Cleric to the integration. Actions are attributed to your Cleric user and use the same instance as the web app. The web app's /api/v1/toolkits endpoints still require signed-in user authentication; use these MCP tools with a personal key.

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.