@xentfi/mcp-sdk

Official Model Context Protocol (MCP) server and SDK for XentFi — enterprise wallet-as-a-service, agentic payments, and treasury infrastructure powered by stablecoins.

Drop this into any MCP-compatible client — Claude Desktop, Claude Code, Cursor, VS Code, ChatGPT (custom connectors), ElizaOS, CrewAI, OpenAI Codex/Agents, or your own agent runtime — and your agent instantly gets policy-governed tools to check its wallet balance, look up token prices, and move money.

npm install @xentfi/mcp-sdk

• 🔑 One header, fully wired — pass your XentFi agent key and every tool call is authenticated automatically.

• 🛡️ Server-side guardrails — every payment is evaluated against the agent's XentFi spend Policy (per‑tx / daily / weekly / monthly limits, recipient allowlists, allowed hours) before it executes.

• 🔌 Two transports — xentfi-mcp (stdio, for local desktop clients) and xentfi-mcp-http (Streamable HTTP, for remote / multi‑tenant / ChatGPT deployments).

• 🧩 Programmatic SDK — import createXentfiMcpServer() or the raw XentfiClient to embed XentFi tools in your own MCP server or agent framework.

• 📦 Zero-config CLI — npx @xentfi/mcp-sdk just works once XENTFI_AGENT_KEY is set.

Table of contents

• Quickstart

• Getting an agent key

• Available tools

• Client integration guides

• Using the SDK programmatically

• Remote / multi-tenant HTTP deployment

• Configuration reference

• Error handling

• Security notes

• Development

• Support

Related MCP server: PayPls MCP Server

Quickstart

Every MCP client ultimately just needs to run one command with one environment variable set:

XENTFI_AGENT_KEY="sk_agent_xxx" npx -y @xentfi/mcp-sdk

That's it — this starts the stdio MCP server and exposes all XentFi tools (see below) to whatever spawned it.

Most people never run this by hand; instead you point your MCP client's config at it. Jump to your client:

Getting an agent key

1. Sign in to the XentFi dashboard (or use the XentFi API to create an agent programmatically).

2. Create (or select) an Agent — this is the identity your AI agent will act as.

3. Generate an Agent key for it, and attach a spend Policy (limits, allowlists, allowed hours) from the Policies section — this is what keeps an autonomous agent from overspending or paying the wrong address.

4. Copy the key. It's shown once — store it in a secrets manager, not in source control.

Full docs: docs.xentfi.com/authentication.

Available tools

All tools are prefixed xentfi_ so they don't collide with tools from other MCP servers.

Agent & wallets

Policy

Payments

Market data (assets)

xentfi_list_blockchains, xentfi_get_blockchain, xentfi_list_tokens, xentfi_get_token, and the price tools require an orgId in addition to the agent key (per the XentFi API's OrgIdAuth requirement on those routes). Set XENTFI_ORG_ID if you plan to use them.

Client integration guides

Each guide below has copy-pasteable config. The short version for any stdio-based client is always the same JSON shape:

{
  "mcpServers": {
    "xentfi": {
      "command": "npx",
      "args": ["-y", "@xentfi/mcp-sdk"],
      "env": {
        "XENTFI_AGENT_KEY": "sk_agent_xxx",
        "XENTFI_ORG_ID": "org_xxx"
      }
    }
  }
}

See the per-client docs for exact file locations and quirks:

• Claude Desktop / Claude Code

• Cursor

• VS Code

• ChatGPT

• ElizaOS

• CrewAI

• Codex / OpenAI Agents SDK

• Any generic MCP client

• Remote HTTP / multi-tenant deployment

Using the SDK programmatically

You don't have to use the CLI — the same tools can be mounted inside your own MCP server or Node process:

import { createXentfiMcpServer } from "@xentfi/mcp-sdk";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createXentfiMcpServer({
  agentKey: process.env.XENTFI_AGENT_KEY,
  orgId: process.env.XENTFI_ORG_ID, // optional, needed only for asset/price tools
});

await server.connect(new StdioServerTransport());

Or use the raw REST client directly (e.g. inside a CrewAI tool, a LangChain tool, or your own backend) without any MCP machinery at all:

import { XentfiClient } from "@xentfi/mcp-sdk";

const xentfi = new XentfiClient({ agentKey: process.env.XENTFI_AGENT_KEY });

const { data: agent } = await xentfi.get("/agent-self");
const { data: wallets } = await xentfi.get("/agent-self/wallets");
const { data: tx } = await xentfi.post("/agent-self/payments", {
  body: {
    agentWalletId: wallets[0].id,
    assetId: "usdc-asset-id",
    recipient: "0x...",
    amount: "25.00",
    idempotencyKey: crypto.randomUUID(),
  },
});

XentfiClient also accepts per-call credential overrides — handy for a backend serving multiple agents from one process:

await xentfi.get("/agent-self", { agentKey: perTenantAgentKey });

Remote / multi-tenant HTTP deployment

For ChatGPT custom connectors, shared team deployments, or any client that speaks MCP over HTTP instead of spawning a local process, run:

npx @xentfi/mcp-sdk-http   # alias: node node_modules/.bin/xentfi-mcp-http

This starts a stateless, multi-tenant Streamable HTTP server on POST /mcp. It does not read a fixed agent key from the environment by default — every HTTP request must carry its own agent credentials:

x-agent-key: sk_agent_xxx
x-xentfi-org-id: org_xxx        # optional

See docs/HTTP_TRANSPORT.md for deployment recipes (Docker, behind a reverse proxy, on Fly.io/Render/Railway) and the ChatGPT connector guide for wiring it into ChatGPT.

Configuration reference

XentfiClientConfig (programmatic use) additionally supports timeoutMs, defaultHeaders, and fetchImpl — see src/types.ts.

Error handling

Tool calls never throw raw exceptions back to the MCP client. Failures are returned as a structured tool result with isError: true and a JSON body like:

{
  "error": true,
  "status": 409,
  "code": "POLICY_DENIED",
  "message": "Transaction exceeds daily limit of $500.00",
  "requestId": "req_123e4567",
  "hint": "The agent's spend policy blocked this transaction ... Call xentfi_get_policy to inspect current limits and spend."
}

This is deliberate: agents reason much better over a structured, explained failure than an opaque protocol error, and it lets the agent decide to check xentfi_get_policy and retry with different parameters instead of just failing silently.

If you use XentfiClient directly (outside of tool handlers), failures raise XentfiApiError (with .status, .code, .requestId, .isAuthError, .isPolicyDenied) or XentfiConfigError for missing credentials.

Security notes

• Never hardcode XENTFI_AGENT_KEY in source control. Use your MCP client's secret/env storage, or a secrets manager in production.

• xentfi_create_payment requires an explicit confirm: true argument — this gives the calling agent (and any human-in-the-loop review layer above it) a natural point to double-check the recipient and amount before funds move. XentFi additionally enforces the agent's Policy limits server-side regardless of what the client does.

• Prefer scoping each agent to its own narrowly-permissioned agent key and Policy rather than sharing one key across many agents.

• When running the HTTP transport publicly, put it behind TLS and treat the x-agent-key header exactly like any other bearer credential (don't log it, rotate it, rate-limit the endpoint).

Development

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

# Run against the MCP Inspector for interactive debugging:
XENTFI_AGENT_KEY=sk_agent_xxx npm run inspector

Support

• Docs: docs.xentfi.com

• Email: support@xentfi.com

• Discord: discord.gg/xentfi

• Issues: github.com/xentfi/xentfi-mcp-sdk/issues

License

MIT © XentFi