Axiom MCP Server

This page explains how to get deeper insights with Axiom MCP Server.

Axiom MCP Server is a Model Context Protocol server implementation that enables AI agents to query your data using Axiom Processing Language (APL).

For guidance on when to use Axiom MCP Server and Axiom Skills, see AI agents.

If your agent doesn’t have an Axiom organization to work in yet, it can provision a temporary one itself and hand you a claim link later. For more information, see Agent-created organizations.

Current capabilities

Supported MCP tools

Axiom MCP Server supports the following MCP tools:

checkMonitors: Check all monitors and their current statuses
createDashboard: Create a dashboard from a JSON document
createMonitor: Create a new monitor
createNotifier: Create a new notifier
deleteDashboard: Delete a dashboard by UID
deleteMonitor: Delete a monitor by ID
deleteNotifier: Delete a notifier by ID
exportDashboard: Export a dashboard as JSON
getDashboard: Get dashboard details
getDatasetSchema: Get dataset schema
getMetricTagValues: Get values for a specific tag in a dataset
getMonitorHistory: Get alert history for a specific monitor
getSavedQueries: Retrieve saved APL queries
listDashboards: List dashboards
listDatasets: List available Axiom datasets
listMetricTags: List tags available for filtering in a dataset
listMetrics: List available metric names in a dataset
listNotifiers: List all configured notifiers
queryApl: Execute APL queries against Axiom datasets
queryMetrics: Execute MPL queries against Axiom datasets
searchMetrics: Search for metrics matching a known tag value
updateDashboard: Update a dashboard by UID
updateDashboardChart: Patch a single chart in an existing dashboard by chart ID
updateMonitor: Update an existing monitor by ID
updateNotifier: Update an existing notifier by ID

Supported MCP prompts

Axiom MCP Server supports the following MCP prompts:

correlate-events-across-datasets: Find patterns and correlations between events across multiple datasets
data-quality-investigation: Investigate data quality issues including missing data, inconsistencies, and collection problems
detect-anomalies-in-events: Generic anomaly detection using statistical analysis and pattern recognition across any dataset
establish-performance-baseline: Establish performance baselines for a dataset to enable effective monitoring and anomaly detection
explore-unknown-dataset: Exploration of an unknown dataset to understand its structure, content, and potential use cases
monitor-health-analysis: Comprehensive analysis of monitor health, alert patterns, and effectiveness

Axiom plans to support MCP resources in the future.

Axiom MCP Server works with all AI agents that support MCP.

Query results routing

The Axiom-hosted MCP Server is located in the US. When you query your data using the Axiom MCP Server using a remote MCP connection, query results are routed through US infrastructure.

Prerequisites

Create an Axiom account.
Create a dataset in Axiom where you send your data.

Setup

Claude

If you’re on the Pro, Team, or Enterprise plan:

Add Axiom to the list of remote MCP servers:
- If you’re on the Pro plan, follow the Claude documentation to add Axiom to the list of remote MCP servers using the URL https://mcp.axiom.co/mcp.
- If you’re on the Team or Enterprise plan, ask your organization admin to follow the Claude documentation to add Axiom to the list of remote MCP servers using the URL https://mcp.axiom.co/mcp.
In Claude.ai or Claude Desktop, go to Settings > Connectors.
Find Axiom in the list.
Click Connect.
Authenticate the request in your browser.

In Claude Code, follow the Claude Code documentation to add Axiom to the list of remote MCP servers using the URL https://mcp.axiom.co/mcp.

If you’re on the Free plan:

Install Claude Desktop.
In Claude Desktop, go to Settings > Developers, and then click Edit Config.

Add the following to claude_desktop_config.json:

{
    "mcpServers": {
        "axiom": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://mcp.axiom.co/mcp"
            ]
        }
    }
}

Restart Claude Desktop.
Authenticate the request in your browser.

Cursor

Install Cursor.
Install Axiom MCP Server.
Authenticate the request in your browser.

Other clients

If your agent supports connecting to remote MCP servers directly:

In your AI agent, add a remote MCP connection with the following details:
- Name: Axiom
- Server URL: https://mcp.axiom.co/mcp
For AI agents that require server-sent events (SSE), use the server URL https://mcp.axiom.co/sse.
Authenticate the request in your browser. You can later revoke access on the Profile page of the Axiom Console.

If your agent doesn’t support connecting to remote MCP servers directly, use the mcp-remote library:

Add the mcp-remote library to the configuration file of your AI agent. For example:

{
    "mcpServers": {
        "axiom": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://mcp.axiom.co/mcp"
            ]
        }
    }
}

Restart your AI agent.
Authenticate the request in your browser. You can later revoke access on the Profile page of the Axiom Console.

Header-based authentication

If your AI agent doesn’t support browser-based OAuth authentication (for example, Agent Builder from OpenAI), authenticate by passing headers directly:

