BitScale MCP Server

Instructions

Implementation Reference

• main.py:159-234 (handler)

  The 'run_grid' tool implementation, which includes the @mcp.tool decorator and the function logic to run a BitScale grid.

  @mcp.tool()
  def run_grid(
      grid_id: str,
      inputs: dict[str, str],
      mode: str = "sync",
      output_columns: list[str] | None = None,
      source_id: str | None = None,
  ) -> str:
      """
      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).
      """
      if not grid_id:
          raise ValueError("grid_id must not be empty")
      if not inputs:
          raise ValueError("inputs must not be empty — provide at least one input column key-value pair")
  
      body: dict = {
          "mode": mode,
          "inputs": inputs,
      }
      if output_columns:
          body["output_columns"] = output_columns
      if source_id:
          body["source_id"] = source_id
  
      # Sync mode can take up to 120s; use 130s timeout to avoid premature client timeout
      timeout = 135 if mode == "sync" else 30
      data = _post(f"/grids/{grid_id}/run", body, timeout=timeout)
      return json.dumps(data, indent=2)