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"

---

rose_search

Find records by ID across alerts, entities, and transactions in a single call. Give it an ID from your system, an Axle axle_id, or just a fragment of one — it matches as a case-insensitive substring against both ID fields. A given ID usually belongs to only one record type, so most of the result groups are typically empty. Results are compact pointers; follow up with get_alert, get_entity, or get_transaction for the full record.

Parameters:

Example prompt: "Find whatever record matches the ID dd86b2cc — could be an alert, an entity, or a transaction."

---

search_rose_investigations

Meaning-based ("semantic") search over your organization's past investigations. Instead of exact filters, you describe the kind of case you're looking for in plain language and get back the closest-matching investigations. Numeric, date, disposition, and analysis-area constraints written into the query (for example "escalated structuring cases with a risk score above 70 in the last 90 days") are understood and applied automatically; you can also pass them as structured parameters below. Each result includes a similarity score, a short snippet of the matching text, the analysis area it came from, and the alert ID — use that alert ID with get_alert or get_alert_metrics to read the full case.

This tool must be enabled for your organization before it can be used. If it isn't yet, ask your Axle contact.

Parameters:

Example prompt: "Find past investigations similar to a customer running rapid pass-through transfers just under the reporting threshold"

---

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"

---

get_entity

Look up a single entity by its Axle axle_id and return basic identity, contact, and KYC fields (name, type, status, date of birth, nationality, occupation, emails, phone numbers, mailing location, source of funds, and more).

Parameters:

Example prompt: "Show me the entity with axle_id axl_1a2b3c"

---

get_transaction

Look up a single transaction by its Axle axle_id and return its core fields (amount, currency, balance, sender/receiver, type, event time, and status).

Parameters:

Example prompt: "Pull up the transaction with axle_id axl_9z8y7x"

---

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 or new information. 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).

Useful for routing a specific fact to the right block before calling add_block_note. For broad, cross-cutting facts (see add_block_note below), you can skip this step and use block_type="general" directly.

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.

• When adding new facts (added_facts notes): omit modules_to_rerun so the full pipeline re-runs. Every analysis block and the zero-shot synthesis will see the new facts.
• When correcting specific blocks: pass modules_to_rerun with the directly_affected block IDs from predict_rerun_impact to scope the rerun to only those blocks.

added_facts notes are automatically carried forward to the new investigation, so you do not need to re-add them if you rerun again later.

Parameters:

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

---

add_block_note

Add a note to an investigation block. Supports two distinct use cases:

Correcting existing output — use when Rose produced an analysis you want to flag as wrong, incomplete, or in need of context:

Use a specific block name from get_alert's analysis_blocks list. After adding, call predict_rerun_impact to identify which blocks to re-run, then rerun_investigation with modules_to_rerun.

Adding new facts Rose didn't have — use classification="added_facts" when you have information that wasn't available during the original investigation:

• Cross-cutting facts (e.g. "customer is a licensed money transmitter", "this counterparty is our internal settlement account"): use block_type="general". The fact is injected into every analysis block prompt and the zero-shot synthesis.
• Targeted facts (e.g. "that transaction was a salary payment, not gambling income"): use the specific block name. The fact only injects into that block's prompt (and the synthesis).

added_facts notes persist automatically into future reruns — you don't need to re-add them each time. After adding, call rerun_investigation without modules_to_rerun (full pipeline).

Parameters:

Example — correcting output: "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"

Example — adding a fact: "Add a general fact to alert TXN-2024-001: the customer holds a state-issued money transmitter licence, classification added_facts"

---

create_support_ticket

File a support ticket to the Axle team for an issue or request that needs their attention. This is a last resort — for input on a specific investigation, use add_block_note (to annotate an analysis block) or submit_alert_feedback (to correct a flag) first. Use a ticket only when the matter doesn't fit a note or flag (for example, a product bug, a data problem, or a broader request).

You don't write the ticket yourself — your assistant composes a clear title and description by summarizing your conversation, including your latest message. The ticket also records your organization, your user, and the conversation it came from automatically, so the Axle team can follow up. When the conversation is about a specific alert, include the alert_id so the alert's context is attached too. If the feedback is about one specific risk flag or report section you can see in Axle, your assistant can note which one via report_area — this helps the Axle team pinpoint what you're referring to.

Your assistant confirms when the ticket has been sent to the Axle team. The team triages it and follows up through your normal support channel.

Parameters:

Example prompt: "Something looks off about how alert TXN-2024-001 was scored — file a support ticket with the Axle team about it."

---

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

"Entity not found" or "Transaction not found"

• Unlike the alert tools, get_entity and get_transaction expect the Axle axle_id — not the entity or transaction ID from your own system. If you paste your own ID (e.g. a transaction hash or customer reference), the lookup returns "not found" by design.
• The axle_id is the value shown in the axle_id field of other tool responses (for example, the entities listed by get_alert_metrics). The quickest way to resolve your own ID to an axle_id is rose_search — ask your assistant to search for the ID, then look up the entity or transaction by the axle_id it surfaces. (You can also pull the alert first and read the axle_id from there.)

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