BitScale MCP Server

Get details about the current BitScale workspace — plan info, credit balances, people/company search limits, and member counts.

The workspace is identified automatically from the API key configured during MCP setup. No parameters needed.

Returns: workspace id, name, plan (name, credits_included, billing_interval, next_billing_date, price), credits (total, used, remaining, plan_credits, rollover, topup), people_company_searches (limit, used, remaining), and members (total, owners, admins, editors).

List all Grids in the workspace with their column definitions.

Grids are spreadsheet-like tables in BitScale that hold data rows and enrichment/formula columns. Use this to discover available grids before running them.

Args: search: Optional keyword to filter grids by name (case-insensitive substring match). Example: "leads" to find lead-related grids. page: Page number for pagination (1-based, default: 1). limit: Results per page (default: 20, max: 100).

Returns: paginated list of grids, each with id, name, description, row_count, column_count, created_at, updated_at, and columns array. The columns array contains only runnable columns (type: enrichment, formula, or merge) with their id (column UUID), name, type, and dependencies.

Use the grid id from the results to call get_grid_details or run_grid. Note: the column UUIDs here are used for output_columns in run_grid. The input labels for run_grid are separate human-readable keys derived from the grid's API data source configuration.

Get full metadata for a specific Grid, including all column definitions, grid settings, and attached data sources.

Use this to inspect a grid's schema before running it — especially to understand the grid's input labels and output column UUIDs needed for the run_grid tool.

Args: grid_id: UUID of the grid. Found in the grid URL at app.bitscale.ai/grid/{gridId}, or from list_grids results.

Returns: grid id, name, description, row_count, created_at, updated_at, settings (auto_run, auto_dedupe, visibility, dedupe_column_id), columns (all columns including text, enrichment, formula, merge types with their id/key and name), and sources (data sources with schedule info).

NOTE on columns vs run_grid inputs:

• The column 'id' values here are UUIDs — use these for the 'output_columns' parameter of run_grid to filter which outputs you want.

• The 'inputs' parameter of run_grid uses human-readable LABELS (e.g. "company_name", "website"), NOT column UUIDs. These labels are derived from the API data source columns configured on the grid. You can find the exact input labels in the BitScale app under the grid's Data Source → BitScale API panel, or by inspecting the source column names.

Run a BitScale Grid by appending a new row with the given inputs and triggering all column enrichments.

This is the primary tool for executing BitScale workflows. It adds a row to the grid, runs all enrichment/formula/merge columns, and returns the enriched outputs.

IMPORTANT — inputs vs output_columns use DIFFERENT key formats:

• 'inputs' uses human-readable LABELS (e.g. "company_name", "website") — these are NOT UUIDs. The labels are derived from the source columns configured on the grid's BitScale API data source. You can find the exact labels in the BitScale app by clicking the Data Source column, selecting the BitScale API source, and looking at the input fields.

• 'output_columns' uses column UUIDs from get_grid_details to filter which output columns to return.

Before calling this, use get_grid_details to understand the grid schema. To discover the exact input labels, check the grid's API data source panel in the BitScale app, or look at the source column configuration.

Args: grid_id: UUID of the grid to run. Found in grid URL or list_grids. inputs: Key-value map of input LABELS to their values. These are human-readable keys like "company_name", "website", "email" — NOT column UUIDs. Example: {"company_name": "Acme Corp", "website": "acme.com"} mode: Execution mode — "sync" (default) or "async". - sync: waits up to 120 seconds for completion, returns outputs directly. If still processing, returns a request_id to poll with get_run_status. - async: returns a request_id immediately. Poll get_run_status for results. output_columns: Optional list of column UUIDs to include in the response. Use the column 'id' values from get_grid_details. If omitted, all enriched columns are returned. source_id: Optional UUID of a specific BitScale API data source on the grid. If omitted, the first available source is used.

Returns:

• sync completed: {mode, status: "completed", outputs: {column_uuid: {value, name}}}

• sync timeout or async: {mode, status: "running", request_id, poll_url}

The outputs object keys are column UUIDs, each containing {value, name} where 'name' is the human-readable column display name.

If status is "running", use get_run_status with the returned request_id to poll for completion (every 2-5 seconds).

Check the status of a previously triggered Grid run.

Use this after run_grid returns a request_id (either from async mode or when sync mode times out after 120 seconds).

Poll every 2-5 seconds until status is "completed" or "failed". Avoid polling more frequently as requests count toward the rate limit (5 req/sec per workspace).

Args: request_id: The request_id UUID returned by run_grid.

Returns: {mode, status, grid_id, outputs (when completed)}. Status is one of: "running", "completed", or "failed". When completed, outputs contains {column_id: {value, name}} for each enriched column.

Get a ready-to-use curl command and structured API contract for running a specific Grid. Call this BEFORE run_grid to discover the exact input fields required by the grid — no trial and error needed.

This endpoint returns the derived required inputs (traced from column dependencies), the full run URL, request body shape, and a copy-paste- ready curl command.

💡 Recommended workflow: 1. Call get_grid_curl to discover the exact input fields. 2. Call run_grid with the returned inputs shape and real values.

Args: grid_id: UUID of the grid. Found in the grid URL at app.bitscale.ai/grid/{gridId}, or from list_grids. output_columns: Optional comma-separated list of column key IDs to include in the run. When provided, required inputs are derived only from the dependencies of the specified columns. When omitted, inputs are derived from all runnable columns in the grid. Example: "col-uuid-1,col-uuid-2"

Returns: grid_id, grid_name, run_url, method, headers, request_body (with mode, inputs shape, and optional output_columns), output_columns array (id, name, type for each requested column), and a curl string ready to copy-paste into a terminal (replace YOUR_WORKSPACE_API_KEY).

Generate a new workspace API key and immediately invalidate the current one.

WARNING: This action is irreversible. The moment this succeeds, the key used to call it stops working. All integrations must be updated with the new key immediately, and this MCP server must be restarted with the new BITSCALE_API_KEY environment variable.

Returns: {"api_key": "sk-live-newkey..."} — the new workspace API key.