Getting Started with Axle's MCP server

Quick Start

All connections use the same flow: your AI assistant registers itself, opens a browser for you to log in with your Axle account, and receives a scoped token. Your data access is limited to your organization — the same permissions as your Axle dashboard.

---

Available Tools

Once connected, your AI assistant can use these tools to help with alert review and investigation workflows:

---

Setup by Tool

Claude Desktop

1. Open Claude Desktop and go to Settings > Connectors
2. Click Add Connector
3. Enter the server URL:

   https://public.api.axleruns.com/mcp/v1

4. Click Add
5. A browser window opens — log in with your Axle account and click Allow

That's it. Claude will auto-discover the OAuth endpoints and register itself. You can now ask Claude to search your alerts, update dispositions, and more.

---

ChatGPT

1. Go to Settings > Apps & Connectors > Advanced settings
2. Toggle Developer Mode to ON
3. Click Add new connector
4. Enter a name (e.g., "Axle") and the URL:

   https://public.api.axleruns.com/mcp/v1

5. Set Authentication to OAuth
6. Check "I trust this application" and click Create
7. Complete the browser login flow

Available on ChatGPT Pro, Plus, Business, Enterprise, and Education plans (web only).

---

Open WebUI

Open WebUI has two setup roles: an admin who adds the MCP server to the shared instance, and individual users who authorize their own Axle account on first use. Each analyst authorizes once and gets a personal access scoped to their own organization.

Admin setup (once per Open WebUI instance)

1. Go to Admin Settings → Integrations (path: /admin/settings/integrations)
2. Click + to add a server
3. Set Type to MCP (Streamable HTTP)
4. Enter the URL:

   https://public.api.axleruns.com/mcp/v1

5. Set Auth to OAuth 2.1
6. Click Register Client, then Save

User setup (each analyst, once)

1. Start a new chat
2. Click the integration button directly below the chat input and enable the Axle connector
3. A browser tab opens — log in with your Axle account and click Allow
4. Return to the chat and ask the assistant to search alerts, review a disposition, etc.

Open WebUI does not support OAuth 2.1 tools as model-level defaults — each analyst must enable the Axle connector per chat via the integration button. Once authorized, the token refreshes automatically.

Important for admins: Set a persistent WEBUI_SECRET_KEY environment variable on the Open WebUI container so OAuth tokens survive container restarts.

---

Self-hosted Open WebUI (or other custom LLM chat deployments)

If you're running Open WebUI — or any other MCP client — on your own infrastructure (e.g., a shared instance for your compliance team at https://ai.yourcompany.com), the client's base URL hostname must be added to Axle's redirect URI allowlist before the OAuth flow will work. This is a deliberate security measure that prevents attackers from standing up a lookalike client to phish your analysts.

To get your hostname added:

Contact the Axle team with:

