Grid MCP Usage

Last updated: April 29, 2026

Grid MCP connects directly to your Grid workspace, letting you query metrics, explore customer and billing data, and run reports via natural language and AI tooling.

Every session starts the same way:

Key Concepts

Grid has different objects and data structures queryable via MCP.

Term

Meaning

Grid

A workspace combining one or more data sources

grid_id

Required on every tool call — get it from list_grids

Metric

A computed KPI: ARR, MRR, NRR, churn, CAC, etc. Grid has 150+ built-in

Chart

A saved metric visualization (time series, cohort, waterfall)

Report

A saved tabular multi-metric view

Dashboard

A collection of charts and reports

Segment

A saved filter applied to metrics (e.g. "Enterprise only")

Grouping

Split a metric by a dimension (e.g. ARR by plan tier)

Quickstart

  1. List your grids to find the grid_id you want to work with

  2. Use that grid_id in every subsequent tool call

"List my grids"
→ list_grids()

"Show me the dashboards in my main grid"
→ list_dashboards(grid_id)

"What was our ARR last quarter?"
→ run_ad_hoc_calc(grid_id, "ARR for Q1 2025")

Functions

Tool

Description

list_grids

List all grids (workspaces) you have access to

get_grid_detail

Get details about a specific grid

list_dashboards

List dashboards in a grid

list_charts_and_reports

List all charts and reports in a grid

get_customer

Get a specific customer record

get_subscription

Get a specific subscription record

get_invoice

Get a specific invoice record

get_opportunity

Get a specific opportunity record

search_grid_objects

Search for customers, subscriptions, invoices, etc.

run_report

Run a saved report and return results

run_chart

Run a saved chart and return data

run_ad_hoc_calc

Calculate a metric on the fly with custom parameters

search_documentation

Search Grid's documentation

For a detailed breakdown of each function, see below:

Tools

list_grids

List all grids (workspaces) your organization has access to. Always call this first. Returns grid names and IDs.

Parameters: none

Example prompt: "What grids do I have?"

get_grid_detail

Get full configuration and metadata for a grid, including all connected data sources (Salesforce, Stripe, HubSpot, etc.) and their sync status.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

ID of the grid to inspect

Example prompt: "What data sources are connected to my grid?"

list_dashboards

List all dashboards in a grid with their names and IDs.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid to list dashboards for

Example prompt: "What dashboards do I have?"

list_charts_and_reports

List all charts and reports in a grid. Optionally scope to a specific dashboard for faster, more focused results.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid to search

dashboard_id

integer

❌

Scope to a specific dashboard

Tip: Pass a dashboard_id when you know which dashboard you want — it's faster and returns higher-quality candidates.

Example prompt: "Show me all the charts on my Revenue dashboard"

run_report

Execute a saved report and return all metric results in tabular form.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid the report belongs to

report_id

integer

✅

ID of the report to run

Example prompt: "Run the Monthly KPIs report"

run_chart

Execute a saved chart and return all data series (time series, cohort, or waterfall).

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid the chart belongs to

chart_id

integer

✅

ID of the chart to run

Example prompt: "Pull the ARR over time chart"

run_ad_hoc_calc

Calculate any metric on the fly using natural language — no saved chart or report needed. Grid selects the right metrics, date range, groupings, and segments automatically.

Use this when no existing chart or report matches what the user is asking. Prefer run_chart / run_report when a relevant saved view already exists.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid to calculate against

prompt

string

✅

Natural language description of what to analyse

include_drilldown

boolean

❌

Set true to get line-item detail (e.g. list of churned customers). Default: false

Example prompts:

  • "What's our NRR for the last 12 months?"

  • "Show ARR grouped by plan tier"

  • "Which customers churned this quarter?" → use include_drilldown: true

  • "CAC payback period by acquisition channel for 2024"

search_grid_objects

Full-text search across customers, subscriptions, invoices, and opportunities. Returns matching objects with IDs — use those IDs with the get_* tools to fetch full detail.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid to search

query

string

✅

Keyword or name to search (min 2 characters)

model_types

array

❌

Filter by type: customer, subscription, invoice, opportunity

Example prompts:

  • "Find the customer Acme Corp"

  • "Search for invoices from Stripe"

  • "Look up the subscription for TechCo"

get_customer

Get full detail for a customer including all their subscriptions and revenue.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid the customer belongs to

customer_id

string

✅

Grid customer ID (gc_...) or raw ID (cus_...)

Example prompt: "Show me everything about customer gc_abc123"

get_subscription

Get full detail for a subscription including associated invoices and MRR.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid the subscription belongs to

subscription_id

string

✅

The subscription ID

Example prompt: "Pull up subscription sub_xyz for me"

get_invoice

Get full detail for an invoice including all line items and formatted dates.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid the invoice belongs to

invoice_id

string

✅

The invoice ID

Example prompt: "Show me invoice in_abc"

get_opportunity

Get full detail for an opportunity including line items and revenue. Supports contracted vs live ARR.

Parameters:

Name

Type

Required

Description

grid_id

string

✅

The grid the opportunity belongs to

opportunity_id

string

✅

The opportunity ID

use_contracted

boolean

❌

Use contracted ARR (true) vs live ARR (false). Default: false

Example prompt: "Get opportunity opp_123 using contracted ARR"

search_documentation

Search Grid's help center and documentation. Use this before answering any question about how Grid works, what features exist, or how metrics are calculated.

Parameters:

Name

Type

Required

Description

query

string

✅

Search query

Example prompts:

  • "How does Grid calculate NRR?"

  • "What's the difference between ARR and MRR recognition?"

  • "How do segments work?"

Common Workflows

Explore a workspace

list_grids()
→ pick a grid_id

get_grid_detail(grid_id)
→ see connected data sources

list_dashboards(grid_id)
→ see what dashboards exist

list_charts_and_reports(grid_id, dashboard_id)
→ see charts and reports on a dashboard

Answer a metrics question

# If a saved chart/report exists:
list_charts_and_reports(grid_id)
→ find chart_id or report_id
run_chart(grid_id, chart_id)
  — or —
run_report(grid_id, report_id)

# If no saved view exists:
run_ad_hoc_calc(grid_id, "your question in plain English")

Look up a specific customer or deal

search_grid_objects(grid_id, "Acme Corp", model_types=["customer"])
→ get customer_id from results

get_customer(grid_id, customer_id)
→ full customer detail including subscriptions

Drill into billing detail

search_grid_objects(grid_id, "TechCo", model_types=["subscription"])
→ get subscription_id

get_subscription(grid_id, subscription_id)
→ see invoices and MRR

get_invoice(grid_id, invoice_id)
→ see line items

Tips

  • Always call list_grids first — every other tool needs a grid_id

  • Use run_ad_hoc_calc freely — it handles natural language and picks the right metrics automatically

  • Add include_drilldown: true when you need to see which customers/records drive a number

  • Use search_grid_objects → get_* pattern to navigate from search results to full detail

  • Scope list_charts_and_reports to a dashboard when possible — faster and more focused results

  • Call search_documentation before answering questions about how Grid calculates any metric