# @xentfi/mcp-sdk

Official **Model Context Protocol (MCP)** server and SDK for [XentFi](https://xentfi.com) — 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](#quickstart)
- [Getting an agent key](#getting-an-agent-key)
- [Available tools](#available-tools)
- [Client integration guides](#client-integration-guides)
- [Using the SDK programmatically](#using-the-sdk-programmatically)
- [Remote / multi-tenant HTTP deployment](#remote--multi-tenant-http-deployment)
- [Configuration reference](#configuration-reference)
- [Error handling](#error-handling)
- [Security notes](#security-notes)
- [Development](#development)
- [Support](#support)

---

## Quickstart

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

```bash
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:

| Client                         | Guide                                                      |
| ------------------------------ | ---------------------------------------------------------- |
| Claude Desktop / Claude Code   | [`docs/CLAUDE_DESKTOP.md`](docs/CLAUDE_DESKTOP.md)         |
| Cursor                         | [`docs/CURSOR.md`](docs/CURSOR.md)                         |
| VS Code (Copilot / MCP)        | [`docs/VSCODE.md`](docs/VSCODE.md)                         |
| ChatGPT (custom connector)     | [`docs/CHATGPT.md`](docs/CHATGPT.md)                       |
| ElizaOS                        | [`docs/ELIZAOS.md`](docs/ELIZAOS.md)                       |
| CrewAI                         | [`docs/CREWAI.md`](docs/CREWAI.md)                         |
| OpenAI Codex / Agents SDK      | [`docs/CODEX.md`](docs/CODEX.md)                           |
| Any other MCP client           | [`docs/GENERIC_MCP_CLIENT.md`](docs/GENERIC_MCP_CLIENT.md) |
| Remote / hosted / multi-tenant | [`docs/HTTP_TRANSPORT.md`](docs/HTTP_TRANSPORT.md)         |

## Getting an agent key

1. Sign in to the [XentFi dashboard](https://dashboard.xentfi.com) (or use the [XentFi API](https://docs.xentfi.com/api-reference) 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](https://docs.xentfi.com/authentication).

## Available tools

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

### Agent & wallets

| Tool                        | Description                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------- |
| `xentfi_get_agent_info`     | Identity/status of the authenticated agent. Call first to sanity-check the agent key. |
| `xentfi_list_wallets`       | List wallets linked to this agent (paginated, filterable).                            |
| `xentfi_create_wallet`      | Generate a brand-new on-chain wallet on a given blockchain and link it.               |
| `xentfi_link_wallet`        | Link an existing child wallet (by `addressId`) to this agent.                         |
| `xentfi_get_wallet_balance` | Token balances + live USD value for one of the agent's wallets.                       |

### Policy

| Tool                | Description                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `xentfi_get_policy` | The agent's effective spend policy (limits, allowlists, hours) and current spend counters. |

### Payments

| Tool                    | Description                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `xentfi_create_payment` | Move funds to a recipient (`TRANSFER`) or settle a `CHECKOUT`. Server-side policy-checked. Requires `confirm: true`. |
| `xentfi_list_payments`  | List past/pending payments (filterable by status/date, paginated).                                                   |
| `xentfi_get_payment`    | Full detail + policy-evaluation trace for one payment.                                                               |

### Market data (assets)

| Tool                      | Description                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `xentfi_list_blockchains` | Supported blockchains (Ethereum, Base, Polygon, Arbitrum, Optimism, BNB Chain, Solana, …). |
| `xentfi_get_blockchain`   | Detail for one blockchain by ID/slug.                                                      |
| `xentfi_list_tokens`      | Supported tokens, filterable by chain/network/symbol.                                      |
| `xentfi_get_token`        | Detail for one token by ID/symbol.                                                         |
| `xentfi_get_token_price`  | Current USD price for one symbol.                                                          |
| `xentfi_get_token_prices` | Current USD prices for up to 100 symbols in one call.                                      |

> `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:

```json
{
  "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](docs/CLAUDE_DESKTOP.md)
- [Cursor](docs/CURSOR.md)
- [VS Code](docs/VSCODE.md)
- [ChatGPT](docs/CHATGPT.md)
- [ElizaOS](docs/ELIZAOS.md)
- [CrewAI](docs/CREWAI.md)
- [Codex / OpenAI Agents SDK](docs/CODEX.md)
- [Any generic MCP client](docs/GENERIC_MCP_CLIENT.md)
- [Remote HTTP / multi-tenant deployment](docs/HTTP_TRANSPORT.md)

## 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:

```ts
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:

```ts
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:

```ts
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:

```bash
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`](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

| Variable                   | Required   | Used by           | Description                                                                                     |
| -------------------------- | ---------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| `XENTFI_AGENT_KEY`         | ✅ (stdio) | `xentfi-mcp`      | Agent key, sent as the `x-agent-key` header on every request.                                   |
| `XENTFI_ORG_ID`            | optional   | `xentfi-mcp`      | Organization ID, sent as the `x-xentfi-org-id` header. Only required for the asset/price tools. |
| `XENTFI_BASE_URL`          | optional   | both              | Override the API base URL. Defaults to `https://api.xentfi.com/v1`.                             |
| `PORT` / `XENTFI_MCP_PORT` | optional   | `xentfi-mcp-http` | Port for the HTTP transport. Defaults to `8787`.                                                |
| `XENTFI_MCP_PATH`          | optional   | `xentfi-mcp-http` | HTTP path for the MCP endpoint. Defaults to `/mcp`.                                             |

`XentfiClientConfig` (programmatic use) additionally supports `timeoutMs`, `defaultHeaders`, and `fetchImpl` — see [`src/types.ts`](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:

```json
{
  "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

```bash
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](https://docs.xentfi.com)
- Email: [support@xentfi.com](mailto:support@xentfi.com)
- Discord: [discord.gg/xentfi](https://discord.gg/xentfi)
- Issues: [github.com/xentfi/xentfi-mcp-sdk/issues](https://github.com/xentfi/xentfi-mcp-sdk/issues)

## License

MIT © XentFi