REST API Sources

If clariBI doesn't have a built-in connector and the vendor isn't in the MCP catalog, you can connect any HTTPS endpoint as a custom data source. Two paths: Custom MCP (preferred — read-only by protocol, OAuth 2.1 + DCR auth) for vendors with an MCP server, or REST API (legacy) for everything else.

Decision Tree — Which Path to Use

1. Vendor in the live MCP catalog? Use it directly. See MCP Integrations.
2. Vendor publishes an MCP server but isn't in the catalog yet? Use Custom MCP — point clariBI at the MCP endpoint URL. Auto-discovers OAuth metadata via the well-known endpoint and registers dynamically (DCR). The recommended path: same security guarantees as catalog vendors, no schema mapping needed.
3. Vendor has a plain REST API only? Use the REST API connector below. You point at a specific endpoint URL, paste an API key, and clariBI handles fetching + pagination.
4. Internal API serving your own business data? Either path — Custom MCP if you can stand up an MCP wrapper (small wrapper layer that exposes your endpoints with the MCP shape); REST API for one-off integrations.

Custom MCP (preferred, Starter+)

If your vendor publishes an MCP server (an increasing number do — see the public catalog at modelcontextprotocol.io), point clariBI at it directly:

1. Go to Settings → Data Sources → Connect MCP → Custom MCP.
2. Paste the MCP endpoint URL (e.g., https://api.example.com/mcp).
3. Pick auth mode: OAuth 2.1 + DCR (recommended — clariBI auto-discovers and registers), Bearer token, or custom header (paste an API key).
4. clariBI runs an SSRF guard on the URL: HTTPS only, RFC1918 / loopback / cloud-metadata addresses blocked. If the check passes, the connection is created and the catalog row appears in your Settings.

Once connected, the AI engine can call the server's read-only tools just like any catalog vendor. Available on Starter / Professional / Enterprise.

When to Use REST API Sources (legacy)

Use the REST API connector when:

• The vendor doesn't have an MCP server at all (and probably won't soon).
• You're pulling from a single specific endpoint with predictable shape (not a full vendor surface).
• You need a one-off integration that doesn't justify wrapping in MCP.

Setup

Response Format

clariBI expects the API to return JSON. The best format is an array of objects:

{
  "data": [
    {"date": "2025-01-01", "product": "Widget A", "revenue": 1500},
    {"date": "2025-01-01", "product": "Widget B", "revenue": 2300},
    ...
  ]
}

Use the response mapping field to specify the path to the array (e.g., data in the example above).

Pagination

For APIs that return paginated results, clariBI can handle pagination during data sync to retrieve the complete dataset.

Sync Schedule

API sources sync based on your tier's cache duration. You can trigger manual syncs at any time. For frequently changing data, consider using shorter cache durations (available on higher tiers).

Limitations

• Only GET requests are supported (clariBI reads data, it does not write)
• Response must be JSON format
• Maximum response size depends on your tier's storage limits
• Rate limiting on the remote API may slow down initial syncs

Related

• Data Sources Overview
• Troubleshooting
• Data Sources API (for programmatic management)