• Your base URL (e.g., https://ai.yourcompany.com) — just the hostname is needed
• The MCP client you're using (Open WebUI, LibreChat, some other custom client, etc.)

We'll confirm once the hostname is live (typically same-day). Open WebUI instances running at localhost / 127.0.0.1 work without any allowlist entry — those loopback addresses are always accepted.

---

Other MCP-Compatible Tools

Any application that supports the MCP specification with Streamable HTTP transport and OAuth 2.1 can connect. The general steps are:

1. Point the application at https://public.api.axleruns.com/mcp/v1
2. The application discovers OAuth metadata from /.well-known/oauth-authorization-server
3. It registers a client via POST /oauth/register (Dynamic Client Registration)
4. You log in through your browser and grant consent
5. The application receives tokens and begins calling MCP tools

---

Authentication Details

How It Works

Axle's MCP server uses OAuth 2.1 — the same standard used by Google, GitHub, and other major platforms. Here's what happens when you connect:

1. Client Registration — Your AI tool automatically registers itself with Axle's OAuth server. No API keys or pre-shared secrets needed.
2. Browser Login — You log in with your existing Axle account credentials (the same ones you use for the Axle dashboard).
3. Consent — You review what the tool is requesting and click Allow.
4. Token Issuance — The tool receives a short-lived access token (15 minutes) and a refresh token (14 days) to stay connected.

Scopes

When registering or authorizing, your tool may request the following scopes:

Your tool can only access data within your organization — the same boundary as your Axle dashboard.

Token Lifecycle

• Access tokens expire after 15 minutes and are automatically refreshed
• Refresh tokens are valid for 14 days (sliding — each use extends the window)
• Absolute session cap: 30 days. After 30 days from your initial authorization, the refresh chain terminates and you must re-authorize through the browser, regardless of activity. This is a hard security boundary.
• If your tool loses its connection, just re-authorize through the browser

---

Tool Reference

search_alerts

List alerts with optional filters. Returns paginated results.

Parameters:

Example prompt: "Show me all unreviewed alerts with a risk score above 0.7 from the last week"

---

list_alert_batches

List the upload batches your organization has ingested. Returns up to 200 batches, newest first. Each batch carries an upload_session_id, the number of alerts in it, and the earliest and latest alert creation timestamps in the batch. Use the upload_session_id to chain into get_batch_stats or to filter search_alerts.

Parameters: None.

Example prompt: "Show me the upload batches from the last few days."

---

get_batch_stats

For one upload batch, return the alert count plus the latest-per-alert investigation, escalation, and SAR-narrative counts. If the batch ID isn't in your organization, every count is zero.

Parameters:

Example prompt: "How many alerts and escalations are in batch batch_2026_05_18?"

---

get_alert_portfolio_stats

Get org-wide alert distributions and amount-volume rollups, optionally scoped to a date range. Returns total alert count, breakdown by status and by alert type, and total / avg / max / min transaction volume. Use this to answer "how's my queue look," "what's my escalation ratio," and similar portfolio questions.

Parameters:

Example prompt: "What's our alert volume and escalation ratio over the last 30 days?"

---

get_alerts_bulk

Fetch the full alert detail (analysis narrative, flags, analysis blocks, summary sections) for up to 20 alerts in one call. IDs that don't resolve to an alert in your organization are returned in not_found — the response does not distinguish between "doesn't exist" and "belongs to a different organization."

Parameters:

Example prompt: "Pull alerts TXN-2024-001, TXN-2024-014, and TXN-2024-031 and summarize the common themes."

---

get_flag_trends

Org-wide rollups of the customer-facing investigation flags Rose embeds in each populated analysis block (e.g. source_of_funds, transaction_risk). Returns the overall flag count plus breakdowns by color, block, and (most usefully) by flag ID — by_flag is a per-flag color breakdown that lets you ask "is flag X red more often than not over this window?"

Parameters:

Example prompt: "Over the last 30 days, has the structuring_multi_account_or_counterparty flag been red more often than not?"

---

get_alert

Fetch a single alert with its full analysis, including the investigation narrative, risk flags, and analysis blocks.

Parameters:

Example prompt: "Get the details for alert TXN-2024-001"

---

get_alert_metrics

Pull aggregated metrics and key facts for a single alert. Returns transaction totals by asset and direction over 7, 30, and 90-day windows, top counterparties by volume, flag color distribution per analysis block, the top red and yellow flag rationales, a headline executive summary, and the key entities linked to the alert. Blocks that the organization's recipe does not run come back empty.

Parameters:

Example prompt: "Give me the transaction metrics for alert TXN-2024-001 — I want to see volume by asset and the top counterparties"

---

update_alert_disposition

Update the disposition on an alert's investigation.

Parameters:

Example prompt: "Escalate alert TXN-2024-001"

---

undo_disposition

Revert the most recent disposition change on an alert. Only works if the change was made by you within the last 5 minutes. Adds a new audit row tagged as an undo — the history is preserved.

Parameters:

Example prompt: "Undo the disposition I just set on alert TXN-2024-001 — I meant to escalate, not clear"

---

submit_alert_feedback

Record feedback on a specific risk flag within an alert's investigation.

Parameters:

Example prompt: "On alert TXN-2024-001, the structuring flag in the transaction analysis block should be red — the entity split deposits across 5 accounts within 24 hours"

---

upload_supplemental_entity_data

Attach additional identifying information to entities referenced by an alert. This enriches future investigations.

Parameters:

Each entity object:

Entities uploaded through this tool are typed as individuals. For richer fields (tax residency, country of birth, UBO trees, etc.) use the REST entity upload API directly.

---

predict_rerun_impact

Predict — without triggering a rerun — which analysis blocks will change if the investigation is rerun with your feedback. Returns a one-sentence summary of what was understood, plus two lists: blocks that will likely change (directly_affected) and blocks that are mentioned but unlikely to change (references). Use the directly_affected list as the modules_to_rerun input when calling rerun_investigation for a targeted, faster rerun.

Parameters:

Example prompt: "If I rerun TXN-2024-001 with the note that the $50K wire was a real estate closing, which blocks will change?"

---

rerun_investigation

Trigger a fresh Rose investigation for an alert. Pass modules_to_rerun (from predict_rerun_impact) for a targeted rerun that only re-runs the affected blocks and copies the rest forward unchanged — faster and cheaper than a full rerun.

Parameters:

Example prompt: "Rerun the investigation for alert TXN-2024-001 — new entity data was uploaded"

---

add_block_note

Add an analyst note to a specific analysis block of an investigation. Notes are visible in the Axle dashboard and influence future reruns.

Parameters:

Example prompt: "Add a note to the transaction analysis block of alert TXN-2024-001: the $50K wire was a legitimate real estate closing, classification reviewed_correct"

---

Troubleshooting

"Connection failed" or "Server not reachable"

• Verify you can reach https://public.api.axleruns.com/.well-known/oauth-authorization-server in your browser
• Check that your network/VPN allows outbound HTTPS to public.api.axleruns.com

OAuth login loop or blank page

• Clear your tool's cached MCP credentials and re-add the connection
• Ensure your browser allows popups from your AI tool

"Unauthorized" or "Token expired"

• Most AI assistants auto-refresh tokens. If you see persistent auth errors, remove and re-add the MCP connection
• Access tokens expire every 15 minutes; refresh tokens last 14 days

"Alert not found"

• The alert_id parameter expects the alert ID from your system, not the Axle internal ID
• You can only access alerts in your organization

Tools not appearing

• After connecting, you may need to start a new chat or conversation for tools to be listed
• In Claude Desktop, check Settings > Connectors to verify the connection is active
• In ChatGPT, verify the connector is listed under Settings > Apps & Connectors
• In Open WebUI, make sure your admin has added the Axle server under Admin Settings → Integrations, then enable the Axle connector per chat via the integration button below the chat input

Open WebUI: "Failed to connect to MCP server" when starting a chat

• Open WebUI cannot run the OAuth browser flow from a pre-enabled tool — each analyst must enable the Axle connector per chat via the integration button below the chat input, which triggers the browser authorization
• Once a user has authorized once, token refresh is automatic for that user's subsequent chats