Getting Started with Axle's MCP server

Connect your AI assistant to Axle's MCP (Model Context Protocol) server to search alerts, update dispositions, submit feedback, and more — directly from Claude or ChatGPT.

Quick Start

DetailValue
MCP Server URLhttps://public.api.axleruns.com/mcp/v1
OAuth Discoveryhttps://public.api.axleruns.com/.well-known/oauth-authorization-server
TransportStreamable HTTP
AuthenticationOAuth 2.1 with PKCE (S256)
Client RegistrationDynamic (automatic) — no pre-shared credentials needed

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:

ToolDescription
search_alertsList alerts with filters (disposition, risk score range, date range, alert ID, upload batch)
rose_searchFind records by ID (or a fragment of one) across alerts, entities, and transactions in one call
search_rose_investigationsMeaning-based search over past investigations — describe what you're looking for in plain language and get the closest-matching cases back
list_alert_batchesList recent upload batches with alert count and date range
get_batch_statsPull alert / investigation / escalation / SAR counts for one upload batch
get_alert_portfolio_statsOrg-wide alert counts and volume rollups, optionally scoped to a date range
get_alerts_bulkFetch full detail for up to 20 alerts in one call (for summarizing or comparing several at once)
get_flag_trendsInvestigation-flag counts by color, block, and flag ID — answers "is flag X red more often than not?"
get_alertFetch a single alert with its full analysis narrative, flags, and risk score
get_related_alertsOther alerts sharing an entity with a given alert, within a lookback window
get_alert_metricsPull aggregated transaction metrics, top counterparties, flag distribution, and key entities for an alert
list_alert_investigationsList every prior investigation of an alert, newest first, with each run's own outcome
compare_investigationsShow what changed between two investigations of the same alert, module by module
get_entityLook up a single entity by its axle_id — identity, contact, and KYC fields
get_entity_alertsAlerts touching a given entity within a lookback window
get_transactionLook up a single transaction by its axle_id — amount, parties, type, and timing
update_alert_dispositionSet an alert's disposition to ESCALATED or CLEARED
undo_dispositionRevert the most recent disposition change (only within 5 minutes and only if you made the change)
update_alert_dispositions_bulkSet the same disposition on up to 50 alerts in one call (requires the separate alerts:bulk_write scope)
undo_dispositions_bulkRevert every change from one bulk-disposition batch (only within 60 minutes and only if you made the batch)
submit_alert_feedbackRecord feedback on a specific flag (color + optional context)
upload_supplemental_entity_dataAttach identifying information (name, DOB, email, etc.) to entities on an alert
predict_rerun_impactPredict which analysis blocks will change if the investigation is rerun with analyst feedback
rerun_investigationTrigger a fresh investigation for an alert
get_rerun_statusCheck whether a rerun you started has finished
add_block_noteAdd an analyst note to a specific analysis block
propose_bulk_facts_rerunPreview attaching a fact to many alerts and rerunning each — resolves the alerts and returns a proposal to review; writes nothing (requires the separate alerts:bulk_rerun scope)
confirm_bulk_facts_rerunApply a previewed bulk-facts proposal: write the note on every alert and queue every rerun — irreversible
get_bulk_rerun_statusCheck progress of a confirmed bulk-facts rerun, and what each alert came back as, in one call
create_support_ticketFile a support ticket to the Axle team (last resort — prefer notes and flag feedback first)

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).

Before connecting ChatGPT, check where your data will go. Alert, entity, and transaction data returned by Axle is processed by OpenAI under the terms of your ChatGPT plan. Business, Enterprise, and Education workspaces do not use your data for model training by default; on personal Plus and Pro accounts it may be used for training unless that is turned off under Settings > Data Controls. For regulated customer data, we recommend connecting from a Business or Enterprise workspace, and confirming with your compliance team first.

Grant only the permissions you need. Developer Mode connectors can call write tools with less confirmation than published apps. If your analysts only need to read and research alerts, approve alerts:read (plus entities:read / transactions:read if needed) and leave the write and bulk permissions off the consent screen.


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. How long each authorization lasts depends on how Open WebUI registered itself; see Token Lifecycle.

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:

