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
| Detail | Value |
|---|---|
| MCP Server URL | https://public.api.axleruns.com/mcp/v1/mcp |
| OAuth Discovery | https://public.api.axleruns.com/.well-known/oauth-authorization-server |
| Transport | Streamable HTTP |
| Authentication | OAuth 2.1 with PKCE (S256) |
| Client Registration | Dynamic (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:
| Tool | Description |
|---|---|
| search_alerts | List alerts with filters (disposition, risk score range, date range, alert ID) |
| get_alert | Fetch a single alert with its full analysis narrative, flags, and risk score |
| update_alert_disposition | Set an alert's disposition to NOT_REVIEWED, ESCALATED, or CLEARED |
| submit_alert_feedback | Record feedback on a specific flag (color + optional context) |
| upload_supplemental_entity_data | Attach identifying information (name, DOB, email, etc.) to entities on an alert |
| rerun_investigation | Trigger a fresh Rose investigation for an alert |
| add_block_note | Add an analyst note to a specific analysis block |
Setup by Tool
Claude Desktop
- Open Claude Desktop and go to Settings > Connectors
- Click Add Connector
- Enter the server URL:
https://public.api.axleruns.com/mcp/v1/mcp - Click Add
- 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
- Go to Settings > Apps & Connectors > Advanced settings
- Toggle Developer Mode to ON
- Click Add new connector
- Enter a name (e.g., "Axle") and the URL:
https://public.api.axleruns.com/mcp/v1/mcp - Set Authentication to OAuth
- Check "I trust this application" and click Create
- Complete the browser login flow
Available on ChatGPT Pro, Plus, Business, Enterprise, and Education plans (web only).
Open WebUI
- Go to Admin Settings > External Tools
- Click + to add a server
- Set Type to MCP (Streamable HTTP)
- Enter the URL:
https://public.api.axleruns.com/mcp/v1/mcp - Set Auth to OAuth 2.1
- Click Register Client, then Save
- Complete the browser login flow
Important: Set a persistent WEBUI_SECRET_KEY environment variable so OAuth tokens survive container restarts.
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:
- Point the application at
https://public.api.axleruns.com/mcp/v1/mcp - The application discovers OAuth metadata from
/.well-known/oauth-authorization-server - It registers a client via
POST /oauth/register(Dynamic Client Registration) - You log in through your browser and grant consent
- 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:
- Client Registration — Your AI tool automatically registers itself with Axle's OAuth server. No API keys or pre-shared secrets needed.
- Browser Login — You log in with your existing Axle account credentials (the same ones you use for the Axle dashboard).
- Consent — You review what the tool is requesting and click Allow.
- 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:
| Scope | Grants |
|---|---|
alerts:read | Search and view alerts in your organization |
alerts:write | Update dispositions, upload entity data, rerun investigations |
feedback:write | Submit flag feedback and analyst notes |
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)
- 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:
| Name | Type | Required | Description |
|---|---|---|---|
disposition | string | No | Filter by disposition: NOT_REVIEWED, ESCALATED, or CLEARED |
min_risk_score | float | No | Minimum risk score (0.0 to 1.0) |
max_risk_score | float | No | Maximum risk score (0.0 to 1.0) |
created_after | string | No | ISO 8601 datetime — only alerts created after this date |
created_before | string | No | ISO 8601 datetime — only alerts created before this date |
source_id | string | No | Filter by alert ID |
page | int | No | Page number (default: 1) |
page_size | int | No | Results per page, 1–50 (default: 10) |
Example prompt: "Show me all unreviewed alerts with a risk score above 0.7 from the last week"
get_alert
Fetch a single alert with its full analysis, including the investigation narrative, risk flags, and analysis blocks.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | The alert ID from your system |
Example prompt: "Get the details for alert TXN-2024-001"
update_alert_disposition
Update the disposition on an alert's investigation.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | The alert ID from your system |
disposition | string | Yes | One of: NOT_REVIEWED, ESCALATED, CLEARED |
Example prompt: "Escalate alert TXN-2024-001"
submit_alert_feedback
Record feedback on a specific risk flag within an alert's investigation.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | The alert ID from your system |
block_id | string | Yes | Analysis block ID (from get_alert response) |
flag_id | string | Yes | Flag ID within the block |
color | string | Yes | Your assessed color: red, yellow, green, white, gray, or black |
context | string | No | Free-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:
| Name | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | The alert ID from your system |
entities | list | Yes | List of entity objects (see below) |
Each entity object:
| Field | Type | Required | Description |
|---|---|---|---|
entity_source_id | string | Yes | The entity ID from your system |
name | string | No | Full legal name |
dob | string | No | Date of birth |
email | string | No | Email address |
phone | string | No | Phone number |
country_of_birth | string | No | Country of birth |
city_of_birth | string | No | City of birth |
tax_residency | string | No | Tax residency country |
controller | string | No | Controlling entity |
rerun_investigation
Trigger a fresh Rose investigation for an alert.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | The alert ID from your system |
reason | string | No | Why the rerun is needed (max 2048 chars) |
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:
| Name | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | The alert ID from your system |
block_type | string | Yes | Block type (use values from get_alert response's analysis_blocks) |
body | string | Yes | Note content (max 4096 chars) |
classification | string | Yes | One of: reviewed_correct, correct_incomplete, factually_incorrect, context_needed, needs_more_context |
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-serverin 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_idparameter 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
Support
For integration questions, contact your Axle account team or reach out at [email protected].
Updated about 21 hours ago