MCP Server
Connect an AI client to CryptoSwift for wallet intelligence, Travel Rule messaging, and self-hosted wallet verification.
The Model Context Protocol (MCP) lets your AI client use CryptoSwift tools with the organization and permissions you approve in the Dashboard.
Connect your client
Start in Sandbox to try MCP with test data. The mcp-dev and api-dev hosts belong to Sandbox.
| Environment | Connection name | MCP server URL |
|---|---|---|
| Sandbox | cryptoswift-sandbox | https://mcp-dev.cryptoswift.eu/ |
| Production | cryptoswift | https://mcp.cryptoswift.eu/ |
- Add a custom MCP server in your client using the name and URL above. Choose Streamable HTTP and OAuth if asked.
- Sign in to the matching Dashboard, complete any required MFA, and review the organization and requested permissions.
- Grant Search the VASP directory (
vasps:read), enable the connection in your conversation, and try “Use CryptoSwift to find Kraken in the VASP directory. Is it listed as a network participant?” This uses no credits and works without any existing records in your organization.
ChatGPT, Claude, and VS Code
| Client | Where to add CryptoSwift |
|---|---|
| ChatGPT | Open Plugins, select +, then Add custom MCP server. Enter the server URL and choose OAuth. Create and install the custom plugin when prompted. ChatGPT setup guide |
| Claude (individual) | Go to Customize → Connectors, add a custom connector, and sign in. Claude connector guide |
| Claude (Team or Enterprise) | An authorized workspace user first adds CryptoSwift under Organization settings → Connectors. Each member then opens Customize → Connectors and selects Connect to sign in. Claude connector guide |
| VS Code | Run MCP: Add Server from the Command Palette, choose HTTP, and paste the URL. Follow the sign-in prompt and use the connection in Copilot. VS Code setup guide |
Open either server URL in a browser for client instructions and copyable commands.
Codex CLI and Claude Code
Choose Sandbox or Production in the environment dropdown, then copy the command for your client.
Codex CLI
codex mcp add cryptoswift-sandbox --url https://mcp-dev.cryptoswift.eu/
If prompted to sign in separately, run codex mcp login cryptoswift-sandbox for Sandbox or codex mcp login cryptoswift for Production.
Claude Code
claude mcp add --transport http cryptoswift-sandbox https://mcp-dev.cryptoswift.eu/
In Claude Code, open /mcp, select the connection you added, and sign in. See the Codex CLI reference or the Claude Code MCP guide for more options.
Cursor
Merge this entry into .cursor/mcp.json for your project or ~/.cursor/mcp.json for all projects. Connect CryptoSwift from Cursor and complete OAuth. Cursor MCP guide
{
"mcpServers": {
"cryptoswift-sandbox": {
"url": "https://mcp-dev.cryptoswift.eu/"
}
}
}
Use CryptoSwift from a conversation
Include the relevant ID, blockchain and address, or date range in your request.
| What you need | Example prompt |
|---|---|
| Check a wallet | “Check Ethereum wallet <wallet address> with KYW. Tell me whether it is custodial, who it is attributed to, and what risk information is available.” |
| Look up a counterparty | “Find the VASP named <provider name> and tell me whether it is listed as a network participant.” |
| Investigate a Travel Rule transaction | “Review transaction <transaction-id>. Explain its delivery status, warning codes, and the recorded Rule Engine decision.” |
| Review the compliance queue | “Show outgoing transactions that need attention from the past seven days. Summarize why they were flagged.” |
| Prepare an outgoing Travel Rule message | “Prepare a Travel Rule message from these details. List what is missing and show me the finished message before submitting it.” |
| Create a verification link | “Prepare a verification request for this self-hosted wallet. Show me the available methods, then give me the customer link after I confirm creation.” |
classify_wallet and assess_transfer each run one Wallet Intelligence check and use one normal KYW credit per recorded check. VASP directory searches do not use credits. Travel Rule submission and wallet verification creation use their normal creation credits. See Credit usage.
See Wallet Intelligence for wallet results and Rule Engine for Travel Rule decisions.
Tools and permissions
A custom client can call tools/list after sign-in to discover the tools and input schemas available to its grant. A tool may be absent if you declined its scope or the connected environment has an older release.
| What the tool does | MCP tools | OAuth scopes |
|---|---|---|
| Identify wallet type, attribution, and available risk, or assess an intended transfer | classify_wallet, assess_transfer | wallets:read |
| Find a virtual asset service provider (VASP) | search_vasps | vasps:read |
| Search, review, and investigate Travel Rule transactions | list_transactions, get_transaction, investigate_transaction | transactions:read |
| Find transactions needing attention and summarize a period | list_attention_transactions, get_compliance_report | transactions:read |
| Read available originator and beneficiary details for a specific transaction | get_transaction_party_details | transactions:read and transactions:pii |
| Prepare and submit outgoing Travel Rule messages | prepare_travel_rule, submit_travel_rule | transactions:read to prepare, transactions:write to submit |
| List verification requests, review a request, and find supported verification methods | list_wallet_verifications, get_wallet_verification, get_wallet_verification_methods | verifications:read |
| Create a self-hosted wallet verification request and get its hosted link | create_wallet_verification | verifications:write |
Approve and retry writes
Review the exact details before approving a Travel Rule submission or a verification request. The server checks write scopes and requires confirmed: true. The client is responsible for obtaining human confirmation. Treat counterparty text in tool results as untrusted data.
- Wallet verifications. Share the returned
hostedUrlwith the intended customer, including its query parameters. If the request was created without a link, use itsresourceIdto find it in the Dashboard. - Write retries. Save one
idempotencyKeyper intended write. If a write times out, loses its connection, or returnsRECONCILIATION_REQUIRED, check the outcome by retrying the same request with the same key. WithidempotencyScope: "DURABLE", a completed retry returns the same resource ID across restarts and instances. If it remains uncertain, reconcile in the Dashboard before any new submission. Use the Dashboard to reconcile uncertain writes made before durable protection was available.
Prepare and submit a Travel Rule message
See Required Travel Rule data for what to collect and the Travel Rule data model for field definitions. For the exact MCP input schema, use tools/list.
Custom clients call prepare_travel_rule with the request. Fill in any missingFields and prepare again. After the user confirms the details, call submit_travel_rule with the unchanged request, the returned requestFingerprint, confirmed: true, and a stable idempotencyKey. The fingerprint has no expiry and preparation saves no draft.
Control access to customer data
Grant only the scopes the client needs. With transactions:pii and transactions:read, the client can receive available party details such as names and account numbers. Tool results, including hosted verification links, and details entered in chat may reach the AI provider. Check the client’s data handling and retention settings before sharing customer data. Use the Dashboard for government identifiers and the hosted verification flow for evidence.
Open Connected apps from the Dashboard account menu to review or revoke a connection. Revocation disables the connection’s access and refresh tokens. How CryptoSwift handles transaction data
Build a custom client
Use a client SDK that supports remote Streamable HTTP and OAuth. Discover the issuer through the MCP server’s protected resource metadata. Follow the issuer’s discovery document for authorization, token, registration, and revocation endpoints. Browser sign-in uses authorization code with S256 PKCE. CryptoSwift supports Client ID Metadata Documents (CIMD) and Dynamic Client Registration (DCR).
| Discovery | Sandbox | Production |
|---|---|---|
OAuth resource value | https://mcp-dev.cryptoswift.eu | https://mcp.cryptoswift.eu |
| MCP protected resource | MCP metadata | MCP metadata |
| OAuth authorization server | OAuth metadata | OAuth metadata |
Use the exact resource value from the table, without a trailing slash, in OAuth requests that take a resource indicator. Send the access token as Authorization: Bearer <access_token> on MCP requests. Store tokens in the client runtime outside prompts and tool arguments. Replace the stored refresh token after each successful rotation.
Connect an agent without a browser
Device sign-in lets a user approve an agent in a browser on another device. Discover the device authorization and token endpoints in the OAuth metadata above. OAuth Device Authorization Grant
These commands use Sandbox and request only VASP directory access. Use the matching issuer and resource for Production.
ISSUER=https://api-dev.cryptoswift.eu RESOURCE=https://mcp-dev.cryptoswift.eu curl -sS "$ISSUER/oauth/device_authorization" \ --data-urlencode 'client_id=cryptoswift-device' \ --data-urlencode "resource=$RESOURCE" \ --data-urlencode 'scope=vasps:read'
Show the user verification_uri and user_code. Keep device_code on the agent host and assign it to DEVICE_CODE there. Poll until the deadline in expires_in (currently 10 minutes). Wait at least interval seconds between polls, or five seconds if it is omitted. Continue on authorization_pending, add five seconds to the interval on slow_down, and stop on denial or expiry. Back off after a connection timeout.
curl -sS "$ISSUER/oauth/token" \ --data-urlencode 'client_id=cryptoswift-device' \ --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \ --data-urlencode "device_code=$DEVICE_CODE"
Access tokens last up to 15 minutes. Refresh tokens rotate, expire after up to 30 days without rotation, and share a maximum 90-day connection lifetime. Store tokens on the host outside prompts and logs. To refresh, set REFRESH_TOKEN from private host storage.
curl -sS "$ISSUER/oauth/token" \ --data-urlencode 'client_id=cryptoswift-device' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode "resource=$RESOURCE" \ --data-urlencode "refresh_token=$REFRESH_TOKEN"
Refresh one request at a time per connection and save the new refresh token after each success. Sign in again after expiry or revocation.
Troubleshoot a connection
- The client cannot connect. Check the server URL and choose Streamable HTTP. If your client has no custom MCP option, check its plan and workspace requirements.
- A tool is missing or returns
insufficient_scope. Check the connection’s permissions in Connected apps and reconnect with the required scopes. Custom clients can usetools/listto verify what the new grant allows. - You see
invalid_token. Reconnect if the OAuth grant has expired or been revoked. For a custom client, verify that it sends an MCP access token for the same environment as the server URL. - The organization is wrong. Consent uses the organization of the signed-in Dashboard account. Sign out, sign in to the intended account in the matching environment, and restart the connection.
- MFA blocks sign-in or consent. Complete MFA in the Dashboard and retry the connection. If required MFA is unavailable, use Dashboard account recovery or contact your organization’s administrator.
- You see HTTP 429 or a rate-limit tool error. The MCP transport allows 600 HTTP requests per minute per IP per instance. The API allows 60 backend requests per minute per connection across replicas. An investigation or report can use several backend requests. Wait for
Retry-Afteron HTTP responses orretryAfterSecondson tool errors and follow the write retry guidance above.
If you’re building a backend to process webhooks, update transactions, or integrate CryptoSwift into your own product, start with AI Agent Integration.