ScopeGrants
alerts:readSearch and view alerts in your organization
alerts:writeUpdate dispositions, upload entity data, rerun investigations
alerts:bulk_writeUpdate or undo dispositions on many alerts in one call — separate from alerts:write so a client can be granted one without the other
alerts:bulk_rerunAttach a fact to many alerts and rerun each one in a single call — separate from alerts:write and alerts:bulk_write so a client can be granted disposition changes without bulk reruns, or vice versa
entities:readLook up entities by axle_id (get_entity)
transactions:readLook up transactions by axle_id (get_transaction)
feedback:writeSubmit flag feedback and analyst notes
tickets:writeFile support tickets to the Axle team

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

Token Lifecycle

How long a connection lasts depends on whether your tool registered with a client secret, and the two cases behave quite differently.

Tools that register without a client secret — the common case for desktop and browser-based assistants, which have nowhere safe to keep one — receive a 1-hour access token and no refresh token. There is no background renewal: when the hour is up, you re-authorize through the browser. If you find yourself clicking Allow about once an hour, that is expected rather than a fault.

Tools that register with a client secret receive a 15-minute access token plus a 14-day refresh token, and renew in the background without involving you. The refresh window slides forward each time it is used.

Absolute session cap: 30 days. Thirty days after 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, re-authorize through the browser.


Tool Reference

search_alerts

List alerts with optional filters. Returns paginated results.

Parameters:

NameTypeRequiredDescription
dispositionstringNoFilter by disposition, using its name rather than its display text: NOT_REVIEWED, UNRESOLVED, FALSE_POSITIVE, ESCALATED, CLEARED, TRUE_POSITIVE, CASE_CREATED, CLOSED, UNDER_INVESTIGATION, MONITORING, POTENTIAL_MATCH_UNABLE_TO_CLEAR, CREATE_A_CASE, NON_REFERRAL, NON_REFERRAL_ALT, ESCALATION, ESCALATION_ALT, ESCALATION_RFI, ESCALATED_WITH_RFI, REPETITIVE, DUPLICATE, or CLOSE_LINKED_TO_CASE. NOT_REVIEWED also matches alerts that have no disposition set at all.
min_risk_scorefloatNoMinimum risk score (0.0 to 1.0)
max_risk_scorefloatNoMaximum risk score (0.0 to 1.0)
created_afterstringNoISO 8601 datetime — only alerts created after this date
created_beforestringNoISO 8601 datetime — only alerts created before this date
source_idstringNoFilter by alert ID
upload_session_idstringNoFilter by upload batch — get the value from list_alert_batches
pageintNoPage number (default: 1)
page_sizeintNoResults per page, 1–50 (default: 10)

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:

NameTypeRequiredDescription
qstringYesAn ID — or a fragment of one — to look for. Matched against both the ID from your system and the Axle axle_id. Minimum 3 characters.
scopestringNoWhich record types to search: all (default), investigations, alerts, entities, or transactions. investigations and alerts both search your alerts.
pageintNoPage number (default: 1)
page_sizeintNoResults per page, 1–50 (default: 10)

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:

NameTypeRequiredDescription
querystringYesPlain-language description of the investigations you're looking for (3–1024 characters)
top_kintNoMaximum number of investigations to return, 1–25 (default: 5)
dispositionstringNoRestrict to a final disposition (ESCALATED or CLEARED)
min_risk_scorefloatNoMinimum final risk score (0 to 100)
max_risk_scorefloatNoMaximum final risk score (0 to 100)
modulestringNoRestrict the matched text to a specific analysis area

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:

NameTypeRequiredDescription
upload_session_idstringYesThe batch ID — get it from list_alert_batches

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:

NameTypeRequiredDescription
date_fromstringNoISO 8601 datetime — lower bound on alert creation (inclusive). Omit for full history.
date_tostringNoISO 8601 datetime — upper bound on alert creation (inclusive). Omit for full history.

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:

NameTypeRequiredDescription
alert_idslist of stringsYesThe alert IDs from your system. Minimum 1, maximum 20 per call.

