> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiaxoniq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP) Server

> Connect AI coding assistants and autonomous agents to aiAxonIQ with 25 secure MCP tools, cursor-based pagination, and human-confirmed remediation.

The **aiAxonIQ MCP Server** connects AI development environments — including Claude Code, Cursor, Windsurf, and custom autonomous agents — directly to your observability plane over the open [Model Context Protocol](https://modelcontextprotocol.io) specification (`2026-07-28`).

Instead of copying logs or query snippets back and forth into chat windows, your AI tools can inspect traces, query metrics, search structured logs, check service health, and run root cause investigations on production incidents in real time.

<Info>
  **Security & Tenant Isolation.** The MCP server is a read-only transport over aiAxonIQ's cost-guarded query layer. Tenants cannot be spoofed, ClickHouse queries have a strict 200,000,000 estimated-row ceiling, and write actions require an explicit human confirmation token.
</Info>

## Capabilities and Tools

The MCP server exposes 12 production-ready tools (11 read-only analysis tools and 1 human-confirmed remediation tool):

| Tool                   | Mode / Scope               | Description                                                                                    |
| :--------------------- | :------------------------- | :--------------------------------------------------------------------------------------------- |
| `get_trace`            | `traces:read`              | Fetches full distributed span trees with parent-child relationships and error tags.            |
| `query_metrics`        | `metrics:read`             | Evaluates Prometheus PromQL or ClickHouse metrics with rollups over custom time windows.       |
| `search_logs`          | `logs:read`                | Runs BM25 full-text and structured JSON field search with automatic pattern clustering.        |
| `get_service_health`   | `services:read`            | Returns golden signals (P50/P95/P99 latency, error rate, throughput) for any service.          |
| `get_topology`         | `services:read`            | Maps upstream and downstream microservice dependencies auto-discovered from live spans.        |
| `get_slo_status`       | `alerts:read`              | Returns error budget consumption and multi-window burn rate calculations.                      |
| `investigate_incident` | `traces:read`, `logs:read` | Runs multi-signal correlation across traces, logs, and metrics to rank root cause candidates.  |
| `explain_anomaly`      | `metrics:read`             | Compares current metric behavior with historical baseline using Z-score and IQR models.        |
| `search_knowledge`     | `alerts:read`              | Searches indexed runbooks and past incident post-mortems via embedding similarity.             |
| `list_incidents`       | `alerts:read`              | Lists active and recently mitigated incidents with triage metadata.                            |
| `check_cost_guard`     | `metrics:read`             | Validates query complexity and row estimates before executing large forensic queries.          |
| `remediate_incident`   | `remediation:write`        | Initiates mitigation actions (sealed `requestState` requiring human-in-the-loop confirmation). |

## Connecting Clients

### Claude Desktop & Claude Code

Add the aiAxonIQ MCP server to your Claude configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "aiaxoniq": {
      "command": "npx",
      "args": [
        "-y",
        "@aiaxoniq/mcp-server"
      ],
      "env": {
        "AIAXONIQ_API_KEY": "oiq_live_your_api_key_here",
        "AIAXONIQ_ENDPOINT": "https://app.aiaxoniq.com"
      }
    }
  }
}
```

### Cursor & Windsurf

In Cursor or Windsurf, navigate to **Settings** → **Features** → **MCP Servers** and click **Add New MCP Server**:

* **Name:** `aiAxonIQ`
* **Type:** `command`
* **Command:** `npx -y @aiaxoniq/mcp-server`
* **Environment Variables:**
  * `AIAXONIQ_API_KEY`: Your service account or user API key.
  * `AIAXONIQ_ENDPOINT`: `https://app.aiaxoniq.com`.

## Safety Guarantees

<Steps>
  <Step title="Tenant Sandboxing">
    The MCP server extracts tenant context strictly from verified cryptographic API tokens. No caller argument can specify or override tenant ID, account ID, or target database tables.
  </Step>

  <Step title="Cost Guard Protection">
    Every forensic query against ClickHouse is subject to cost-guard verification. Queries exceeding resource budgets or estimated row limits are safely bounded.
  </Step>

  <Step title="Sealed Write Confirmation">
    The `remediate_incident` tool cannot execute autonomously. It returns a cryptographically signed confirmation challenge. The action only executes when an authorized human operator approves the payload in the aiAxonIQ dashboard.
  </Step>
</Steps>