Using Barfinex with MCP (AI tools)

What is Provider MCP?

Provider MCP is an MCP (Model Context Protocol) server that exposes the Barfinex Provider REST API as tools for AI clients (e.g. Cursor, Claude, other MCP-enabled assistants). The AI can work with your Provider—accounts, orders, candles, detectors, replay, and more—through structured tool calls instead of ad-hoc HTTP prompts.

• Source of truth — Provider OpenAPI (GET /docs-json) drives which MCP tools are available. New Provider endpoints can appear as tools without manual coding.
• Transport — stdio (process-spawned MCP server).

Tool model

Static tools (always available)

• provider_health — Check Provider via GET /api/options
• provider_openapi — Fetch current OpenAPI document
• provider_refresh_openapi_tools — Refetch OpenAPI and rebuild dynamic tools
• provider_request — Generic HTTP fallback tool

Dynamic tools (Swagger-driven)

After startup (or after refresh), the MCP server registers one tool per OpenAPI operation:

• Name: provider_<operationId> (or derived from method + path if no operationId)
• Methods: GET, POST, PUT, PATCH, DELETE
• Inputs: pathParams, query, body, headers, bearerToken

So you get tools like provider_getAccounts, provider_getCandles, etc., matching your Provider API.

Run modes

• MCP only — Start just the MCP server (e.g. npm run start:mcp:provider:dev in the trading.apps repo).
• Provider + MCP — Start both Provider and MCP (recommended for development).
• Full stack (Provider + Detector + MCP) — For AI-oriented development with detector available.

Exact commands depend on your Barfinex/trading.apps setup; check the repository scripts (e.g. start:provider:dev, start:ai-stack:dev).

Environment variables

• PROVIDER_API_URL — Provider API base (e.g. http://localhost:8080/api or http://localhost:8081/api).
• PROVIDER_BEARER_TOKEN — Token for authenticated Provider API (should match Provider apiToken).
• PROVIDER_MCP_TIMEOUT_MS — Request timeout (default 15000).
• PROVIDER_MCP_INSECURE_TLS — Set to true for local self-signed HTTPS if needed.

Authentication

Provider API routes under /api/* are protected by API token. Send the token in MCP calls via the bearerToken input for each tool, or set PROVIDER_BEARER_TOKEN in the MCP process environment so all calls use it.

MCP client configuration (example)

For a Cursor-compatible stdio MCP client, configure the server something like this (paths and script names depend on your repo):

{
  "mcpServers": {
    "barfinex-provider": {
      "command": "npm",
      "args": ["run", "start:mcp:provider:dev"],
      "cwd": "/path/to/trading.apps",
      "env": {
        "PROVIDER_API_URL": "http://localhost:8081/api",
        "PROVIDER_BEARER_TOKEN": "your_token_if_required"
      }
    }
  }
}

Limitations

• Only REST operations from Swagger are exposed; WebSocket events are not MCP tools.
• Methods like HEAD, OPTIONS may not be auto-registered.
• If the Provider is unavailable at startup, only static tools are available until you run provider_refresh_openapi_tools after the Provider is up.

Troubleshooting

• Connection refused on startup — Start the Provider first, then run provider_refresh_openapi_tools.
• Only static tools visible — OpenAPI preload failed; run the refresh tool manually once the Provider is reachable.
• HTTPS certificate errors (local) — Set PROVIDER_MCP_INSECURE_TLS=true for local dev.

For the full Provider API, see Provider API reference. For Barfinex architecture, see Barfinex architecture.