Documentation Index Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
Use this file to discover all available pages before exploring further.
Overview The Narrative MCP server exposes platform operations as tools that AI assistants can discover and call. All tool names use the narrative_ prefix. This page documents every available tool, its parameters, and usage patterns.
For setup instructions, see Connecting to the Narrative MCP Server . For background on how the server works, see MCP Server for Agents .
Server URL https://mcp.narrative.io/mcp
Context tools Context tools manage your authenticated session and company scope.
narrative_context_get_companiesLists the companies the authenticated user belongs to.
Parameter Type Required Description (none) Returns all companies for the current user
Returns each company’s id and name. Use this to discover which companies you can switch to.
narrative_context_set_companySwitches the active company for the current session. All subsequent tool calls operate against the selected company until changed.
Parameter Type Required Description company_idinteger Yes The company to switch to
narrative_context_search_companiesSearches companies by name using case-insensitive substring matching. Available to global administrators only.
Parameter Type Required Description querystring Yes Search term to match against company names per_pageinteger No Results per page (default: 50, max: 100)
Returns { id, name } for each matching company.
Dataset tools let you search, describe, and inspect datasets.
narrative_datasets_searchFinds datasets by name, description, or tags.
Parameter Type Required Description search_termstring Yes Text to search across dataset names, descriptions, and tags
narrative_datasets_describeDescribes one or more datasets with configurable detail levels. Accepts multiple dataset ids in a single call and fetches them in parallel.
Parameter Type Required Description dataset_idsinteger[] Yes One or more dataset ids to describe includestring[] No Sections to include (default: ["metadata", "schema"]) formatstring No Response format: "markdown" (default) or "json"
Available include values: Value Description metadataName, id, description, owner schemaColumn types and attribute mappings mappingsRosetta Stone mappings on the dataset sampleSample rows statsDataset-level statistics (not per-column) column_stats_configWhich columns have statistics configured retention_policyData retention settings nqlGenerated NQL snippet to query the dataset
narrative_dataset_get_column_statsReturns per-column statistics for a single dataset.
Parameter Type Required Description dataset_idinteger Yes The dataset to inspect columnsstring[] Yes Column names to retrieve stats for includestring[] No Stat types to include (default: ["basic_column_stats"]) formatstring No Response format: "markdown" (default) or "json"
Available include values: Value Description basic_column_statsAll statistics except histogram — safe for context budget histogramOpt-in; can produce large responses on wide columns
narrative_dataset_set_column_stats_configConfigures which columns have statistics collected on a dataset.
Parameter Type Required Description dataset_idinteger Yes The dataset to configure configobject Yes Column statistics configuration
These tools trigger asynchronous operations on datasets. All return a job or operation id that you can poll for completion.
narrative_dataset_request_sampleEnqueues a sampling job for a dataset.
Parameter Type Required Description dataset_idinteger Yes The dataset to sample compute_pool_idstring No Target a specific compute pool; otherwise uses the dataset’s configured pool
Returns the job id. Poll completion with narrative_nql_get_job.
narrative_dataset_refresh_materialized_viewTriggers a refresh of a materialized-view dataset.
Parameter Type Required Description dataset_idinteger Yes The materialized view dataset to refresh typestring Yes "full" (reprocess all snapshots) or "incremental" (skip already-processed snapshots)compute_pool_idstring No Target a specific compute pool
Returns the refresh job id. Poll completion with narrative_nql_get_job.
narrative_dataset_recalculate_statisticsEnqueues a column-statistics recalculation across the dataset’s snapshot range.
Parameter Type Required Description dataset_idinteger Yes The dataset to recalculate stats for from_snapshotstring No Start from a specific snapshot; otherwise recalculates all snapshots in the stats configuration
Returns the recalculation id, queued snapshot count, and snapshot timestamp range.
Attribute tools let you explore and inspect Rosetta Stone attributes.
narrative_attributes_searchSearches Rosetta Stone attributes by name.
Parameter Type Required Description search_termstring Yes Text to search across attribute names and descriptions includestring[] No Sections to include (default: ["metadata"]) formatstring No Response format: "markdown" (default) or "json"
Available include values: Value Description metadataId, name, display name, description, type, tags schemaProperties, required fields, enum values
narrative_attributes_describeDescribes one or more attributes by id. Accepts multiple attribute ids in a single call.
Parameter Type Required Description attribute_idsinteger[] Yes One or more attribute ids to describe includestring[] No Sections to include (default: ["metadata", "schema"]) formatstring No Response format: "markdown" (default) or "json"
Uses the same include values as narrative_attributes_search.
NQL tools let you validate, execute, and track NQL queries.
narrative_nql_validateCompile-checks an NQL query without executing it. Returns the compiled SQL on success, or validation errors pointing to the offending part of the query.
Parameter Type Required Description querystring Yes The NQL query to validate
Use narrative_nql_validate to test Rosetta Stone mapping expressions cheaply. Validate a candidate expression by running SELECT expression FROM company_data."dataset_id" through the tool — if it compiles, the expression is valid against the dataset’s schema.
narrative_nql_runSubmits an NQL query for asynchronous execution. Supports SELECT queries, EXPLAIN forecasts, and CREATE MATERIALIZED VIEW statements.
Parameter Type Required Description querystring Yes The NQL query to execute data_plane_idstring No Target a specific data plane; otherwise uses the company default compute_pool_idstring No Target a specific compute pool; otherwise uses the company default
Returns a job descriptor in state: pending with a polling hint.
narrative_nql_get_jobPolls a job by id to retrieve its current state, compiled SQL, result payload, and any failures.
Parameter Type Required Description job_idstring Yes The job id to poll data_plane_idstring No The data plane the job runs on compute_pool_idstring No The compute pool the job runs on
Usage patterns Recommended NQL flow The most effective pattern for running queries is validate → run → poll :
Validate the query with narrative_nql_validate to catch syntax errors before enqueuing a job.Run the validated query with narrative_nql_run to submit it for execution.Poll with narrative_nql_get_job until the job reaches a terminal state.
This avoids enqueuing jobs that would fail at compile time and keeps long-running executions out of the synchronous request path.
Dataset inspection flow To understand a dataset’s structure and content:
Search with narrative_datasets_search to find datasets by name or description.Describe with narrative_datasets_describe using include=["metadata", "schema"] for an overview, or add "sample" and "stats" for deeper inspection.Inspect columns with narrative_dataset_get_column_stats for detailed per-column statistics.
Multi-company workflows If you belong to multiple companies:
List your companies with narrative_context_get_companies.Switch with narrative_context_set_company to set the active company.All subsequent tool calls operate against the selected company until you switch again.
Naming conventions
Plural names (datasets_describe, attributes_describe) accept multiple ids per call.Singular names (dataset_get_column_stats, dataset_request_sample) operate on a single entity.All tools use the narrative_ prefix.
Related content
Connecting to the Narrative MCP Server Set up your MCP client
Data Collaboration MCP Server How the MCP server works
NQL Design Philosophy Understand the query language behind NQL tools
Rosetta Stone The schema normalization system behind attribute tools
