BI Portal — Report Builder MCP Server

An MCP server exposing the BI Portal's self-service Report Builder to MCP clients (Claude Desktop, Claude Code, or any other MCP-speaking agent): list datasets, run ad-hoc queries, create/edit/submit draft reports, and view saved dashboards.

Why this is its own repo, not part of backend/

It's a thin HTTP client of the backend's REST API — no backend Python imports, no direct Postgres access. Everything it does goes through the exact same /api/explore/*, /api/reports/*, and /api/dashboards/* endpoints the React UI uses, so every RBAC check the backend already enforces applies automatically; this server can't become a second, independently-drifting authorization path. Being a separate repo means it deploys, versions, and can break independently of the backend and UI — see the root docs/architecture.md for the fuller rationale on why this was cut out as its own service while Report Builder's actual query logic stayed in the backend.

Two identity modes

Every tool call is attributed to whichever Bearer token this process is configured with — the server itself doesn't know or care which mode is active, only the backend does.

• delegated (default) — acts as a real logged-in human, inheriting exactly their roles. Mint a token from the backend while your portal session is live:

  curl -X POST http://localhost:8000/auth/token \
    -H "Content-Type: application/json" \
    -b "session=<your browser's session cookie>" \
    -d '{"label": "my MCP client"}'
  

  The response's token field (pat_...) is shown once — copy it into BI_PORTAL_TOKEN.
• fixed — acts as a standing service identity (e.g. a FinanceReportGen-scoped account) independent of who's driving the agent. An Admin mints one:

  curl -X POST http://localhost:8000/api/admin/service-identities \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <an Admin's pat_ token>" \
    -d '{"name": "mcp-reportsgen", "groups": ["FinanceReportGen"]}'
  

  The response's token field (svc_...) is shown once — copy it into BI_PORTAL_TOKEN.

Setup

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # fill in BI_PORTAL_BASE_URL / BI_PORTAL_AUTH_MODE / BI_PORTAL_TOKEN
pytest                 # runs against a mocked backend, no live server needed

Run directly over stdio (what most desktop MCP clients expect):

python -m mcp_bi_portal.server

Example Claude Desktop / Claude Code MCP client config:

{
  "mcpServers": {
    "bi-portal-report-builder": {
      "command": "/path/to/mcp-server/.venv/bin/python",
      "args": ["-m", "mcp_bi_portal.server"],
      "env": {
        "BI_PORTAL_BASE_URL": "http://localhost:8000",
        "BI_PORTAL_AUTH_MODE": "delegated",
        "BI_PORTAL_TOKEN": "pat_..."
      }
    }
  }
}

Tools

Tool	Backend endpoint
list_datasets	GET /api/explore/datasets
run_explore_query	POST /api/explore/run
create_draft_report	POST /api/reports
update_draft_report	PATCH /api/reports/{id}
get_report	GET /api/reports/{id}
submit_report	POST /api/reports/{id}/submit
view_report_builder_dashboard	GET /api/dashboards/report-builder
view_custom_query_dashboard	GET /api/dashboards/custom-query

Review/approve is deliberately not exposed — the tool surface is scoped to authoring, not the full REST API. (For a fixed ReportGen-style identity this is also enforced server-side, not just by omission here: require_domain_review_access rejects any identity that isn't in a domain's admin_group_name.)

Deployment

MCP servers for desktop/CLI clients are conventionally a local subprocess over stdio, launched by the client itself — there's no standing network service by default, unlike backend/ui. See deployment/README.md for the optional streamable-http path and why the K8s manifests for this service are marked optional.