# Olly

Use the Coralogix MCP server to send natural-language investigation requests to [Olly](https://coralogix.com/docs/user-guides/olly/index.md), 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](https://coralogix.com/docs/user-guides/mcp-server/setup/index.md)).
- 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](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/index.md). 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:

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

#### API key

If you authenticate with a personal [Coralogix API key](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/index.md) instead of OAuth, add the same two headers alongside `Authorization`:

```json
{
  "mcpServers": {
    "coralogix-server": {
      "url": "https://api.[[DOMAIN_VALUE]]/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:

```bash
claude mcp add --transport http coralogix-server https://api.[[DOMAIN_VALUE]]/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`:

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

| Tool                  | Description                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `olly_ask`            | Send a natural-language question to Olly and wait for a response. Starts a new chat when you omit `chat_id`. |
| `olly_list_chats`     | List your previous Olly chat sessions.                                                                       |
| `olly_get_chat`       | Retrieve a chat's full conversation history.                                                                 |
| `olly_list_artifacts` | List query results, charts, and other artifacts Olly generated.                                              |
| `olly_get_artifact`   | Get an artifact's metadata and a pre-signed download URL.                                                    |

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

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

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

### Investigation across data types

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

```text
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:

```text
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](https://coralogix.com/docs/user-guides/mcp-server/tools/logs-and-traces/index.md), [Metrics](https://coralogix.com/docs/user-guides/mcp-server/tools/metrics/index.md), or [Alerts and incidents](https://coralogix.com/docs/user-guides/mcp-server/tools/alerts-and-incidents/index.md) tools instead.

## Troubleshooting

| Symptom                                                                                             | Cause                                                                              | Resolution                                                                                                  |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Olly tools do not appear in your client's tool list.                                                | The `x-allow-costly-use: true` header is missing or has a different value.         | Add the header to your MCP server configuration in your client and reconnect.                               |
| Olly tools do not appear in your client's tool list, and `x-allow-costly-use: true` is already set. | The `mcp-version: v2` header is missing. Olly tools are v2-only.                   | Add `mcp-version: v2` alongside `x-allow-costly-use: true` in your MCP server configuration and reconnect.  |
| `olly_ask` returns a 401 or 403.                                                                    | Your token or API key lacks permission to call Olly or access the underlying data. | Verify your Coralogix authentication, API key scopes, and that Olly is available in your account.           |
| `olly_ask` returns `status: error` or `stopped` with no text.                                       | Olly did not finish the interaction.                                               | Retry with the same `chat_id` to preserve context, or call `olly_get_chat` to inspect the full interaction. |
| Artifact download fails.                                                                            | The pre-signed URL has expired.                                                    | Request the artifact again with `olly_get_artifact` to get a fresh URL.                                     |

## Next steps

To use Olly outside the MCP server — from the Coralogix UI or programmatically — see [Olly](https://coralogix.com/docs/user-guides/olly/index.md).