Olly

Use the Coralogix MCP server to send natural-language investigation requests to Olly, Coralogix's observability agent. Ask "why is the checkout service slow?" or "what alerts fired in the last hour?" directly from Cursor, Claude Code, or Codex — Olly investigates across logs, metrics, traces, and alerts and returns answers along with downloadable artifacts.

Olly is opt-in and only available on MCP server v2. Olly runs longer agent workflows against your observability backend, so Coralogix treats it as a costly capability and hides it unless you turn it on per MCP connection.

What you need

• MCP server v2 — send the mcp-version: v2 header (see Setup).
• The x-allow-costly-use: true header on every MCP request. Without it, Olly tools are not advertised to your client.
• The same Coralogix authentication you use for the rest of the MCP server — OAuth or a personal Coralogix API key. Olly inherits the permissions of the authenticated user.

Turn on Olly in your MCP client

Add the x-allow-costly-use header to your MCP server configuration. Set it once on the server entry — not on a one-off request — so it applies to every tool listing and call.

Cursor

OAuth

Add the header to your .cursor/mcp.json file:

{
  "mcpServers": {
    "coralogix-server": {
      "url": "https://api./mgmt/api/v1/mcp",
      "headers": {
        "mcp-version": "v2",
        "x-allow-costly-use": "true"
      }
    }
  }
}

API key

If you authenticate with a personal Coralogix API key instead of OAuth, add the same two headers alongside Authorization:

{
  "mcpServers": {
    "coralogix-server": {
      "url": "https://api./mgmt/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR-API-KEY>",
        "mcp-version": "v2",
        "x-allow-costly-use": "true"
      }
    }
  }
}

Claude Code

Register the MCP server with the additional header:

claude mcp add --transport http coralogix-server https://api./mgmt/api/v1/mcp \
  --header "mcp-version: v2" \
  --header "x-allow-costly-use: true"

Codex

Add both headers to the coralogix-server entry in ~/.codex/config.toml:

[mcp_servers.coralogix-server]
http_headers = { "mcp-version" = "v2", "x-allow-costly-use" = "true" }

The value must be the string true — capitalization does not matter, so true, True, and TRUE are all accepted. Any other value, or no x-allow-costly-use header at all, leaves Olly hidden.

Tools

Send a question to Olly

Use olly_ask to send a question or investigation request. Olly works as a sub-agent: for each request it plans a sequence of steps, queries logs, metrics, traces, and alerts on its own, and combines the findings into one answer. Because of that, a single call can take time. olly_ask is blocking and waits up to 15 minutes for Olly to finish before returning.

Parameter	Required	Description
message	Yes	The question or investigation request.
chat_id	No	Continue an existing conversation. Omit this parameter to start a new chat.
model	No	Specific Olly model to use. Omit this parameter to let the Olly API use its default. To see currently supported models, ask Olly directly.

The response is JSON with:

• chat_id — save this to continue the conversation on follow-up calls.
• interaction_id — identifier for this turn.
• status — one of completed, error, stopped, or in_progress.
• response — Olly's text answer, or a short fallback message when Olly returns no text (for example, retry guidance on error or stopped).

Find and resume previous chats

Use olly_list_chats and olly_get_chat to find and resume previous investigations:

• olly_list_chats takes no parameters and returns each chat's id, title, created_at, and type.
• olly_get_chat takes a required chat_id and returns the chat's full message history as structured content blocks.

Retrieve generated artifacts

During an investigation, Olly produces artifacts: query results, metric charts, log samples, alert data, and Kubernetes resource queries.

Tool	Parameter	Description
olly_list_artifacts	chat_id (optional)	Filter artifacts to a single chat. Omit to list all artifacts.
olly_get_artifact	artifact_id (required)	Get artifact metadata and a pre-signed download_url.

olly_get_artifact returns:

• id, type, params — what the artifact is and what query produced it.
• download_url — a time-limited, pre-signed link to the artifact data. The payload is gzip-compressed JSON; decompress before parsing.

Artifact types you might see:

Type	Content
coralogix_logs	DataPrime log query results.
coralogix_spans	DataPrime span query results.
coralogix_metrics	PromQL query results.
alert_watch_data	Alert trigger data and supporting context.
kubernetes_query_results	Kubernetes resource queries.

Example prompts

Use Olly for investigation, root-cause analysis, and questions that span multiple data types.

Root-cause investigation

Why did the payments-api error rate spike in the last hour?

What is the root cause of the latest "Checkout latency p95" alert?

Investigation across data types

Compare error rates between yesterday and today for service ingest-api.

What changed in our infrastructure right before the outage at 14:30 UTC?

Continuing a conversation

After your first olly_ask, save the returned chat_id and pass it on follow-ups to keep Olly's context:

Drill into the top error from the previous answer and show me a sample log.

When to use Olly versus direct tools

Default to the direct tools. Reach for Olly only when the user explicitly asks for it or the question genuinely needs Olly's investigative reasoning — direct tools are faster and do not consume an Olly agent run.

Use Olly when	Use direct tools when
The user explicitly asks for Olly.	The user does not specifically request Olly.
You do not know the exact DataPrime or PromQL syntax.	You already have a precise query.
You need to investigate across logs, metrics, traces, and alerts in one flow.	You need one specific log set, metric series, or incident.
You want root-cause reasoning, not data retrieval.	You are listing or fetching by known ID.

For precise, known queries, use the Logs and traces, Metrics, or Alerts and incidents tools instead.

Troubleshooting

Next steps

To use Olly outside the MCP server — from the Coralogix UI or programmatically — see Olly.