# Work with the Cribl MCP Server > For the complete documentation index, see [llms.txt](/llms.txt). Learn how to configure and use the Cribl [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) server. The MCP server is an AI-native way to interact with your Cribl environment (Cribl.Cloud or on-prem). Access it through an [MCP client](https://modelcontextprotocol.io/docs/learn/client-concepts) such as Cursor, Claude Code, or the OpenAI Codex CLI. --- ## Overview {#overview} The Cribl MCP server lets external MCP clients connect to your Cribl environment and investigate your Sources, Destinations, Pipelines, Worker Groups, system health, metrics, and Search data through natural language. The MCP server is embedded in the Cribl Leader. Each MCP client connects directly to the Leader endpoint at `/api/v1/mcp` and authenticates with the same credentials as the rest of the Cribl API. There is no separate service to deploy, and every tool call runs with the caller's own identity and role-based access control (RBAC) permissions. The embedded MCP server does not use Cribl-managed models or a [custom AI provider](cribl-byoai). Your MCP client (for example, Cursor, Claude Code, or Codex) supplies its own model. Selecting or changing an AI provider in **AI Settings** does not change how the MCP server authenticates, exposes tools, or runs tool calls. > Cribl recommends the embedded MCP server for new setups. The standalone Docker MCP server (`cribl/cribl-mcp-server`) remains fully supported as an alternative. For that setup, see [Standalone Docker MCP Server](#docker-standalone). {.box .info} ## Prerequisites {#prerequisites} - Cribl environment ([Cribl.Cloud](/stream/cloud-vs-self-hosted), [on-prem](/stream/deploy-types/), or [hybrid](/stream/cloud-enterprise/#hybrid)) - For on-prem deployments, Cribl version 4.19.0 or newer - Admin role in your Cribl Organization to enable the MCP server on the **MCP Server** settings page. Connecting to the server and running tools does not require the admin role. - Product access for the tools you want to use. Cribl filters the tool list by your permissions. See [Tool Access and Permissions](#rbac). - MCP client such as Cursor, Claude Code, or the OpenAI Codex CLI - Network access to the Leader API endpoint for your deployment ## Choose Your Connection {#connection} Use the following table to identify the MCP endpoint and authentication method to use for your environment. | Deployment | MCP endpoint | Authentication | Token lifetime | | --- | --- | --- | --- | | Cribl.Cloud | `https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp` | Bearer token | About 24 hours | | On-prem Leader (embedded) | `https://${hostname}:${port}/api/v1/mcp` | Bearer token | Configurable (default 1 hour) | | Standalone Docker container | `http://:3030/mcp` | `X-API-Key` | Does not expire | Replace `${workspaceName}` and `${organizationId}` with your Cribl.Cloud Workspace name and Organization identifier, and `${hostname}` and `${port}` with the hostname and API port of your Leader. ## Get Your Token {#get-token} The embedded MCP server authenticates with a Bearer token that you pass in the `Authorization` header of your MCP client configuration. The way you obtain the token depends on your deployment. ### Cribl.Cloud {#token-cloud} 1. Log in to your Cribl.Cloud Organization. 1. Select **Settings**, then select **Global**. 1. Select **MCP Server**. 1. If the MCP server is off, toggle **Enable MCP server** on. Only administrators can turn the MCP server on or off. 1. Under **Connect to Cribl MCP server** > **Get your token**, select the **Copy token** icon. The copied value is your current session Bearer token. The page shows only the token header and masks the rest. Paste the token into your MCP client configuration as described in [Configure Your MCP Client](#configure), or use **Copy with Token** to copy a ready-made configuration. Once an administrator turns the MCP server on, you can also copy a token from the **Bearer Token** row at **Settings > Global > Information**. This row gives you the same session token without opening the **MCP Server** page. Users with a non-admin role such as **User**, **Read Only**, or **Editor** can use it to get a token for themselves. > The **MCP Server** page is separate from **AI Settings** because the embedded MCP server is independent of which LLM provider powers other Cribl AI features. {.box .info} > The token and client configuration sections appear only while the MCP server is enabled. On the **Information** tab, the **Bearer Token** row does not appear at all while the MCP server is off. {.box .info} ### On-Prem Leader {#token-onprem} > The embedded MCP server for on-prem Leaders requires Cribl version 4.19.0 or newer. {.box .info} On an on-prem Leader, go to **Settings > Global > MCP Server** and toggle **Enable MCP server** on. Then obtain a Bearer token from the login API. Replace the hostname, port, and credentials with your own values. ```bash curl -s -X POST 'https://${hostname}:${port}/api/v1/auth/login' \ -H 'Content-Type: application/json' \ -d '{"username": "", "password": ""}' | jq -r .token ``` On-prem Bearer tokens expire according to the **Auth token TTL** value at **Settings > Global > General Settings > API Server Settings > Advanced** (default `3600` seconds, or one hour). For details, see [Authenticate with the Cribl API](/cribl-as-code/api-auth). > To use `https` for on-prem requests, you must [configure Transport Layer Security (TLS)](/stream/securing-tls-ui-api). If TLS is not configured, use `http` instead. Use `http` only for testing in development environments. {.box .info} > **Protect your token.** The Bearer token is your Cribl session token, and a connected MCP client inherits your permissions. If your account can modify configurations such as Pipelines, the client can too. A token never grants more than the account that copied it, and Cribl checks your permissions again on each tool call. Treat the token like a password: Share it only with clients you trust, and never commit it to source control. {.box .warning} ## Configure Your MCP Client {#configure} Add the Cribl MCP server to your client configuration using the endpoint and token for your deployment. Cursor, Claude Code, and Codex all support remote HTTP MCP servers natively, so you do not need the `mcp-remote` proxy. ### Copy a Configuration From the MCP Server Page {#configure-ui} When the MCP server is on, the **MCP Server** page generates a configuration for you, with the endpoint for your deployment already filled in: 1. Go to **Settings > Global > MCP Server**. 1. Under **Configure your client**, select the tab for your client: **Claude Code**, **Cursor**, **Codex**, or **Other client**. 1. Review the snippet. The tab lists the file to edit: `~/.claude.json` or `.mcp.json` for Claude Code, `~/.cursor/mcp.json` for Cursor, and `~/.codex/config.toml` for Codex. The **Other client** tab lists the URL, method, and headers instead. The snippet shows `` as a placeholder. 1. Select **Copy with Token** to copy the snippet with your current session token filled in, then paste it into the client's configuration file. 1. Restart your client to confirm the connection. The following sections show the same configuration, so you can edit it by hand or fill in the values yourself. The following examples use a Cribl.Cloud endpoint. For an on-prem Leader, replace the URL with `https://${hostname}:${port}/api/v1/mcp` and use the token from the [login API](#token-onprem). In each example, replace the placeholders in the `url` value with the values for your deployment: `${workspaceName}` and `${organizationId}` for Cribl.Cloud, or `${hostname}` and `${port}` for an on-prem Leader. > The `Accept: application/json, text/event-stream` header is required for Cribl.Cloud and embedded Leader endpoints. Without it, the server returns HTTP 406. {.box .warning} ### Cursor {#configure-cursor} Add the following to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project): ```json { "mcpServers": { "cribl-cloud": { "type": "url", "url": "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp", "headers": { "Authorization": "Bearer ", "Accept": "application/json, text/event-stream" } } } } ``` After editing, restart Cursor, then confirm that the server shows as connected under **Settings > MCP**. ### Claude Code {#configure-claude-code} Add the following to `~/.claude.json` (user scope) or `.mcp.json` (project scope), under the `mcpServers` key: ```json { "mcpServers": { "cribl-cloud": { "type": "http", "url": "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp", "headers": { "Authorization": "Bearer ", "Accept": "application/json, text/event-stream" } } } } ``` After editing, restart Claude Code or run `/mcp` to confirm that the server shows as **connected**. Claude Code expands `${VAR}` references in `url` and `headers` values, so you can keep the token in an environment variable. ### Codex {#configure-codex} Add the following to `~/.codex/config.toml`: ```toml [mcp_servers."cribl-cloud"] url = "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp" [mcp_servers."cribl-cloud".http_headers] Authorization = "Bearer " Accept = "application/json, text/event-stream" ``` To confirm that Codex loaded the configuration, run: ```bash codex mcp get cribl-cloud codex mcp list ``` The output shows `transport: streamable_http`, `Status: enabled`, and `Auth: Bearer token`. Existing Codex sessions might not pick up a newly added server, so restart Codex or open a new thread before testing the Cribl MCP tools. ## Verify the Connection {#verify} After configuration, your MCP client surfaces the tools that the embedded server exposes. You can also preview the tools before you connect. See [Preview Available Tools](#try-it-out). The **Access required** column shows the permission that makes each tool visible. For details, see [Tool Access and Permissions](#rbac). | Tool | Description | Access required | | --- | --- | --- | | `cribl_getSystemMetrics` | Retrieve system metrics, with optional filtering by expression, metric name, and time range. | System metrics | | `cribl_getAlerts` | Get alerts and system messages, with filtering and pagination support. | System messages | | `cribl_listWorkerGroups` | List Worker Groups in the deployment, optionally filtered by product type. | Worker Group list | | `cribl_getSources` | Retrieve Source (input) configurations. Use `groupName` to scope to a Worker Group. | Stream | | `cribl_getDestinations` | Retrieve Destination (output) configurations. Use `groupName` to scope to a Worker Group. | Stream | | `cribl_getPipelines` | Retrieve Pipeline definitions. Use `groupName` to scope to a Worker Group. Supports Pipelines inside Packs. See [Work With Pipelines in Packs](#pack-pipelines). | Stream | | `cribl_getPipelineConfig` | Retrieve the full configuration for a specific Pipeline by ID. For a Pipeline inside a Pack, use `groupName` and `packId`. | Stream | | `cribl_setPipelineConfig` | Apply a new configuration to a specific Pipeline. For a Pipeline inside a Pack, use `groupName` and `packId`. | Stream, plus write access | | `cribl_getSearchContext` | Return available Datasets, saved searches, and KQL guidance needed to compose a query. | Search | | `cribl_runSearchQuery` | Run an exact KQL query. Fast searches return results inline. Longer searches return a job ID. | Search | | `cribl_getSearchJobResults` | Retrieve status and paginated results for a search job, including preview results while it runs. | Search | | `cribl_getSearchNotebooks` | Retrieve Search Notebooks, or a single Notebook when you provide a Notebook ID. | Search | | `cribl_addToSearchNotebook` | Add Markdown or search sections to a Search Notebook, or create a new Notebook. | Search | | `cribl_editSearchNotebookSection` | Edit a section in a Search Notebook. | Search | | `cribl_removeSearchNotebookSection` | Remove one or more sections from a Search Notebook. | Search | | `cribl_queryMetrics` | Run a PromQL query, or a metadata command such as `.labels` or `.metrics`, against the metrics you ingest through Prometheus remote write. | Search | | `cribl_getMonitors` | Retrieve monitor configurations, which are the alert-on-metric rules for the metrics you ingest through Prometheus remote write. | Monitors | > `cribl_queryMetrics` and `cribl_getMonitors` work with the metrics you ingest into Cribl, not with health data about Cribl itself. For the health of your Cribl deployment, use `cribl_getSystemMetrics` and `cribl_getAlerts`. {.box .info} ### Work With Pipelines in Packs {#pack-pipelines} The Pipeline tools can read and change Pipelines inside [Packs](/stream/packs). Because Packs are installed per Worker Group, name both the Pack and its Worker Group in your prompt. For example, "Show me the Pipelines in the my-pack Pack on the default Worker Group." Your client works out which tool parameters to use. ### Tool Access and Permissions {#rbac} Each tool runs with the calling user's identity and inherits that user's existing Cribl permissions. The embedded server relies on these existing permissions rather than a separate MCP permission model, so there are no MCP-specific roles to grant. Cribl applies the same rules on Cribl.Cloud and on-prem deployments. To review or change what a user can do across Cribl, see [Access Control](/iam/access-control/). Cribl checks access in three layers: endpoint access, tool visibility, and call-time enforcement. 1. **Endpoint access.** Connecting to `/api/v1/mcp` requires the **Leader MCP Access** permission. Cribl includes this permission in the common building-block policies, so any user with Worker Group read access, Search access, or product access already has it. A user with no assigned policies receives HTTP 403 before Cribl processes the request. 1. **Tool visibility.** Your client sees only the tools your permissions allow: - **Search tools** require Search product access. - **Stream read tools** require Stream product access. - **`cribl_setPipelineConfig`** requires Stream product access and write access to at least one Worker Group. A read-only Stream user sees the Stream read tools but not this one. - **Platform tools**, meaning `cribl_getSystemMetrics`, `cribl_getAlerts`, `cribl_listWorkerGroups`, and `cribl_getMonitors`, are checked individually against the resource each one reads. You might see some of them and not others. Tools you cannot use do not appear in your client's tool list at all. Cribl omits them rather than listing them and failing when they run. If a client calls an omitted tool anyway, for example because it cached an earlier tool list, the call returns `Forbidden: insufficient API permissions for this tool (RBAC).` 1. **Call-time enforcement.** Visibility is not the final check. Cribl also enforces permissions on each call, so a tool that appears in your list can still return an error for a Worker Group or Dataset that you cannot access. This is expected. Tool visibility is scoped by product, while the underlying resources are scoped by Worker Group and Dataset. ### Preview Available Tools {#try-it-out} When the MCP server is on, the **Try it out** section of the **MCP Server** page lists the tools grouped by category: **Platform**, **Stream**, **Search**, and **Monitors**. Tool access follows the user and team permissions set within Cribl. A check mark identifies the tools that you can use. Tools you lack permission to use appear unchecked. Any user with product access can open the **MCP Server** page and view this list, even if only an administrator can turn the server on. To narrow the list: - Enter text in **Filter tools by name or description**. - Under **Access type**, select **All**, **Read**, or **Write**. Tools that can modify content, which are `cribl_setPipelineConfig` and the Search Notebook tools that add, edit, or remove sections, carry a **Write access** tag. - Turn on **Available only** to hide tools that you don't have access to. ### Audit Tool Calls {#audit} The Leader logs every MCP tool call at `info` level under the event name `mcp.tool.call`. Each entry records the tool name, the username of the caller, the duration in milliseconds, a request ID, and a status of `success`, `error`, or `denied`. A `denied` status means that Cribl blocked the call because the user lacked permission. On Cribl.Cloud, entries also record the tenant. Cribl does not log tool arguments or results. ## Use Case Examples {#use-cases} The Cribl MCP server provides an AI-native approach to interacting with your Cribl environment. When evaluating how to best use the Cribl MCP server, consider the following use cases as a reference. | Use Case | Sample Prompt | Value | | --- | --- | --- | | Cribl environment health | "What's the current health of my Cribl environment? Highlight any areas of concern or action items I need to consider." | Coalesces health information across your Cribl environment into a digestible summary with clear action items. | | Cribl Source and Destination overview | "What Sources and Destinations do I have in my environment? Are there any I should pay specific attention to?" | Provides an overview of active and unused Sources and Destinations across your environment. | | Cribl Worker Group overview | "What's the processing status of my Worker Groups?" | Provides cross-Worker-Group visibility into throughput, health, and configuration settings, with improvement recommendations. | | Cribl Search investigations | "Search the last 24 hours for authentication failures, summarize them by source, and highlight unusual activity." | Discovers available Datasets, composes the appropriate KQL query, runs it, and retrieves results for analysis. (Unless the Dataset and exact KQL are already known, the agent should call `getSearchContext` first to discover Datasets and syntax. If it doesn't, ask it to "Check which Datasets are available first.") | ## Token Expiration and Refresh {#token-refresh} - **Cribl.Cloud:** Bearer tokens expire after about 24 hours. To refresh, log back in to Cribl.Cloud, copy a new token, and restart your MCP client. - **On-prem Leader:** Bearer tokens expire according to the **Auth token TTL** setting (default one hour). To refresh, re-run the [login API](#token-onprem) and update your client configuration. When a token expires, MCP tool calls return HTTP 401. Refresh the token and update your client configuration to restore access. If the MCP server is disabled, tool calls return HTTP 403. An administrator can enable it at **Settings > Global > MCP Server**. ## Switch From the Standalone Docker Server {#migrate} If you already run the standalone Docker MCP server, you can switch to the embedded server on the Leader. The standalone Docker server remains supported, so this switch is optional. The embedded server removes the need to run a separate container, manage API credentials for the server, or expose port 3030. The two servers share tools such as `cribl_getSources`, and shared tools use identical names, so prompts that reference them continue to work after you switch. The tool sets are not identical, however. For the tools the embedded server exposes, see [Verify the Connection](#verify). ### Map Your Credentials {#migrate-credentials} The embedded server authenticates with your session Bearer token instead of the environment variables that the container requires. Use the following table to map your standalone configuration to the embedded configuration. | Standalone Docker setting | Embedded server equivalent | | --- | --- | | `CRIBL_BASE_URL` | The MCP endpoint host: `https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp` (Cribl.Cloud) or `https://${hostname}:${port}/api/v1/mcp` (on-prem). | | `CRIBL_CLIENT_ID` and `CRIBL_CLIENT_SECRET` | Not required. Authentication uses your Bearer token. See [Get Your Token](#get-token). | | `MCP_API_KEY` (sent as `X-API-Key`) | Not required. Replaced by the `Authorization: Bearer ` header. | | Running container on port 3030 | No container. Clients connect directly to the Leader endpoint. | ### Update Your Client Configuration {#migrate-config} Replace your standalone server configuration with the embedded endpoint and Bearer token. For example, on Cribl.Cloud: **Before** (standalone Docker server with an API key): ```json { "mcpServers": { "cribl-onprem": { "type": "url", "url": "http://localhost:3030/mcp", "headers": { "X-API-Key": "" } } } } ``` **After** (embedded server with a Bearer token): ```json { "mcpServers": { "cribl-cloud": { "type": "url", "url": "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp", "headers": { "Authorization": "Bearer ", "Accept": "application/json, text/event-stream" } } } } ``` To switch: 1. Confirm that an administrator has enabled the embedded server at **Settings > Global > MCP Server**. 1. Get a Bearer token for your deployment. See [Get Your Token](#get-token). 1. In your client configuration, change the `url` to the embedded endpoint, remove the `X-API-Key` header, and add the `Authorization` and `Accept` headers. See [Configure Your MCP Client](#configure). 1. Restart your MCP client and confirm that the Cribl MCP tools appear. See [Verify the Connection](#verify). 1. After you confirm that the embedded server works, stop the standalone container. The container's `CRIBL_CLIENT_ID`, `CRIBL_CLIENT_SECRET`, and `MCP_API_KEY` values are no longer used by the client. ## Standalone Docker MCP Server {#docker-standalone} > The standalone Docker MCP server is a fully supported alternative to the embedded MCP server. It runs as a separate container and authenticates with a static `X-API-Key` rather than a Bearer token. Cribl recommends the embedded MCP server for new setups. {.box .info} The standalone Cribl MCP server runs as a Docker container. You can get the container image from [Docker Hub](https://hub.docker.com/r/cribl/cribl-mcp-server/tags) or the [AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-dddpw5botcxri). The container requires the following environment variables. | Variable Name | Required | Description | Information Source | | --- | --- | --- | --- | | `CRIBL_BASE_URL` | Yes | The base URL for your target Cribl environment (Cribl.Cloud Organization URL or on-prem Leader URL). | [Cribl](/cribl-as-code/api/#base-urls) | | `CRIBL_CLIENT_ID` | Yes | One of the two components of the Cribl API credential. Must be created by an admin or owner. | [Cribl API Auth](/cribl-as-code/api-auth) | | `CRIBL_CLIENT_SECRET` | Yes | One of the two components of the Cribl API credential. Must be created by an admin or owner. | [Cribl API Auth](/cribl-as-code/api-auth) | | `MCP_API_KEY` | No | A self-created API key to restrict access to your MCP server. Recommended if hosting in AWS or shared environments. | User created and managed | | `aws_account_id` | Yes (for AWS) | Your target AWS account ID if hosting in AWS. | [AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/console-account-id.html) | | `aws_region` | Yes (for AWS) | Your target AWS region if hosting in AWS. | [AWS ECS](https://docs.aws.amazon.com/general/latest/gr/ecs-service.html) | Run the container using one of the following commands. ### Docker (Local) {#docker-local} ```bash docker run -p 3030:3030 \ -e CRIBL_BASE_URL=https://${workspaceName}-${organizationId}.cribl.cloud \ -e CRIBL_CLIENT_ID= \ -e CRIBL_CLIENT_SECRET= \ -e MCP_API_KEY= \ cribl/cribl-mcp-server ``` For an on-prem target, set `CRIBL_BASE_URL` to `https://${hostname}:${port}`. ### AWS ECS {#docker-aws} ```bash docker run -p 3030:3030 \ -e CRIBL_BASE_URL=https://${workspaceName}-${organizationId}.cribl.cloud \ -e CRIBL_CLIENT_ID= \ -e CRIBL_CLIENT_SECRET= \ -e MCP_API_KEY= \ .dkr.ecr..amazonaws.com/cribl/cribl-mcp-server ``` When the container starts, you should see output confirming that the Cribl MCP server is running: ``` [2025-11-04T17:00:45.965Z] INFO Configuration validated successfully {"baseUrl":""} [2025-11-04T17:00:45.966Z] INFO Registering MCP tools... [2025-11-04T17:00:45.966Z] INFO MCP tools registered successfully [2025-11-04T17:00:45.969Z] INFO MCP Stateless Streamable HTTP Server listening on port 3030 ``` ### Configure a Client for the Standalone Container {#docker-configure} The standalone container is treated as a local MCP server, even when it runs in an ECS instance. If you set the `MCP_API_KEY` environment variable, configure your MCP client to send the same key in the `X-API-Key` header: ```json { "mcpServers": { "cribl-onprem": { "type": "url", "url": "http://localhost:3030/mcp", "headers": { "X-API-Key": "" } } } } ``` The `MCP_API_KEY` is a static string set when the server starts and does not expire. --- To connect Cribl AI to external MCP servers instead, see [Connect Cribl AI to External MCP Servers](/copilot/mcp-integrations).