Installation Guide
Datafuse is a plain HTTPS API. You can call it with curl, requests or fetch, connect any MCP client to it, or use the typed SDKs below. The SDKs are optional wrappers: every guide on this site also works without them.
Prerequisites
- A Datafuse account at app.datafuse.xyz.
- At least one integration connected on the Integrations page, showing credentials verified. Tool schemas and tool calls are only available on a verified connection.
- Python 3.8 or newer, or Node.js 18 or newer.
Python SDK
pip install datafuse-sdk
Check that it imports:
python -c "import datafuse; print('Python SDK successfully installed!')"
See the Python client guide for usage.
TypeScript SDK
npm install @datafuse/sdk
yarn add @datafuse/sdk and pnpm add @datafuse/sdk work the same way. The package ships compiled JavaScript with type declarations and has no runtime dependencies.
Check that it resolves:
node -e "const { Datafuse } = require('@datafuse/sdk'); console.log('TypeScript SDK successfully installed!');"
See the TypeScript client guide for usage.
Credentials
Datafuse uses two credentials. Which one you need depends on the route.
| Credential | Where it comes from | Lifetime | Send it as |
|---|---|---|---|
API key (df_live_...) | Settings > API keys in the dashboard. Shown once, when created. | Until you delete it | x-api-key: df_live_... |
| Access token (JWT) | POST /api/v1/auth/login with your email and password | 30 minutes | Authorization: Bearer <token> |
| Routes | API key | Access token |
|---|---|---|
Run tools: resolve-tools, tools, tools/schema, invoke | Yes | Yes |
MCP endpoint: /mcp, /mcp/{integration_id} | Yes | Yes |
/api/v1/connected_accounts | Yes (x-api-key header only) | No |
Manage integrations: list, create, get, delete, test | No | Yes |
Account routes: /api/v1/api-keys, /api/v1/audit/logs, billing | No | Yes |
Browse the catalog: /api/v1/providers | Not needed | Not needed |
In practice: an agent that only runs tools needs an API key and nothing else. Setting up or inspecting integrations needs an access token.
On the tool-running routes and /mcp, an API key is also accepted as Authorization: Bearer df_live_....
Get an access token
curl -sS -X POST "https://api.datafuse.xyz/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "your_password"}'
The response contains access_token and refresh_token. When the access token expires, exchange the refresh token for a new pair:
curl -sS -X POST "https://api.datafuse.xyz/api/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{"refresh_token": "your_refresh_token"}'
Environment variables
The guides on this site read these variables. The SDKs do not read them automatically: pass the values to the client yourself.
# API key from Settings > API keys. Runs tools and authenticates MCP clients.
DATAFUSE_API_KEY=df_live_your_key
# Access token from /api/v1/auth/login. Manages integrations. Expires after 30 minutes.
DF_TOKEN=your_access_token
# API host. Change this only for a self-hosted deployment.
DATAFUSE_API_URL=https://api.datafuse.xyz
Keep both credentials out of source control and out of model prompts.
Next Steps
- Follow the 5-Minute Quickstart to resolve tools and invoke one.
- Prefer the terminal? Use the curl quickstart.
- Using an agent framework or IDE? Connect any MCP client with only an API key.