Agent Tools (MCP)

This page covers concepts and client integrations for @xentfi/mcp-sdk. For the tool-by-tool argument/return reference, see Tools Reference in the Agent tab.

Overview

@xentfi/mcp-sdk is XentFi’s official Model Context Protocol (MCP) server — it exposes an agent’s XentFi wallet, spend policy, and payments as 15 tools any MCP-compatible client can call directly, with no custom integration code.

npm install @xentfi/mcp-sdk

🔑 One credential

Your agent’s Agent API Key authenticates every tool call — no separate OAuth flow to build.

🛡️ Server-side guardrails

Every payment is checked against the agent’s XentFi Policy (limits, allowlists, allowed hours) before it executes — enforced by the API, not the client.

🔌 Two transports

xentfi-mcp (stdio) for local desktop clients, xentfi-mcp-http (Streamable HTTP) for remote and multi-tenant deployments.

🧩 Programmatic SDK

Import createXentfiMcpServer() or the raw XentfiClient to embed XentFi tools in your own MCP server or agent framework.

Tools call the same /v1/agent-self/* routes documented in API Reference — the SDK doesn’t add new backend behavior, it exposes that surface with agent-friendly names, descriptions, and error messages.

Client integrations

Pick your client below. Every one ultimately needs the same two pieces of information: command npx, args ["-y", "@xentfi/mcp-sdk"], and env XENTFI_AGENT_API_KEY.

Claude Desktop & Claude Code

Claude Desktop — edit (Settings → Developer → Edit Config, or directly):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

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

Fully quit and reopen the app, open a new chat, and confirm xentfi appears with 15 tools.Claude Code:

claude mcp add xentfi -- npx -y @xentfi/mcp-sdk

Set XENTFI_AGENT_API_KEY in the shell Claude Code runs in, or in the generated config’s env block. Verify with claude mcp list.Global install alternative: npm install -g @xentfi/mcp-sdk, then use "command": "xentfi-mcp" instead of npx.Troubleshooting: no server showing → check Settings → Developer → Open Logs Folder for [xentfi-mcp] lines or a Missing XENTFI_AGENT_API_KEY error. Tool errors about a missing key → the env block isn’t inside the xentfi entry.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in your repo root (project-only, useful for per-project Agent API keys):

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

Check Cursor Settings → MCP for a green/active xentfi entry. Cursor spawns one subprocess per config entry and keeps it running for the session — restart only needed after editing mcp.json.For a key that can read but never move funds unattended, restrict the Policy attached to that agent’s Agent API Key rather than relying on client-side restrictions — xentfi_create_payment is still callable by any client holding a valid key.

VS Code

Create .vscode/mcp.json:

{
    "servers": {
        "xentfi": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@xentfi/mcp-sdk"
            ],
            "env": {
                "XENTFI_AGENT_API_KEY": "${input:xentfi_agent_api_key}"
            }
        }
    },
    "inputs": [
        {
            "id": "xentfi_agent_api_key",
            "type": "promptString",
            "description": "XentFi Agent API Key",
            "password": true
        }
    ]
}

Using inputs means VS Code prompts for the key once and stores it securely instead of writing it to a file you might commit.Command Palette → MCP: List Servers to confirm xentfi is running, then use Copilot Chat’s Agent mode. Debug with MCP: Show Server Output.

ChatGPT (custom connector)

ChatGPT speaks MCP over remote Streamable HTTP, not stdio — deploy xentfi-mcp-http first (see Remote HTTP Deployment below), then:

Configure a custom Authorization: Bearer sk_agent_xxx header in ChatGPT’s connector setup.
Settings → Connectors → Advanced settings → Add custom connector: Name XentFi, MCP Server URL https://your-deployment/mcp, auth via the custom headers above.
Enable the connector via the ”+“/tools menu in a chat.

Every distinct ChatGPT user/workspace should get its own agent, Agent API Key, and Policy — the header is the credential that authorizes payments. Enable ChatGPT’s tool-use/action-review setting for this connector so xentfi_create_payment calls are surfaced for confirmation before finalizing.

ElizaOS

ElizaOS reaches MCP servers through the community MCP plugin (@elizaos/plugin-mcp or equivalent):

npm install @elizaos/plugin-mcp

{
    "name": "MyTradingAgent",
    "plugins": [
        "@elizaos/plugin-mcp"
    ],
    "settings": {
        "mcp": {
            "servers": {
                "xentfi": {
                    "type": "stdio",
                    "command": "npx",
                    "args": [
                        "-y",
                        "@xentfi/mcp-sdk"
                    ],
                    "env": {
                        "XENTFI_AGENT_API_KEY": "sk_agent_xxx"
                    }
                }
            }
        }
    }
}

Since ElizaOS agents often act with minimal human review, set tight perTransactionLimitUsd/dailyLimitUsd and an allowedRecipients allowlist on the attached Policy, make sure your action logic sets confirm: true deliberately rather than reflexively, and call xentfi_get_policy in planning before large payments.

CrewAI

CrewAI (Python) consumes MCP servers via crewai-tools’ MCPServerAdapter:

pip install crewai crewai-tools

import os
from crewai import Agent, Task, Crew
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters

xentfi_params = StdioServerParameters(
    command="npx",
    args=["-y", "@xentfi/mcp-sdk"],
    env={**os.environ, "XENTFI_AGENT_API_KEY": os.environ["XENTFI_AGENT_API_KEY"]},
)

with MCPServerAdapter(xentfi_params) as xentfi_tools:
    agent = Agent(role="Treasury Operator", tools=xentfi_tools, ...)
    crew = Crew(agents=[agent], tasks=[...])
    crew.kickoff()

For a two-step audit trail, split into a planner agent (decides what to pay, no payment tools) and an executor agent (only has xentfi_create_payment, calls it with confirm: true only after your own validation passes).Newer crewai-tools versions also support connecting MCPServerAdapter to a remote server over SSE/Streamable HTTP — point it at a shared xentfi-mcp-http deployment with an Authorization: Bearer <agent-api-key> header.

Codex CLI & OpenAI Agents SDK

Codex CLI — ~/.codex/config.toml:

[mcp_servers.xentfi]
command = "npx"
args = ["-y", "@xentfi/mcp-sdk"]
[mcp_servers.xentfi.env]
XENTFI_AGENT_API_KEY = "sk_agent_xxx"

OpenAI Agents SDK (Python):

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(params={
    "command": "npx", "args": ["-y", "@xentfi/mcp-sdk"],
    "env": {"XENTFI_AGENT_API_KEY": os.environ["XENTFI_AGENT_API_KEY"]},
}) as xentfi_server:
    agent = Agent(name="Treasury Agent", mcp_servers=[xentfi_server])
    result = await Runner.run(agent, "List my XentFi wallets and their balances.")

Both SDKs cache the tool list at connect time — restart/reconnect after rotating the Agent API Key. Combine the Agents SDK’s tool-use approval hooks with confirm: true for a human-in-the-loop checkpoint on top of server-side Policy enforcement.

Any other MCP client

All any stdio-based client needs: command npx, args ["-y", "@xentfi/mcp-sdk"], env XENTFI_AGENT_API_KEY.To test without any client at all, use the MCP Inspector:

XENTFI_AGENT_API_KEY=sk_agent_xxx npx @modelcontextprotocol/inspector npx -y @xentfi/mcp-sdk

Remote HTTP deployment

Use xentfi-mcp-http instead of the stdio server when you need a hosted, network-reachable MCP endpoint — for ChatGPT connectors, a shared team deployment, or any client that only supports remote servers. It runs stateless: every request builds a fresh MCP server + client pair bound to that request’s own credentials, then tears it down. One process safely serves many agents/organizations at once, with no session state to scale.

npm install @xentfi/mcp-sdk
npx xentfi-mcp-http
# Listening on http://localhost:8787/mcp (health check: /healthz)

Every request must carry its own credentials:

Authorization: Bearer <agent-api-key>

FROM node:20-slim
WORKDIR /app
RUN npm install @xentfi/mcp-sdk
EXPOSE 8787
CMD ["npx", "xentfi-mcp-http"]

docker build -t xentfi-mcp-http .
docker run -p 8787:8787 xentfi-mcp-http

Put this behind a TLS-terminating reverse proxy — ChatGPT requires HTTPS. Fly.io, Render, and Railway all provision HTTPS automatically.

Variable	Default	Purpose
`PORT` / `XENTFI_MCP_PORT`	`8787`	Port to listen on.
`XENTFI_MCP_PATH`	`/mcp`	Path for the MCP endpoint.

Programmatic embedding

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

app.post("/mcp", async (req, res) => {
  const apiKey = req.header("authorization")?.replace(/^Bearer\s+/i, "");
  if (!apiKey) return res.status(401).json({ error: "missing agent api key" });

  const server = createXentfiMcpServer({ apiKey });
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => { transport.close(); server.close(); });

  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

Tools Reference

Every xentfi_* tool, arguments, and return shape.

Quickstart

Get credentials and make your first call.

x402 guide

The other way an agent can transact — pay per call.

Getting Started

Wallet Management

Payment Links & Webhooks

Transfers & Auto Settlement

Security & Compliance

Trading & Liquidity

Agent Tools

Overview

🔑 One credential

🛡️ Server-side guardrails

🔌 Two transports

🧩 Programmatic SDK

Client integrations

Remote HTTP deployment

Programmatic embedding

Tools Reference

Quickstart

x402 guide

​Overview

🔑 One credential

🛡️ Server-side guardrails

🔌 Two transports

🧩 Programmatic SDK

​Client integrations

​Remote HTTP deployment

​Programmatic embedding

​Related

Tools Reference

Quickstart

x402 guide

Overview

Client integrations

Remote HTTP deployment

Programmatic embedding

Related