Two dispositions, and they disagree: each result carries analyst_disposition (your analyst's own decision, from the alert) and final_disposition (what the latest investigation decided — ESCALATED or CLEARED, or null if none has completed). Re-running an alert changes the second and never the first, so an alert re-run since it was dispositioned reports the older analyst decision beside the newer run's score. final_risk_score belongs to final_disposition.

Breaking change. The field previously called disposition is now analyst_disposition, and the new final_disposition sits beside it. The same rename applies to get_alert. Integrations reading disposition off these responses must be updated.

To find out how a bulk re-run turned out, use get_bulk_rerun_status rather than reading the batch's alerts back through this tool — it reports each alert's outcome in one call, and these payloads are large enough that a whole batch will not fit in one turn.

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?"

A single call aggregates at most the 1,000 most recent investigations in the window. When that limit is reached, truncated comes back true and investigations_scanned tells you how many investigations fed the rollups — the results then lean toward recent activity rather than covering the whole window, so narrow date_from / date_to if you need complete coverage.

Parameters:

NameTypeRequiredDescription
date_fromstringNoISO 8601 datetime — lower bound on investigation creation (inclusive)
date_tostringNoISO 8601 datetime — upper bound on investigation creation (inclusive)

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:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system

Carries the same two dispositions as get_alerts_bulk: analyst_disposition (your analyst's own, renamed from disposition — a breaking change) and final_disposition (the latest investigation's).

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


get_related_alerts

Find other alerts that share an entity with a given alert, within a lookback window. The alert you name is never included in its own results. Use this to answer "has this customer had other alerts recently" without paging through search_alerts, which has no entity filter — pair it with get_alert or get_alerts_bulk to see the detail on whatever comes back.

Parameters:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system
lookback_daysintNoHow many days back from now to look, based on each alert's own creation date, not when it was received (default 30, maximum 365)
limitintNoMaximum number of alerts to return, newest first (default 50, maximum 50)

Includes alerts of every status, open and closed. If more alerts exist in the window than fit in one response, truncated comes back true — narrow lookback_days for full coverage rather than treating the count as complete.

Example prompt: "Has this customer had any other alerts in the last two weeks?" (while looking at 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:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system

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


list_alert_investigations

List every prior investigation of an alert, newest first, with each run's own outcome. Alerts are investigated more than once whenever a rerun happens (a correction, a new fact, an updated analysis), and this is how you see that history instead of only ever seeing the latest run. Test and internal-only runs are excluded.

Parameters:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system

Response fields:

FieldDescription
analyst_dispositionYour analyst's own decision on the alert — one value for the whole alert, not per run
investigationsOne row per investigation, newest first — see below

Each investigations row:

FieldDescription
investigation_axle_idThis run's own identifier — pass it to compare_investigations
ran_atWhen this run happened
is_latestWhether this is the current, most recent run
processing_statusThe run's own status
final_risk_scoreThe risk score this run produced
final_dispositionWhat this run decided — ESCALATED or CLEARED, or null if it never completed

final_disposition is what a given run decided; analyst_disposition on the response is your analyst's own call and does not change from run to run. Keep the two separate when reporting — they are two different decisions, not two spellings of one.

Example prompt: "Has alert TXN-2024-001 been rerun before, and what did the earlier run decide?"


compare_investigations

Show what changed between two investigations of the same alert, module by module: score movement, which flags flipped color, and whether the analysis was recomputed or carried forward unchanged. Defaults to comparing the alert's newest investigation against the one before it — get the investigation_axle_id values from list_alert_investigations to compare a specific pair instead.

Parameters:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system
baselinestringNoThe earlier investigation's investigation_axle_id. Defaults to the run immediately before after.
afterstringNoThe later investigation's investigation_axle_id. Defaults to the alert's newest investigation.
modulestringNoName one analysis area (from get_alert's analysis_blocks) to also see its full before/after write-up. Omitted otherwise to keep the response manageable.

Response fields:

FieldDescription
baseline, afterSummary of each side: its investigation_axle_id, when it ran, its risk score, and its outcome
risk_score_deltaHow much the overall risk score moved
disposition_changedWhether the outcome (ESCALATED/CLEARED) changed between the two runs
config_matchesWhether both runs used the same underlying configuration, when known
modulesPer-module detail — see below
only_in_baseline, only_in_afterAnalysis areas that ran on one side only

Each modules row: its name, whether it was recomputed, carried forward unchanged, or failed, the score and contribution on each side, whether any flags flipped color, and (only when you named this module in module) the full before/after write-up.

If the alert has only one investigation, there is nothing to compare it against: baseline comes back null and every module is reported from the single run alone.

Example prompt: "What changed between the last two runs of alert TXN-2024-001?"


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:

NameTypeRequiredDescription
entity_axle_idstringYesThe entity's axle_id (the Axle identifier, not the entity ID from your system)

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


get_entity_alerts

Find alerts touching a given entity within a lookback window. Unlike get_entity, this accepts the entity ID from your own system directly — it also accepts the Axle axle_id as a fallback if that's what you have.

Parameters:

NameTypeRequiredDescription
entity_idstringYesThe entity ID from your system, or its Axle axle_id
lookback_daysintNoHow many days back from now to look, based on each alert's own creation date, not when it was received (default 30, maximum 365)
limitintNoMaximum number of alerts to return, newest first (default 50, maximum 50)

Includes alerts of every status, open and closed. If more alerts exist in the window than fit in one response, truncated comes back true — narrow lookback_days for full coverage rather than treating the count as complete.

Example prompt: "Find alerts for customer CUST-4471 in the last week."


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:

NameTypeRequiredDescription
transaction_axle_idstringYesThe transaction's axle_id (the Axle identifier, not the transaction ID from your system)

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


update_alert_disposition

Update the disposition on an alert's investigation.

Parameters:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system
dispositionstringYesOne of: ESCALATED, CLEARED

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:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system

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


update_alert_dispositions_bulk

Set the same disposition on many alerts in one call, all sharing one batch_id for later undo. Requires the alerts:bulk_write scope — a client granted only alerts:write cannot call this. Calling it twice with the same batch_id is safe: the second call returns what was already applied instead of writing again.

Parameters:

NameTypeRequiredDescription
alert_idsarray of stringsYesThe alert IDs from your system, up to 50 per call
dispositionstringYesOne of: ESCALATED, CLEARED
batch_idstringNoYour own idempotency key for this batch; generated for you if omitted

Example prompt: "Clear these 12 alerts: TXN-001, TXN-002, ..."


undo_dispositions_bulk

Revert every disposition change written by one update_alert_dispositions_bulk call. Only works if the batch was written by you within the last 60 minutes (wider than the single-alert undo window, since noticing a mistake across many alerts takes longer).

Parameters:

NameTypeRequiredDescription
batch_idstringYesThe batch_id returned by update_alert_dispositions_bulk

Example prompt: "Undo that last bulk clear, batch bulk_a1b2c3d4"


submit_alert_feedback

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

Parameters:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system
block_idstringYesAnalysis block ID (from get_alert response)
flag_idstringYesFlag ID within the block
colorstringYesYour assessed color: red, yellow, green, white, gray, or black
contextstringNoFree-text explanation (max 4096 chars)

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:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system
entitieslistYesList of entity objects, up to 20 per call (see below)

Each entity object:

FieldTypeRequiredDescription
entity_source_idstringYesThe entity ID from your system
namestringNoFull legal name
dobstringNoDate of birth
emailstringNoEmail address
phonestringNoPhone number

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:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system
analyst_feedbackstringYesYour free-text guidance or new fact for the rerun (max 4000 chars)

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

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system
reasonstringNoWhy the rerun is needed (max 2048 chars)
modules_to_rerunlist of stringsNoSpecific analysis blocks to re-run (for corrections). Omit when adding new facts.

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


get_rerun_status

Check whether a rerun you started with rerun_investigation has finished. An investigation typically takes around 15 minutes; a run still queued hasn't started at all and may be waiting behind a large batch, so it can take considerably longer. Call this once and check back at the suggested time rather than polling — repeatedly re-fetching the alert will not show progress any sooner.

Parameters:

NameTypeRequiredDescription
investigation_idstringYesThe investigation ID returned by rerun_investigation

Response fields:

FieldDescription
statequeued, running, completed, incomplete, stalled (has run far longer than any normal run and is not expected to finish), or unknown (the run's status couldn't be interpreted — treat it as not finished, and contact the Axle team if it persists)
processing_statusThe raw underlying status, for reference
age_secondsHow long the run has been going
check_back_after_secondsHow long to wait before checking again; 0 once the run is done or stalled
completed_atWhen the run finished, if it has

Example prompt: "Check whether the rerun on investigation inv_8f2a1c has finished yet"


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:

ClassificationWhen to use
reviewed_correctRose's output is correct; you've verified it
correct_incompleteCorrect but missing something important
factually_incorrectRose got a fact wrong
context_neededThe block needs more context to assess
needs_more_contextSimilar to above

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:

NameTypeRequiredDescription
alert_idstringYesThe alert ID from your system
block_typestringYesBlock name from get_alert's analysis_blocks, or "general" for added_facts notes that apply broadly
bodystringYesNote content (max 4096 chars)
classificationstringYesOne of: reviewed_correct, correct_incomplete, factually_incorrect, context_needed, needs_more_context, added_facts

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"


propose_bulk_facts_rerun

Preview attaching a fact to many alerts and rerunning each one — the bulk equivalent of add_block_note + rerun_investigation, for when you have a worklist (for example, a spreadsheet export) pairing many alerts with a fact for each. This step is read-only: it resolves your alert identifiers, checks which ones are usable, and returns a proposal for you to review. Nothing is written and nothing is queued until you confirm it with confirm_bulk_facts_rerun.

Requires the separate alerts:bulk_rerun scope — a connection granted only alerts:write or alerts:bulk_write cannot use this tool. This tool must also be enabled for your organization; ask your Axle contact if it isn't yet.

Each item is one alert and one fact — if a row in your worklist names two alerts, send it as two items, each with its own copy of that fact. Several items may name the same alert; each becomes its own note and the alert is rerun once.

Limits:

  • Up to 500 items per proposal, and those items may resolve to at most 100 distinct alerts. The alert limit counts the alerts that would actually be rerun, not the rows in your worklist, so a 300-row export covering 40 alerts is fine.
  • Each fact can be up to 12,000 characters.
  • Each analyst can queue up to 300 alert reruns in any rolling 24-hour period. This is checked when you confirm.
  • A proposal can be confirmed for 10 minutes. After that, propose again.

Parameters:

NameTypeRequiredDescription
itemslistYesOne entry per fact — see below
modules_to_rerunlist of stringsNoAnalysis blocks to re-compute on every alert, leaving the rest copied forward. Omit for a full rerun on each.

Each item:

FieldTypeRequiredDescription
alert_idstringYesThe alert this fact belongs to — your own alert ID, an Axle alert ID, or a full Axle alert URL
bodystringYesThe fact to attach to this alert, in your own words

Response fields:

FieldDescription
proposal_idPass this, and only this, to confirm_bulk_facts_rerun
expires_in_secondsHow long the proposal stays valid before you must propose again
countHow many alerts would be rerun
alert_idsThe alerts that would be rerun
not_found, already_running, no_investigation, ambiguousAlerts excluded from the proposal, and why (see below)

An alert can be excluded from the proposal for a few reasons: it didn't match an alert in your organization (not_found), it already has a run in progress (already_running), it has never been investigated so there's nothing to rerun (no_investigation), or the identifier you gave matches more than one alert (ambiguous — send that alert as its own item instead).

Example prompt: "Here's a list of 40 alerts with a note for each — propose attaching these facts and rerunning them"


confirm_bulk_facts_rerun

Apply a proposal from propose_bulk_facts_rerun: write the note on every alert, then queue every rerun. Takes only the proposal_id — the alerts and their facts come from what was resolved when the proposal was made, so they cannot be changed here. Only call this after you've reviewed the proposal and approved it.

This is irreversible — there is no undo for a dispatched rerun. Confirming the same proposal twice is safe: the second call returns the batch that was already dispatched instead of rerunning everything again. If the batch would take you past the daily limit of 300 alert reruns per analyst, the confirmation is refused and nothing is written.

Parameters:

NameTypeRequiredDescription
proposal_idstringYesThe proposal_id returned by propose_bulk_facts_rerun

Response fields:

FieldDescription
batch_idPass this to get_bulk_rerun_status to follow progress
dispatchedAlert ID → the ID of its new investigation
notes_writtenHow many notes were saved
not_found, failedAlerts that couldn't be resolved or failed to dispatch, with a reason
typical_wait_secondsRoughly how long before results are worth checking, for the whole batch

Example prompt: "Yes, go ahead and confirm that bulk rerun"


get_bulk_rerun_status

Report how far a confirmed bulk-facts rerun has got, in one call — pass the batch_id that confirm_bulk_facts_rerun returned. Use this instead of checking each alert individually with get_rerun_status; at batch size, that's the polling loop this tool exists to replace.

Parameters:

NameTypeRequiredDescription
batch_idstringYesThe batch_id returned by confirm_bulk_facts_rerun

Response fields:

FieldDescription
staterunning, completed, failed (finished and no alert completed — notes were still saved), stalled, or unknown
total, completed, still_running, incompletePer-outcome counts across the batch
by_statePer-investigation state breakdown
age_secondsHow long the batch has been running
check_back_after_secondsHow long to wait before checking again; 0 once every run in the batch is done
resultsOne row per alert the batch dispatched — see below
deltaWhat changed across the whole batch, compared to each alert's prior investigation — present only once the batch is finished (completed or failed); see below

results rows report what each alert actually came back as. This is the only tool that reports a re-run's own outcome; the per-alert tools report your analyst's earlier decision instead.

FieldDescription
alert_idThe identifier you gave when the re-run was proposed
axle_idThe alert's Axle id
batch_idThe batch this alert belongs to — present on every row, since one conversation can confirm more than one batch
final_dispositionWhat this re-run decided: ESCALATED or CLEARED. Null while the run is still going, or if it never completed
final_risk_scoreThe risk score this re-run produced
disposition_at_dispatchYour analyst's disposition immediately before this re-run started — not the previous run's outcome. A change from this to final_disposition is the run disagreeing with your analyst
statecompleted, running, queued, incomplete, stalled or unknown, for this alert

Every dispatched alert gets a row even when the batch failed before any run started, in which case the outcome fields are null. An alert with null outcomes was run and produced nothing — it was not left out of the batch.

delta answers "what changed" for the whole batch, once it has finished, without you having to compare each alert's investigations one by one with compare_investigations.

FieldDescription
alerts_comparedHow many alerts this delta covers
alerts_not_comparedAlerts skipped, and why — no run started, or this was the alert's first investigation with nothing to compare against
modules_identicalHow many module results, across the whole batch, came back unchanged or were carried forward from the prior investigation
flags_changedHow many individual flags changed color, across the whole batch
module_deltasPer analysis area: how many alerts it changed on, the average score movement, and how many flags it flipped
disposition_changesOne row per alert whose outcome (ESCALATED/CLEARED) moved, with the prior outcome, the new outcome, your analyst's disposition, and whether the new outcome moved toward or away from your analyst's call
agreement_with_analystHow many of the compared alerts agreed with your analyst's disposition before this rerun, and how many agree after it

Example prompt: "What's the status of bulk rerun batch bulk_run_9f3c2a?" or, once it's finished, "What changed across that whole batch?"


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:

NameTypeRequiredDescription
titlestringYesA short title your assistant composes from the conversation (you don't write it)
descriptionstringYesA description your assistant composes from the conversation (you don't write it)
alert_idstringNoThe alert ID from your system this relates to — attaches alert context. Omit for general requests.
report_areastringNoThe specific risk flag or report section the feedback is about, named as you see it in Axle (e.g. a flag name or a report section). Helps the Axle team locate what you mean. Omit for general requests.

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"

  • If your tool registered with a client secret it renews tokens in the background, so persistent errors mean the connection itself needs removing and re-adding
  • If it registered without one, its access token lasts an hour and there is no background renewal — re-authorizing through the browser is the normal fix, not a sign of a problem. See Token Lifecycle
  • Thirty days after your first authorization, every connection must be re-authorized in the browser regardless of type

"Insufficient scope" when dispositioning many alerts at once

  • The bulk disposition tools need the alerts:bulk_write permission, which is deliberately separate from alerts:write — a tool granted only the latter cannot call them
  • Your assistant lists every tool the Axle server offers regardless of what you granted, so this limit only shows up when the tool is actually used, not when you browse the tool list
  • To fix it, remove and re-add the connection and check that "Update or undo alert dispositions in bulk" appears on the consent screen before you click Allow

"Insufficient scope" when running propose_bulk_facts_rerun or confirm_bulk_facts_rerun

  • These tools need the alerts:bulk_rerun permission — separate from both alerts:write and alerts:bulk_write, so a connection granted only disposition permissions cannot call them
  • The bulk-facts-rerun tools may also not be turned on for your organization yet; ask your Axle contact
  • To fix a missing scope, remove and re-add the connection and check that "Attach facts to many alerts and re-run their investigations (cannot be undone)" appears on the consent screen before you click Allow

"Too many alerts for one bulk re-run" or "This would exceed the daily re-run limit"

  • A single bulk-facts proposal can rerun at most 100 distinct alerts. Split the worklist into smaller batches.
  • Each analyst can queue at most 300 alert reruns in any rolling 24-hour period. Wait for older reruns to fall outside that window, then confirm the rest.
  • If a proposal has expired (after 10 minutes), ask your assistant to propose it again before confirming.

"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.)
  • get_entity_alerts is the exception: it accepts the entity ID from your own system directly (it falls back to the Axle axle_id only if your ID doesn't resolve). If it still comes back empty, double-check the ID against a recent alert rather than assuming it needs the axle_id form.

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, that authorization carries across their subsequent chats — see Token Lifecycle for how long it lasts

Did this page help you?