XentFi MCP Server

An open-source Model Context Protocol (MCP) server for the XentFi API — Bitcoin and stablecoin payment infrastructure (deposit addresses, master wallets, transfers, asset recovery, transaction/message signing, AML screening, payment links, and webhooks).

It exposes all 61 operations from the official XentFi OpenAPI specification as MCP tools, so any MCP-compatible client (Claude, Claude Code, Claude Desktop, or any other MCP host) can call the XentFi API directly on your behalf.

This project is generated from the spec, not hand-maintained: openapi/xentfi.openapi.json is the single source of truth, and npm run generate regenerates every tool definition from it. This keeps tool names, input schemas, and descriptions in sync with the official API reference instead of drifting over time. See Architecture below.

---

⚠️ Before you start: this server can move real funds

Several tools in this server call XentFi endpoints that are irreversible on-chain actions: transferring assets, recovering assets from a wallet, and signing transactions/messages/typed data. There is no "undo" for a blockchain transaction.

• Start with XENTFI_READ_ONLY=true (see Configuration) while you evaluate the server. This registers only the 28 read-only (GET) tools and completely omits transfer, recovery, and signing tools.
• Only point the server at a sandbox/testnet XentFi environment until you're confident in your client's behavior.
• Review Safety & read-only mode before connecting this to an agent that can act autonomously.
• The whitelist_deposit_address tool has an optional privatekey field defined by the API. Avoid ever putting a real private key in front of an LLM if you can avoid it — see the inline warning on that tool.

---

Quick start

1. Install

git clone https://github.com/xentfi/xentfi-mcp-server.git
cd xentfi-mcp-server
npm install
npm run build

2. Configure credentials

Copy .env.example to .env and fill in your XentFi API credentials (found in your XentFi dashboard), or set the equivalent environment variables directly in your MCP client config (see below).

Variable	Required	Description
XENTFI_API_KEY	Yes	Sent as the apiKey header on every request.
XENTFI_ORG_ID	Yes	Sent as the orgId header on every request.
XENTFI_API_BASE_URL	No	XentFi API base URL. Defaults to https://api.xentfi.com
XENTFI_TIMEOUT_MS	No	Request timeout in ms. Default 30000.
XENTFI_READ_ONLY	No	true to register only GET tools. Default false.
XENTFI_DEBUG	No	true for verbose stderr request/response logging (secrets are redacted). Default false.

3. Connect it to an MCP client

Claude Desktop / Claude Code — add to your MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "xentfi": {
      "command": "node",
      "args": ["/absolute/path/to/xentfi-mcp-server/dist/index.js"],
      "env": {
        "XENTFI_API_KEY": "your-api-key",
        "XENTFI_ORG_ID": "your-org-id",
        "XENTFI_API_BASE_URL": "https://api.xentfi.com",
        "XENTFI_READ_ONLY": "true"
      }
    }
  }
}

A ready-to-copy version of this lives in examples/claude_desktop_config.json.

Any other MCP client: point it at node dist/index.js with the same environment variables — the server speaks standard MCP over stdio.

4. Verify it's working

npx @modelcontextprotocol/inspector node dist/index.js

This opens the official MCP Inspector so you can browse and manually test every tool before wiring up a real client.

---

Architecture

openapi/xentfi.openapi.json   <- source of truth: the official XentFi API spec
        │
        ▼  npm run generate  (scripts/generate-tools.cjs)
