How to connect Prizma BI to an AI agent with MCP

MCP lets an AI agent read data from Prizma BI over Streamable HTTP. The server applies the user’s permissions, so an agent cannot access workspaces, dashboards, or datasets unavailable to that user.

Current contract version: v1.

Before you start

You need:

• a Prizma BI account;
• access to the target workspace and published data;
• an MCP client with Streamable HTTP support;
• a Bearer token with the minimum required permissions.

Never paste the token into an agent prompt, public chat, repository, or log. Provide it only through the MCP client’s protected secret configuration.

Configure the connection

Set the MCP server URL in your client:

https://<mcp-host>/mcp

For local development, use the MCP endpoint bound to loopback on port 8090. The production address depends on the environment and must be provided by a Prizma BI administrator.

Add the authorization header:

Authorization: Bearer <token>

After connecting, list the available workspaces first. Do not run an analytics query until you have verified the user’s access scope.

Available tools

list_workspaces

Returns the workspaces and teams available to the authenticated user. It takes no arguments.

Example input:

{}

search

Searches dashboards and reports already available to the authenticated user. It searches only the caller’s authorized workspace scope; arbitrary Directus collections are never searched. Filter by object type and set limit to 50 or less.

Example input:

{"query":"revenue","types":["dashboard","report"],"limit":20}

get_dashboard

Returns a dashboard by its public identifier, dashboardId. Internal database IDs are not accepted. If a dashboard is missing or inaccessible, the server returns the same safe error.

Example input:

{"dashboardId":"sales-overview"}

list_notifications

Lists notification summaries for the authenticated user only. It is read-only and does not return notification body text, file IDs, export metadata, or internal entity IDs.

Example input:

{"limit":20}

list_alerts

Lists alerts available to the authenticated user. Results remain scoped to existing workspace authorization and are limited server-side.

Example input:

{"limit":20}

get_report

Returns one report by its public identifier, including the authorized report definition and dataset field catalog. A missing or inaccessible report returns the same safe error.

Example input:

{"reportId":"revenue-by-month"}

run_query

Runs a structured read-only query against a published dataset. The request can contain a dataset public ID, dimensions, measures, filters, orderBy, and limit.

Raw SQL, table names, and unknown fields are rejected. The server applies the user’s RLS/CLS policies and caps limit server-side.

Minimal example:

{
  "dataset": "sales",
  "dimensions": ["month"],
  "measures": ["revenue"],
  "filters": [],
  "orderBy": [],
  "limit": 100
}

The MCP client receives the exact query JSON Schema through tools/list. Do not add fields from this example if they are absent from the current schema for your server version.

download_export

Downloads your completed export using workspace and exportId from list_exports / get_export_status. File bytes are in resource.blob (base64), with the name in structuredContent.fileName. The attachment URI is not a public link. Current workspace, dataset and export access are checked; the file is read with the same user token. Download larger files through the Prizma interface.

Prefer platform analysis without exporting. Use a file only when the user asks for one or there is an explained need.

Create reports and dashboards

preview_create_report validates the current user’s workspace, team and dataset. Supply workspace and team public IDs from list_workspaces, title, description (string or null), dataset, dimensions, measures, filters, order and chartType. Use exact fresh get_dataset.members[].id root canonical member IDs, not internal UUIDs, labels or joined members. At least one measure is required. The tool saves a flat draft report with its initial revision, field selection, filter tree and ordering. It does not create folders, publish, build pivot reports or update an existing report.

preview_create_dashboard accepts only workspace, team, title and description. It creates an empty draft without widgets, not a populated dashboard.

Show the exact preview to the user. Only after explicit approval call create_report or create_dashboard with the unchanged request, issued previewId, confirm: true and a unique idempotencyKey (8–200 characters). The single-use preview expires after 120 seconds. Built-in chat additionally requires its native server-owned approval. Success returns the public ID and a platform link after exact record readback. Repeating the same key replays the receipt without another insert. An uncertain result must not be retried with a fresh key or preview: inspect the library first; unresolved operations require operator reconciliation.

Server mutations, idempotency storage and separately granted mcp:reports:create / mcp:dashboards:create scopes on an explicitly approved user target are required. Read grants and global read mode never imply these scopes. Ordinary Directus permissions and workspace/dataset checks remain in force. STDIO remains read-only. Installing tools does not grant production access or enable mutations.

Current tool identifiers

The full identifier list below is checked during documentation build. Always obtain parameter details for a specific installation from tools/list.

list_notifications, list_alerts, get_alert, list_activity, list_datasets, get_distinct_values, run_query, run_report, run_widget, get_dataset, validate_query, explain_query, get_dashboard, get_report, list_exports, get_export_status, download_export, preview_export, mark_notification_read, mark_all_notifications_read, request_export, list_workspaces, search, get_library, list_favorites, get_default_dashboard, add_favorite, remove_favorite, preview_create_report, create_report, preview_create_dashboard, create_dashboard

Not supported yet

Resources include prizma://capabilities, prizma://glossary and dataset catalogs. Tools do not expose arbitrary CRUD, object deletion, raw SQL, user administration or token issuance. Changes are limited to explicitly registered actions with separate permissions and confirmation.

Do not infer a capability from the product name alone; verify the current tools/list response.

Security and limitations

• Current tools include read operations and limited actions within the user’s permissions. Never assume that a tool is available or modifies data: always inspect the current schema with tools/list before calling it.
• Access is checked by Prizma BI for every call.
• Do not include secrets or unnecessary personal data in requests.
• Do not ask an agent to bypass RLS/CLS or guess object identifiers.
• Access errors intentionally do not disclose whether an inaccessible object exists.
• Production still requires ingress authentication, rate limiting, audit, metrics, and stateful session storage; the current transport is intended for staging/first vertical slice.

Verify the connection

1. Run tools/list and confirm list_workspaces, search, get_dashboard, list_notifications, list_alerts, get_report, and run_query are present.
2. Call list_workspaces with no arguments.
3. Select an accessible dashboard public ID.
4. Run a small run_query with a limit of 100 rows or less.
5. Confirm that the result matches the user’s permissions.

If the connection fails, check the /mcp URL, Bearer token, token expiry, and server availability. Do not include the token in a support request; provide only the error time and an anonymized client description.

Next steps

Start with the quick start, then read working with reports. Contact your workspace administrator for access questions.

{
  "query": "revenue",
  "types": ["dashboard", "report"],
  "limit": 20
}

Authorization: Bearer <token>