Skip to content

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.

EnvironmentConnection nameMCP server URL
Sandboxcryptoswift-sandboxhttps://mcp-dev.cryptoswift.eu/
Productioncryptoswifthttps://mcp.cryptoswift.eu/
  1. Add a custom MCP server in your client using the name and URL above. Choose Streamable HTTP and OAuth if asked.
  2. Sign in to the matching Dashboard, complete any required MFA, and review the organization and requested permissions.
  3. 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

ClientWhere to add CryptoSwift
ChatGPTOpen 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 CodeRun 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 needExample 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 doesMCP toolsOAuth scopes
Identify wallet type, attribution, and available risk, or assess an intended transferclassify_wallet, assess_transferwallets:read
Find a virtual asset service provider (VASP)search_vaspsvasps:read
Search, review, and investigate Travel Rule transactionslist_transactions, get_transaction, investigate_transactiontransactions:read
Find transactions needing attention and summarize a periodlist_attention_transactions, get_compliance_reporttransactions:read
Read available originator and beneficiary details for a specific transactionget_transaction_party_detailstransactions:read and transactions:pii
Prepare and submit outgoing Travel Rule messagesprepare_travel_rule, submit_travel_ruletransactions:read to prepare, transactions:write to submit
List verification requests, review a request, and find supported verification methodslist_wallet_verifications, get_wallet_verification, get_wallet_verification_methodsverifications:read
Create a self-hosted wallet verification request and get its hosted linkcreate_wallet_verificationverifications: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 hostedUrl with the intended customer, including its query parameters. If the request was created without a link, use its resourceId to find it in the Dashboard.
  • Write retries. Save one idempotencyKey per intended write. If a write times out, loses its connection, or returns RECONCILIATION_REQUIRED, check the outcome by retrying the same request with the same key. With idempotencyScope: "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).

DiscoverySandboxProduction
OAuth resource valuehttps://mcp-dev.cryptoswift.euhttps://mcp.cryptoswift.eu
MCP protected resourceMCP metadataMCP metadata
OAuth authorization serverOAuth metadataOAuth 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 use tools/list to 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-After on HTTP responses or retryAfterSeconds on 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.