src/tools/*.ts                 <- generated declarative ToolDefinition[] per resource
        │
        ▼
src/toolEngine.ts              <- generic engine: ToolDefinition -> live MCP tool
        │
        ▼
src/server.ts, src/client.ts   <- MCP server wiring + XentFi HTTP client
        │
        ▼
src/index.ts                   <- stdio entrypoint

• openapi/xentfi.openapi.json — the canonical XentFi OpenAPI 3 spec. Replace this file with an updated spec whenever the XentFi API changes.
• scripts/generate-tools.cjs — reads the spec and writes one src/tools/<resource>.ts file per resource group (Addresses, Master Wallets, Signing, Payment Links, Assets, AML, Webhooks), each exporting a ToolDefinition[]. Also writes src/tools/index.ts, which aggregates everything into allTools.
• src/toolEngine.ts — a single generic function (registerTools) turns every ToolDefinition into a live server.registerTool(...) call: building the request from path/query/body params, calling the XentFi API, and mapping the response (or error) into MCP tool content. There is exactly one code path for all 61 tools — no per-endpoint handler code to maintain.
• src/client.ts — a small dependency-free fetch-based HTTP client that adds the apiKey/orgId auth headers, handles timeouts, and normalizes errors into XentfiApiError.

Because tool generation is a build step, the generated src/tools/*.ts files are committed to the repo — you get readable, reviewable TypeScript in pull requests, while still getting spec-driven regeneration whenever openapi/xentfi.openapi.json changes.

Regenerating after a spec update

# replace openapi/xentfi.openapi.json with the new spec, then:
npm run generate   # rewrites src/tools/*.ts
npm run typecheck   # confirm nothing broke
npm run build

---

Safety & read-only mode

Every tool is annotated per the MCP tool annotations spec (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so MCP clients that respect these hints can prompt for confirmation appropriately. In addition:

• Setting XENTFI_READ_ONLY=true prevents any non-GET tool from being registered at all — the model literally cannot call create_master_transfer, recover_assets_from_address, sign_master_transaction, etc., because they don't exist in the tool list.
• Tools under .../transfer/..., .../recover, and .../signing/... are marked destructiveHint: true regardless of read-only mode, since they represent irreversible on-chain actions.
• The server's MCP instructions field tells the connecting model to confirm details with the user before calling fund-moving or signing tools, and to prefer read-only tools to gather context first. (This is guidance to the model, not an enforcement mechanism — XENTFI_READ_ONLY is the actual enforcement mechanism.)
• All logging goes to stderr only. The stdio MCP transport uses stdout exclusively for the JSON-RPC protocol stream; nothing else may write there.

---

Tool reference

All 61 XentFi API operations are available as tools, grouped by resource. Descriptions below are summaries — each tool's full MCP description (visible to the connecting model) includes the complete OpenAPI description, HTTP method/path, and tags.

Note on spec quirk: the official spec's summary fields for POST /v1/addresses/{addressId}/transfer/execute ("Create address transfer quote") and POST /v1/addresses/{addressId}/transfer/estimate-gas ("Execute address transfer quote") appear to be swapped relative to their path names. This server mirrors the spec exactly rather than silently reinterpreting it — verify behavior against your XentFi environment before relying on either tool, and consider filing this with the XentFi API team.

Addresses

Tool name	Method	Path	Description
list_deposit_addresses	GET	/v1/addresses	List deposit addresses
create_depositeaddress	POST	/v1/addresses	Create deposit address
whitelist_deposit_address	POST	/v1/addresses/whitelist	Whitelist an existing deposit address
get_deposit_address	GET	/v1/addresses/{addressId}	Get single deposit address
enable_address_monitoring	POST	/v1/addresses/{addressId}/monitoring/{blockchainId}/enable	Enable address monitoring
disable_address_monitoring	POST	/v1/addresses/{addressId}/monitoring/{blockchainId}/disable	Disable address monitoring
list_address_transfers	GET	/v1/addresses/{addressId}/transfers	List address transfers
get_address_token_balance	GET	/v1/addresses/{addressId}/balance	Get address token balance
list_address_settlement_rules	GET	/v1/addresses/{addressId}/settlement-rules	List address settlement rules
create_address_settlement_rule	POST	/v1/addresses/{addressId}/settlement-rules	Create address settlement rule
get_address_settlement_rule	GET	/v1/addresses/settlement-rules/{ruleId}	Get single settlement rule
update_addres_settlement_rule	PUT	/v1/addresses/settlement-rules/{ruleId}	Update settlement rule
delete_address_settlement_rule	DELETE	/v1/addresses/settlement-rules/{ruleId}	Delete settlement rule
create_address_quote_transfer	POST	/v1/addresses/{addressId}/transfer/execute	Create address transfer quote
execute_address_quote_transfer	POST	/v1/addresses/{addressId}/transfer/estimate-gas	Execute address transfer quote
recover_assets_from_address	POST	/v1/addresses/{addressId}/recover	Recover assets from an address
get_recoverable_assets_for_address	GET	/v1/addresses/{addressId}/recoverable-assets	Get recoverable assets for an address

Master Wallets

Tool name	Method	Path	Description
list_master_wallets	GET	/v1/master-wallets	List master wallets
create_master_wallet	POST	/v1/master-wallets	Create master wallet
get_master_wallet	GET	/v1/master-wallets/{masterId}	Get single master wallet
enable_master_monitoring	POST	/v1/master-wallets/{masterId}/monitoring/{blockchainId}/enable	Enable monitoring
disable_master_monitoring	POST	/v1/master-wallets/{masterId}/monitoring/{blockchainId}/disable	Disable monitoring
list_master_wallet_transfers	GET	/v1/master-wallets/{masterId}/transactions	List master wallet transfers
get_master_token_balance	GET	/v1/master-wallets/{masterId}/balance	Get master wallet token balance
list_master_settlement_rules	GET	/v1/master-wallets/{masterId}/settlement-rules	List master settlement rules
create_master_settlement_rule	POST	/v1/master-wallets/{masterId}/settlement-rules	Create master settlement rule
get_master_settlement_rule	GET	/v1/master-wallets/settlement-rules/{ruleId}	Get single settlement rule
update_master_settlement_rule	PUT	/v1/master-wallets/settlement-rules/{ruleId}	Update settlement rule
delete_master_settlement_rule	DELETE	/v1/master-wallets/settlement-rules/{ruleId}	Delete settlement rule
create_master_transfer	POST	/v1/master-wallets/{masterId}/transfer/execute	Create and execute master transfer
estimate_master_transfer_gas	POST	/v1/master-wallets/{masterId}/transfer/estimate-gas	Estimate gas fee for master transfer
recover_assets_from_master	POST	/v1/master-wallets/{masterId}/recover	Recover assets from a master wallet
get_recoverable_assets_for_master	GET	/v1/master-wallets/{masterId}/recoverable-assets	Get recoverable assets for a master wallet

Signing

Tool name	Method	Path	Description
sign_master_transaction	POST	/v1/master-wallets/{masterId}/signing/transaction	Sign a transaction using a master wallet
sign_master_message	POST	/v1/master-wallets/{masterId}/signing/message	Sign a message using a master wallet
sign_master_typed_data	POST	/v1/master-wallets/{masterId}/signing/typed-data	Sign typed data (EIP-712) using a master wallet
sign_address_transaction	POST	/v1/addresses/{addressId}/signing/transaction	Sign a transaction using an address wallet
sign_address_message	POST	/v1/addresses/{addressId}/signing/message	Sign a message using an address wallet
sign_address_typed_data	POST	/v1/addresses/{addressId}/signing/typed-data	Sign typed data (EIP-712) using an address wallet

Payment Links

Tool name	Method	Path	Description
list_payment_links	GET	/v1/payment-links	List payment links
create_payment_link	POST	/v1/payment-links	Create payment link
get_payment_link	GET	/v1/payment-links/{id}	Get single payment link
update_payment_link	PUT	/v1/payment-links/{id}	Update payment link
list_payment_transfers	GET	/v1/payment-transfers	List payment transfers
get_payment_transfer	GET	/v1/payment-transfers/{id}	Get single payment transfer

Assets

Tool name	Method	Path	Description
list_supported_blockchains	GET	/v1/assets/blockchains	List supported blockchains
get_blockchain	GET	/v1/assets/blockchains/{id}	Get blockchain by ID or slug
list_supported_tokens	GET	/v1/assets/tokens	List supported tokens with optional filtering
get_token	GET	/v1/assets/tokens/{id}	Get token by ID or symbol
get_token_price	GET	/v1/assets/prices/tokens/{symbol}	Get token price by symbol
get_token_prices	POST	/v1/assets/prices/tokens	Get prices for multiple tokens

AML

Tool name	Method	Path	Description
check_sanctions	GET	/v1/aml/check/{address}	Check if an address is sanctioned
check_multiple_sanctions	POST	/v1/aml/check-batch	Check multiple addresses for sanctions

Webhooks

Tool name	Method	Path	Description
list_webhook_subs	GET	/v1/webhooks	List webhook subscriptions
create_webhook	POST	/v1/webhooks	Create webhook subscription
get_webhook_sub	GET	/v1/webhooks/{subscriptionId}	Get webhook subscription details
update_webhook	PUT	/v1/webhooks/{subscriptionId}	Update webhook subscription
rotate_webhook_secret	POST	/v1/webhooks/{subscriptionId}/secret/rotate	Rotate webhook secret
listt_webhook_events	GET	/v1/webhook-events	List webhook events
get_webhook_event	GET	/v1/webhook-events/{eventId}	Get webhook event details
send_test_webhook_event	POST	/v1/webhooks/{subscriptionId}/test	Send a test webhook event

---

Development

npm install
npm run generate     # regenerate src/tools/*.ts from openapi/xentfi.openapi.json
npm run typecheck     # tsc --noEmit
npm run build          # compile to dist/
npm run inspector    # launch MCP Inspector against the built server

Project layout:

openapi/xentfi.openapi.json   Canonical API spec (source of truth)
scripts/generate-tools.cjs    Codegen: spec -> src/tools/*.ts
src/
  types.ts                    ToolDefinition type
  config.ts                   Env var loading/validation
  client.ts                   XentFi HTTP client (auth, timeouts, errors)
  logger.ts                   stderr-only logger with secret redaction
  toolEngine.ts                Generic ToolDefinition -> MCP tool registration
  server.ts                   McpServer construction
  index.ts                    stdio entrypoint
  tools/*.ts                  Generated tool definitions (committed, not hand-edited)
examples/                     Sample MCP client configs

See CONTRIBUTING.md for how to propose changes.

---

License

MIT — this is an independent, community-maintained integration and is not an official XentFi release artifact unless stated otherwise by XentFi. Contributions welcome.