Create a personal access token.
Determine organization ID.
Configure your AI agent to use the server URL https://mcp.axiom.co/mcp.
Configure your AI agent to send the following headers with each request to the server URL:
- Authorization: Bearer PERSONAL_ACCESS_TOKEN
- x-axiom-org-id: ORGANIZATION_ID
Info
Replace PERSONAL_ACCESS_TOKEN with the personal access token you have generated.
Replace ORGANIZATION_ID with your organization ID. For more information, see Determine organization ID.

If your AI agent only supports setting the Authorization header, pass the organization ID as a URL parameter: https://mcp.axiom.co/mcp?org-id=ORGANIZATION_ID

The setup explained above uses a remote MCP connection and is the recommended approach for most use cases. Alternatively, deploy Axiom MCP Server locally on your machine for more control.

Local setup

With the local setup:

You run Axiom MCP Server yourself.
You authenticate using an API token instead of OAuth 2.0.
You can’t use the MCP prompts mentioned in Current capabilities.

Install

Run the following to install the latest built binary from GitHub:

go install github.com/axiomhq/axiom-mcp@latest

Create API token

Create an API token in Axiom with permissions to update the dataset you have created.

Configure

Configure your AI agent to use the MCP Server in one of the following ways:

Use a config file
Use environment variables

Config file

Create a config file where you specify the authentication and configuration details. For example:
```
token API_TOKEN
url https://api.axiom.co
query-rate 1
query-burst 1
datasets-rate 1
datasets-burst 1
monitors-rate 1
monitors-burst 1
```
Info
Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Optionally, configure the rate and the burst limits at the query, dataset, and monitor levels. The rate limit is the maximum number of requests that your AI agent can make per second. The burst limit is the maximum number of requests that your AI agent can make in a short period (burst) before the rate limit applies to further requests.
In the settings of your AI agent, reference the binary file of Axiom MCP Server and the config file you have previously created.

For example, if you use the Claude desktop app, add axiom to the mcpServers section of the Claude configuration file. The default path is ~/Library/Application Support/Claude/claude_desktop_config.json on MacOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.
```
{
  "mcpServers": {
    "axiom": {
      "command": "PATH_AXIOM_MCP_BINARY",
      "args": [
        "--config",
        "PATH_AXIOM_MCP_CONFIG"
      ]
    }
  }
}
```
Info
Replace PATH_AXIOM_MCP_BINARY with the path the binary file of Axiom MCP Server.
Replace PATH_AXIOM_MCP_CONFIG with the path the config file you have previously created.

Environment variables

In the settings of your AI agent, use environment variables to specify the authentication details and the binary file of Axiom MCP Server.

For example, if you use the Claude desktop app, add axiom to the mcpServers section of the Claude configuration file. The default path is ~/Library/Application Support/Claude/claude_desktop_config.json on MacOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

{
  "mcpServers": {
    "axiom": {
      "command": "PATH_AXIOM_MCP_BINARY",
      "env": {
        "AXIOM_TOKEN": "API_TOKEN",
        "AXIOM_URL": "https://api.axiom.co",
        "AXIOM_QUERY_RATE": "1",
        "AXIOM_QUERY_BURST": "1",
        "AXIOM_DATASETS_RATE": "1",
        "AXIOM_DATASETS_BURST": "1",
        "AXIOM_MONITORS_RATE": "1",
        "AXIOM_MONITORS_BURST": "1"
      }
    }
  }
}

Optionally, configure the rate and the burst limits at the query, dataset, and monitor levels. The rate limit is the maximum number of requests that your AI agent can make per second. The burst limit is the maximum number of requests that your AI agent can make in a short period (burst) before the rate limit applies to further requests.

Token hygiene

The remote MCP Server uses OAuth for authentication which handles credential isolation automatically. Agents never see your tokens. You can revoke access at any time.

For the local setup or when using Axiom Skills, you configure API tokens directly. For detailed guidance on secure token configuration, see Token hygiene for AI agents.

Limit query costs

Query cost limits let you cap the hourly and daily query costs of an AI agent so it can query your data autonomously without creating unexpected costs:

For the local setup, set query cost limits on the API token you create for the agent.
For the remote MCP Server, the agent acts as your user account through OAuth, so set query cost limits on your roles instead.

For more information, see Set query cost limits for AI agents.

Use MCP Server

After setting up the Axiom MCP Server, you can:

Ask your own questions about your event data. For example:
- “List datasets.”
- “Get the data schema for the dataset logs.”
- “Get the most common status codes in the last 30 minutes in the dataset logs.”
Use the prebuilt prompts. For example, in Claude, click + > Add from Axiom to access them.

To answer your questions, your AI client can use the supported MCP tools.

Revoke access

Using the procedure above, you authorized your AI client to access your event data in Axiom.

To revoke access:

In Axiom, go to Settings > Profile.
In the Sessions section, find the session where you authorized your AI client, and then click Delete on the right.

If you connected to Axiom MCP Server using the mcp-remote library, clear the .mcp-auth folder. This is where Axiom MCP Server stores credential information. On a Mac, the default path is ~/.mcp-auth.