Learn how to configure and use the Cribl MCP server. The MCP server is an AI-native way to interact with your Cribl environment (Cribl.Cloud or on-prem) from an MCP client such as Cursor, Claude Code, or the OpenAI Codex CLI.

Overview ​

The Cribl MCP server lets external MCP clients connect to your Cribl environment and investigate your Sources, Destinations, Worker Groups, system health, 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.

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.

Prerequisites ​

• Cribl environment (Cribl.Cloud, on-prem, or hybrid)
• Admin role in your Cribl Organization. MCP server access is limited to admins.
• 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 ​

Use the following table to identify the MCP endpoint and authentication method to use for your environment.

Replace ${workspaceName} and ${organizationId} with your Cribl.Cloud Workspace name and Organization identifier, and ${hostname} and ${port} with your Leader’s hostname and API port.

Get Your 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 ​

1. Log in to your Cribl.Cloud Organization.
2. Select Settings, then select AI Settings.
3. Locate the MCP Server setting, then select Copy bearer token.

The copied value is your current session Bearer token. Paste it into your MCP client configuration as described in Configure Your MCP Client.

The Copy bearer token button is available only when the MCP Server setting is enabled. If the setting is disabled, the button appears grayed out.

On-Prem Leader ​

On an on-prem Leader, obtain a Bearer token from the login API. Replace the hostname, port, and credentials with your own values.

curl -s -X POST 'https://${hostname}:${port}/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username": "<your-username>", "password": "<your-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.

To use https for on-prem requests, you must configure Transport Layer Security (TLS). If TLS is not configured, use http instead. Use http only for testing in development environments.

Protect your token. Only admins can use the MCP server. The Bearer token is your Cribl session token, and a connected MCP client inherits your permissions. For an admin, this includes reading and modifying configurations such as Pipelines. Treat the token like a password: Share it only with clients you trust, and never commit it to source control.

Configure Your MCP Client ​

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.

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

Cursor ​

Add the following to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "cribl-cloud": {
      "type": "url",
      "url": "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

After editing, restart Cursor, then confirm that the server shows as connected under Settings > MCP.

Claude Code ​

Add the following to ~/.claude.json (user scope) or .mcp.json (project scope), under the mcpServers key:

{
  "mcpServers": {
    "cribl-cloud": {
      "type": "url",
      "url": "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "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 ​

Add the following to ~/.codex/config.toml:

[mcp_servers."cribl-cloud"]
url = "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp"

[mcp_servers."cribl-cloud".http_headers]
Authorization = "Bearer <your-token>"
Accept = "application/json, text/event-stream"

To confirm that Codex loaded the configuration, run:

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 ​

After configuration, your MCP client surfaces the following tools that the embedded server exposes:

Access to the MCP server is limited to admins. Each tool runs with the calling user’s identity and inherits their existing Cribl permissions. Before it exposes or runs a tool, the embedded server checks the permission for the underlying REST resource. The embedded server relies on these existing permissions rather than a separate MCP permission model.

Use Case Examples ​

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.

Token Expiration and 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 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 under Settings > AI Settings.

Switch From the Standalone Docker Server ​

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.

Map Your 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.

Update Your Client Configuration ​

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

{
  "mcpServers": {
    "cribl-onprem": {
      "type": "url",
      "url": "http://localhost:3030/mcp",
      "headers": {
        "X-API-Key": "<your-api-key>"
      }
    }
  }
}

After (embedded server with a Bearer token):

{
  "mcpServers": {
    "cribl-cloud": {
      "type": "url",
      "url": "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

To switch:

1. Confirm that an administrator has enabled the embedded server at Settings > AI Settings > Core Functionality > MCP Server.
2. Get a Bearer token for your deployment. See Get Your Token.
3. 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.
4. Restart your MCP client and confirm that the Cribl MCP tools appear. See Verify the Connection.
5. 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 ​

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.

The standalone Cribl MCP server runs as a Docker container. You can get the container image from Docker Hub or the AWS Marketplace.

The container requires the following environment variables.

Run the container using one of the following commands.

Docker (Local) ​

docker run -p 3030:3030 \
  -e CRIBL_BASE_URL=https://${workspaceName}-${organizationId}.cribl.cloud \
  -e CRIBL_CLIENT_ID=<your-client-id> \
  -e CRIBL_CLIENT_SECRET=<your-client-secret> \
  -e MCP_API_KEY=<your-secure-api-key> \
  cribl/cribl-mcp-server

For an on-prem target, set CRIBL_BASE_URL to https://${hostname}:${port}.

AWS ECS ​

docker run -p 3030:3030 \
  -e CRIBL_BASE_URL=https://${workspaceName}-${organizationId}.cribl.cloud \
  -e CRIBL_CLIENT_ID=<your-client-id> \
  -e CRIBL_CLIENT_SECRET=<your-client-secret> \
  -e MCP_API_KEY=<your-secure-api-key> \
  <aws_account_id>.dkr.ecr.<aws_region>.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":"<https://your-org.cribl.cloud>"}
[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 ​

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:

{
  "mcpServers": {
    "cribl-onprem": {
      "type": "url",
      "url": "http://localhost:3030/mcp",
      "headers": {
        "X-API-Key": "<your-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.