Claude MCP Server
The mcp-butterfly server gives Claude direct, audited access to your Butterfly Security identity backups. Add it as a Claude custom connector and ask in natural language to list backups, diff snapshots, score recovery readiness, or restore with confirmation.
What it does
An MCP server that lets Claude list, inspect, diff, and (with confirmation) restore your Butterfly Security identity-provider backups directly. Eleven tools, audience-bound JWT auth, runs on Cloudflare Workers. The server proxies your authenticated session to butterflysecurity.org/api/*, so every call respects the same RLS, plan limits, and audit logging as the dashboard.
Supported provider connections today: Okta, Okta Workflows, and Auth0.
Install
Claude custom connector
- Open Claude and go to Settings → Connectors → Add custom connector.
- Enter the MCP server URL:https://mcp-butterfly.<account>.workers.dev/mcp
- Complete the OAuth flow. Claude will redirect you to Butterfly to authenticate; on return, Claude stores an audience-bound bearer token for that connector.
- Start a new chat and ask Claude something from the examples below.
Anthropic Directory
We've submitted mcp-butterflyto the Anthropic Directory. Once listed, you'll be able to add Butterfly Security from inside Claude with one click — no URL copy/paste, same OAuth flow.
Tools
All eleven tools, with MCP annotations that drive host UX: read-only calls run silently, write tools surface in the transcript, and destructive tools trigger a confirmation dialog in Claude before the call goes out.
| Tool | Type | Purpose |
|---|---|---|
list_connections List Connections | read-only | List every identity-provider connection on the team, with redacted credentials and schedule state. |
list_backups List Backups | read-only | Paginated, filterable list of backups across all connections (status, date range, resource types, free-text search). |
get_backup Get Backup | read-only | Fetch full metadata for one backup by UUID: timestamps, size, resource counts, storage key, owning connection. |
get_backup_status Get Backup Status | read-only | Poll an in-flight backup's lifecycle state and progress percentage. Use after run_backup. |
get_resilience_score Get Resilience Score | read-only | Numeric resilience score out of 100 for one connection, with five weighted factors and actionable recommendations. |
diff_backups Diff Two Backups | read-only | Compare two backups of the same connection. Returns structured changes by resource type, action, and severity. |
diff_against_current Diff Backup vs. Live State | read-only | Compare the latest backup against the live identity provider. Okta connections only; Auth0 and Okta Workflows return an empty diff. |
preview_restore Preview Restore | read-only | Summarize what restoring a given backup would touch — per-resource-type counts, source org URL, collection time. No writes. |
run_backup Run Backup | write | Kick off a backup for one connection. Returns a backupId immediately; poll progress with get_backup_status. |
set_backup_schedule Set Backup Schedule | write | Update the scheduled-backup configuration for a connection: enable/disable, frequency, hour, day, timezone, incremental. |
execute_restore Execute Restore | destructive | Restore resources from a backup into the live identity provider. Supports dry-run, full, and selective modes. Host shows a confirmation dialog. |
Auth
The server supports two OAuth flows so it works both with Claude.ai (which prefers Dynamic Client Registration) and with hosts that pre-register a client.
Used by hosts that already know which MCP server they're connecting to. The MCP server publishes its own metadata and the host authenticates against Butterfly directly.
Used by Claude when you add a custom connector. The host registers itself on the fly via /oauth/register, then runs a standard authorization-code flow.
Discovery
Both flows are advertised at /.well-known/oauth-authorization-server on the MCP server, which is the standard MCP auth discovery endpoint.
Audience binding (RFC 8707)
Issued bearer tokens are audience-bound to https://butterflysecurity.org/api/. A token minted for one MCP server cannot be replayed against any other API surface, and tokens for other APIs cannot be used against Butterfly — per RFC 8707 Resource Indicators.
Example prompts
Drop these straight into Claude after adding the connector. Each one exercises a different slice of the tool surface.
“Show me the last 7 days of backups across all my connections.”
list_connectionslist_backups“Diff the latest two Okta backups for my prod org and summarize the security-relevant changes.”
list_backupsdiff_backups“Run a backup of my Okta connection right now and tell me when it finishes.”
list_connectionsrun_backupget_backup_status“What's my restore readiness score for the prod Okta connection, and what should I fix first?”
list_connectionsget_resilience_score“Preview a restore of the 'engineering' group from yesterday's Okta backup before I do anything.”
list_backupspreview_restoreLimitations & roadmap
Restore is preview-first, Okta-only today
execute_restore currently writes only to Okta connections. Auth0 restore requires two stored snapshots to diff against and is on the roadmap. preview_restore works for all supported providers.
No admin proxy actions in v0
The MCP server does not yet expose the iOS admin endpoints (suspend user, clear sessions, network-zone toggle, helpdesk actions). Those require capability-gated scopes and a biometric confirmation surface that we're designing before exposing them to a chat host.
Refresh tokens land in v2
v0 tokens are long-lived bearers bound by audience. Refresh tokens + token rotation are coming in v2 to bring the auth model in line with the latest MCP spec.
iOS companion app
The Butterfly for Okta iOS app does not yet integrate with the MCP server. iOS uses its own audit-logged proxy at /api/okta/admin/*. Bridging MCP into the iOS surface is a future consideration.
Questions, bugs, or feature requests? support@butterflysecurity.org