Data Collaboration MCP Server

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`

Returns the current session context: authenticated user, role, and active company (if one has been set).

Parameter	Type	Required	Description
(none)			Returns the current user, role, and active-company selection

Use this to confirm which company is active before running queries or operations. If no company is set, follow up with narrative_context_set_company.

`narrative_context_get_companies`

Lists 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_company`

Switches the active company for the current session. All subsequent tool calls operate against the selected company until changed.

Parameter	Type	Required	Description
`company_id`	integer	Yes	The company to switch to

`narrative_context_search_companies`

Searches companies by name using case-insensitive substring matching. Available to global administrators only.

Parameter	Type	Required	Description
`search_term`	string	Yes	Search term to match against company names
`per_page`	integer	No	Results per page (default: 50, max: 100)

Returns { id, name } for each matching company.

Dataset tools

Dataset tools let you search, describe, and inspect datasets.

`narrative_datasets_search`

Finds datasets by fuzzy keyword match, tags, or data plane. At least one filter must be supplied — calling with no filters returns an error rather than the full corpus. Filters compose with AND.

Parameter	Type	Required	Description
`search_term`	string	No	Fuzzy-matched against dataset `name`, `display_name`, and `description`. Matches on `name` and `display_name` rank above `description`-only matches of equal strength. Does NOT match `tags`.
`tags`	string[]	No	Exact-match all-of filter (case-sensitive). A dataset is returned only if it carries every supplied tag.
`data_plane_id`	string (uuid)	No	Restrict to a single data plane. Use `narrative_data_planes_list` to discover ids.
`include`	string[]	No	Sections to include per match

Returns at most 50 ranked matches. If the response indicates more matches exist, narrow the filters and retry. For full metadata on a shortlisted dataset, call narrative_datasets_describe with its id.

`narrative_datasets_describe`

Describes 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_ids`	integer[]	Yes	One or more dataset ids to describe
`include`	string[]	No	Sections to include (default: `["metadata", "schema"]`)
`format`	string	No	Response format: `"markdown"` (default) or `"json"`

Available include values:

Value	Description
`metadata`	Name, id, description, owner
`schema`	Column types and attribute mappings
`mappings`	Rosetta Stone mappings on the dataset
`sample`	Sample rows
`stats`	Dataset-level statistics (not per-column)
`column_stats_config`	Which columns have statistics configured
`retention_policy`	Data retention settings
`nql`	For materialized-view datasets, the NQL query that defines the view
`refresh_schedule_config`	For materialized-view datasets, the active refresh schedule (cron, status, timezone, timestamps)

`narrative_dataset_get_column_stats`

Returns per-column statistics for a single dataset.

Parameter	Type	Required	Description
`dataset_id`	integer	Yes	The dataset to inspect
`columns`	string[]	Yes	Column names to retrieve stats for
`include`	string[]	No	Stat types to include (default: `["basic_column_stats"]`)
`format`	string	No	Response format: `"markdown"` (default) or `"json"`

Available include values:

Value	Description
`basic_column_stats`	All statistics except histogram — safe for context budget
`histogram`	Opt-in; can produce large responses on wide columns

`narrative_dataset_set_column_stats_config`

Configures which columns have statistics collected on a dataset.

Parameter	Type	Required	Description
`dataset_id`	integer	Yes	The dataset to configure
`config`	object	Yes	Column statistics configuration

Dataset operation tools

These tools trigger asynchronous operations on datasets. All return a job or operation id that you can poll for completion.

`narrative_dataset_request_sample`

Enqueues a sampling job for a dataset.

Parameter	Type	Required	Description
`dataset_id`	integer	Yes	The dataset to sample
`compute_pool_id`	string	No	Target a specific compute pool; otherwise uses the dataset’s configured pool

Returns the job id. Poll completion with narrative_jobs_describe.

`narrative_dataset_refresh_materialized_view`

Triggers a refresh of a materialized-view dataset.

Parameter	Type	Required	Description
`dataset_id`	integer	Yes	The materialized view dataset to refresh
`type`	string	Yes	`"full"` (reprocess all snapshots) or `"incremental"` (skip already-processed snapshots)
`compute_pool_id`	string	No	Target a specific compute pool

Returns the refresh job id. Poll completion with narrative_jobs_describe.

`narrative_dataset_recalculate_statistics`

Enqueues a column-statistics recalculation across the dataset’s snapshot range.

Parameter	Type	Required	Description
`dataset_id`	integer	Yes	The dataset to recalculate stats for
`from_snapshot`	string	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.

`narrative_dataset_update`

Updates the safe, curator-editable metadata of a dataset: display name, description, and tags. Wraps PUT /datasets/:id. Structural fields (name, schema, write mode) are never editable through this tool.

Parameter	Type	Required	Description
`dataset_id`	integer	Yes	Dataset to update
`display_name`	string	No	New human-readable display name (must be non-empty). Omit to leave unchanged
`description`	string	No	New description. Omit to leave unchanged
`add_tags`	string[]	No	Tags to add to the dataset’s existing tags
`remove_tags`	string[]	No	Tags to remove from the dataset’s existing tags

At least one of display_name, description, add_tags, or remove_tags must be provided. Omitted fields are left unchanged (partial update). Tags are edited additively: the tool reads the dataset’s current tags, applies add_tags and remove_tags, then writes the resulting set. A small set of platform-managed system tags — _nio_view, _nio_inference, _nio_cached_mapping, _nio_materialized_view, and _nio_refresh_use_workflow — are immutable and silently ignored if included in add_tags or remove_tags; any other tag (including custom _nio* tags) is caller-controlled. pending datasets accept updates to all safe fields; active datasets accept display name, description, and tags; archived datasets reject any update.

The upstream endpoint currently treats an empty tag list as a no-op, so a remove_tags that would clear the dataset’s last remaining tag is rejected with a clear error rather than silently ignored.

Returns a confirmation with the updated display name, description, and tags.

Attribute tools

Attribute tools let you explore, inspect, and create Rosetta Stone attributes.

`narrative_attributes_search`

Searches Rosetta Stone attributes by name.

Parameter	Type	Required	Description
`search_term`	string	Yes	Text to search across attribute names and descriptions
`include`	string[]	No	Sections to include (default: `["metadata"]`)
`format`	string	No	Response format: `"markdown"` (default) or `"json"`

Available include values:

Value	Description
`metadata`	Id, name, display name, description, type, tags
`schema`	Properties, required fields, enum values

`narrative_attributes_describe`

Describes one or more attributes by id. Accepts multiple attribute ids in a single call.

Parameter	Type	Required	Description
`attribute_ids`	integer[]	Yes	One or more attribute ids to describe
`include`	string[]	No	Sections to include (default: `["metadata", "schema"]`)
`format`	string	No	Response format: `"markdown"` (default) or `"json"`

Uses the same include values as narrative_attributes_search.

`narrative_attribute_create`

Creates a new attribute owned by the currently selected company. Wraps POST /attributes.

Parameter	Type	Required	Description
`name`	string	Yes	Identifier for the attribute (alphanumeric characters or underscores, < 255 chars). Used when the attribute is referenced in validations.
`display_name`	string	Yes	Public-facing descriptive name.
`type_definition`	object	Yes	The attribute’s type — a scalar, object, or array shape (see below).
`description`	string	No	What the attribute represents, including collection methodology and assumptions.
`tags`	string[]	No	Tags to associate with the attribute.

The type_definition argument accepts one of these shapes:

Scalar types — { "type": "string" | "long" | "double" | "boolean" | "timestamptz" }. string and long accept an optional enum of allowed values. All scalars accept optional validations: Spark SQL boolean expressions over $this that a value must satisfy (e.g. "$this >= 0").
Object types — { "type": "object", "properties": { <name>: <type definition>, ... }, "required": [ <name>, ... ] }. Nest additional type definitions inside properties.
Array types — { "type": "array", "items": <type definition> }.

Attributes are created private to the owning company (no view/map collaborators); sharing is managed through the Narrative app or API. The created attribute’s id, name, display name, type, description, tags, owning company, and schema details are returned in the response.

Search the catalog with narrative_attributes_search before creating a new attribute — mapping into an existing attribute keeps the marketplace’s shared vocabulary consistent. A good reason to create a new attribute is to define the type contract for a downstream system (usually reached through a connector) that data is normalized into.

See attribute types for the full type reference.

Access rule tools

Access rule tools let you discover and inspect access rules — the permissions and pricing controls applied to datasets — that your company owns or has been granted.

`narrative_access_rules_search`

Searches access rules the active company has access to. At least one filter must be provided; calling with no filters returns an error rather than dumping the full corpus.

Parameter	Type	Required	Description
`search_term`	string	No	Fuzzy-matched against name, display name, description, owning company name, and slug. Matches on name and display name rank above description / company matches of equal strength.
`exposed_attribute_names`	string[]	No	Filter to rules that expose any of these Rosetta Stone attributes (discover names via `narrative_attributes_search`)
`tags`	string[]	No	Filter to rules carrying any of these tags
`dataset_ids`	integer[]	No	Filter to rules referencing any of these datasets
`owned_only`	boolean	No	Restrict to rules owned by the active company
`shared_only`	boolean	No	Restrict to rules shared with (but not owned by) the active company
`can_be_used_in_nql_only`	boolean	No	Drops rules that cannot be referenced in NQL (default: `true`). Set to `false` to include those too.
`data_plane_id`	string (uuid)	No	Restrict to rules on a single data plane. Use `narrative_data_planes_list` to discover ids.
`include`	string[]	No	Sections to include per match (default: `["data_plane_id", "description", "mappings"]`)

Filters compose with AND. Matches are ranked by fuzzy score with name-side fields weighted above description and company fields, and truncated with an explicit note when the cap fires; refine the filters if you see the truncation message. Available include values:

Value	Description
`data_plane_id`	UUID of the data plane the rule runs on
`description`	Rule description
`mappings`	Attributes the rule exposes
`tags`	Tags attached to the rule

To reference a rule in NQL, use <owning_company_slug>.<access_rule_name>.

`narrative_access_rules_describe`

Describes one or more access rules by id. Accepts multiple ids in a single call and fetches them in parallel.

Parameter	Type	Required	Description
`access_rule_ids`	integer[]	Yes	One or more access rule ids to describe
`include`	string[]	No	Sections to include (default: `["metadata", "mappings"]`)

Available include values:

Value	Description
`metadata`	Name, display name, description, owning company, data plane id, type, status, tags, dataset ids, timestamps
`mappings`	Attributes the rule exposes
`nql`	Generated NQL snippet for the rule
`schema`	Output schema as JSON
`collaborators`	Sharing and collaborator configuration
`pricing`	Price in CPM USD

Mapping tools

Mapping tools let you create Rosetta Stone mappings from datasets to attributes in the active company.

`narrative_mapping_create`

Creates a private mapping from a dataset to an attribute in the currently selected company. The mapping defines how each of the attribute’s properties is built from a row of the source dataset, using NQL expressions over the dataset’s columns.

Parameter	Type	Required	Description
`attribute_id`	integer	Yes	ID of the target attribute being mapped to
`dataset_id`	integer	Yes	ID of the source dataset the mapping draws columns from
`mapping`	object	Yes	The mapping definition — an `object_mapping`, a `value_mapping`, or a `cached_mapping` (see below)

The mapping argument accepts one of three shapes:

object_mapping — for attributes whose value is an object. Supply type: "object_mapping" and property_mappings, a list of { path, expression } entries where path is a dotted path to an attribute property (e.g. product.brand) and expression is an NQL expression over dataset columns (e.g. itemBrand). Provide a mapping for each of the attribute’s required properties. Quote string literals like 'SKU'.
value_mapping — for scalar attributes. Supply type: "value_mapping" and a single expression that produces the attribute’s value.
cached_mapping — compiles into a dataset join at query time. Supply type: "cached_mapping" and one or more input_expressions — NQL expressions over the source dataset’s columns that form the join key. The cache dataset is created automatically when the mapping is created, so no cache_dataset_id is supplied. Not permitted on opt-out attributes (data_privacy_request_identifier, unique_id, identifier_relation). See cached_mapping for details.

The dataset must be active and owned by the current company, and you must have map permission on the attribute. The created mapping’s id, scope, source, status, and creation timestamp are returned in the response.

Use narrative_nql_validate to test a candidate mapping expression before submitting it. Run SELECT <expression> FROM company_data."<dataset_id>" — if it compiles, the expression is valid against the dataset’s schema.

See mapping types for the full schema and Mapping schemas for guidance on writing mappings by hand.

Connector tools

Connector tools let you inspect a company’s installed apps and create connections that route dataset data to external connectors. See the connection creation flow below for the recommended order.

`narrative_installations_list`

Lists the apps installed by the currently selected company and flags which ones are connectors. Apps whose categories include destination_connector can receive dataset data through a connection; model_connector apps connect models instead and do not accept dataset connections.

Parameter	Type	Required	Description
`page`	integer	No	1-based page of installations to return (default: 1)
`per_page`	integer	No	Installations per page (default: 100)

Each result shows the installation id, the app id, the app’s name, and its categories. Use the installation id with narrative_app_profiles_list to find the profile a connection is created against.

`narrative_app_profiles_list`

Lists the profiles of an app installation in the currently selected company. A profile’s id is the profile_id that a dataset connection is created against, and only profiles with status enabled can back a connection.

Parameter	Type	Required	Description
`installation_id`	integer	Yes	Numeric installation id from `narrative_installations_list`

If no enabled profile exists, the user must create and enable one in the app’s UI before a connection can be created.

`narrative_app_interfaces_list`

Lists a connector app’s interfaces and their quick-settings JSON Schemas. Use the returned schema to construct the quick_settings object that narrative_connection_create accepts. Interface ids match the ones narrative_dataset_get_compatible_interfaces reports.

Parameter	Type	Required	Description
`app_id`	integer	Yes	Numeric app id of an installed connector (from `narrative_installations_list`)
`include`	string[]	No	Sections to include (default: `[]`)

Available include values:

Value	Description
`metadata`	Interface tags and refresh schedule
`collaboration_policy`	Full JSON-Schema acceptance rules over dataset schemas — large; usually unnecessary because `narrative_dataset_get_compatible_interfaces` already evaluates it

Omit include=["collaboration_policy"] unless you need to explain why a specific dataset was rejected. Use narrative_dataset_get_compatible_interfaces to find accepted interfaces first, then call this tool for their quick_settings schemas only.

`narrative_dataset_get_compatible_interfaces`

Reports which installed connector interfaces accept a dataset’s schema. Run this before narrative_connection_create: an accepted (app_id, interface_id) pair means that connector can receive the dataset’s data.

Parameter	Type	Required	Description
`dataset_id`	integer	Yes	Numeric dataset id to evaluate
`include`	string[]	No	Sections to include (default: `[]`)

Available include values:

Value	Description
`validation_details`	Raw JSON-Schema validation output for each incompatible interface. Can be large — omit unless you need to explain a rejection

Returns two sections: Accepted — the interfaces that can receive the dataset — and Incompatible — the ones that rejected the schema.

`narrative_connection_create`

Creates a connection from a dataset to a connector app, routing the dataset’s data to that destination.

Parameter	Type	Required	Description
`dataset_id`	integer	Yes	Numeric id of the dataset to connect
`profile_id`	string (uuid)	Yes	UUID of an enabled app profile (from `narrative_app_profiles_list`)
`quick_settings`	object	No	Connector-specific settings, forwarded verbatim to the connector. Construct from the interface’s quick-settings JSON Schema returned by `narrative_app_interfaces_list`

Returns the created connection’s id, app, dataset, profile, status, and creation timestamp. The connector validates the schema again at create time and rejects datasets that no longer match an interface.

Connections activate immediately. Confirm the dataset and profile with the user before calling this tool.

NQL tools

NQL tools let you validate, execute, and track NQL queries.

`narrative_nql_validate`

Compile-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
`query`	string	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_execute`

Submits an NQL query to POST /v1/nql/execute for asynchronous execution. Supported statements are INSERT, UPDATE, DELETE, EXPLAIN, and CREATE MATERIALIZED VIEW; SELECT and MERGE are rejected.

Parameter	Type	Required	Description
`nql`	string	Yes	The NQL query to execute
`data_plane_id`	string	No	Target a specific data plane; otherwise uses the company default
`compute_pool_id`	string	No	Target a specific compute pool; otherwise uses the company default

Returns the id of the workflow that runs the query and the id of the workflow run. Poll the run with narrative_workflow_runs_list(workflow_id=...), find the enqueued job with narrative_jobs_search(workflow_run_id=...), then read the result with narrative_jobs_describe.

The tool was previously named narrative_nql_run. The old name is still accepted and transparently routed to narrative_nql_execute, but new integrations should call narrative_nql_execute directly.

Job tools

Job tools let you discover and follow Narrative jobs — the asynchronous units of work spawned by narrative_nql_execute, dataset operations, and workflow runs. Jobs are generic across types; the type field on each response distinguishes nql-forecast, materialize-view, datasets_sample, and others.

`narrative_jobs_describe`

Describes one or more jobs by id in a single call. Use this to poll jobs through to completion — re-invoke until each job’s state is completed, failed, or cancelled.

Parameter	Type	Required	Description
`job_ids`	string[]	Yes	One or more job ids (up to 50 per call)
`include`	string[]	No	Sections to include (default: `["failures", "metadata", "result"]`)

Available include values:

Value	Description
`metadata`	State, type, timestamps, data plane, compute pool
`result`	The job’s result payload (shape depends on job `type`)
`failures`	Any errors recorded against the job
`input`	The original job input
`compiled_sql`	Compiled SQL (NQL-derived jobs only)
`tags`	Tags attached to the job

`narrative_jobs_search`

Searches jobs by tags, state, type, dataset, or data plane. At least one filter must be supplied — calling with no filters returns an error rather than dumping the full corpus.

Parameter	Type	Required	Description
`tags`	string[]	No	Filter by tag (exact-match, case-sensitive). Multiple tags match any job carrying at least one of them
`state`	string	No	One of `pending`, `running`, `completed`, `pending_cancellation`, `cancelled`, `failed`
`type`	string	No	Job-type filter (free-form, e.g. `materialize-view`, `nql-forecast`, `datasets_sample`)
`dataset_id`	integer	No	Only return jobs whose input references this dataset
`data_plane_id`	string	No	Data plane UUID
`workflow_id`	string	No	Workflow UUID. Returns every job ever enqueued by this workflow
`workflow_run_id`	string	No	Workflow run UUID. Returns only jobs enqueued by this specific run
`per_page`	integer	No	Items per page (default: 25, max: 500)
`offset`	integer	No	Number of records to skip. Use `offset = page_index * per_page` to walk pages
`include`	string[]	No	Sections to include per match (default: `["metadata"]`; also accepts `"tags"`)

Pass the returned ids to narrative_jobs_describe for full per-job detail. To find workflow-enqueued jobs, filter with workflow_run_id or workflow_id rather than the older tag convention.

Data plane tools

Data plane tools let you discover the data planes your company has access to. The ids returned here are used by workflow tools and the optional data_plane_id argument on narrative_nql_execute.

`narrative_data_planes_list`

Lists every data plane available to the active company, including Narrative-hosted and any company-owned planes.

Parameter	Type	Required	Description
`include`	string[]	No	Sections to include per result (default: `["metadata"]`)

`narrative_data_planes_describe`

Describes one or more data planes by id. Accepts multiple ids in a single call and fetches them in parallel.

Parameter	Type	Required	Description
`data_plane_ids`	string[]	Yes	One or more data plane UUIDs to describe
`include`	string[]	No	Sections to include (default: `["metadata"]`)

Available include values (shared by both data plane tools):

Value	Description
`metadata`	Display name, status, description, default compute pool, last heartbeat
`compute_pools`	Compute pools attached to the data plane, each with `status`, `size`, `idle_timeout_seconds`, and a derived `always_on` flag (`true`/`false` for AWS EMR pools, `n/a` for Snowflake warehouses that use auto-suspend/resume)
`platform`	Platform-specific configuration as JSON

Both tool descriptions carry usage guidance for connected AI assistants: compute pools with always_on: true skip cold-start cluster spin-up, making small always-on pools ideal for lightweight jobs like narrative_dataset_request_sample.

Workflow tools

Workflow tools let you submit, inspect, and track runs of workflows. The workflow YAML is passed as a free-form string — see the workflow task reference for the YAML shape.

`narrative_workflows_create`

Submits a new workflow from a YAML specification.

Parameter	Type	Required	Description
`specification`	string	Yes	The workflow YAML as a plain string
`data_plane_id`	string	Yes	UUID of the data plane the workflow should run on. Use `narrative_data_planes_list` to discover ids
`trigger_immediately`	boolean	No	Trigger a run as soon as the workflow is created (default: `false`)
`schedule_immediately`	boolean	No	Activate the workflow’s schedule as soon as it is created (default: `false`)
`tags`	string[]	No	Optional tags to attach to the workflow

Returns the created workflow’s id and metadata. When trigger_immediately=true, the response also includes a run_id you can poll with narrative_workflow_runs_list.

`narrative_workflows_trigger`

Triggers a new run of an existing workflow. Returns immediately with the new run’s id; poll the run’s status via narrative_workflow_runs_list.

Parameter	Type	Required	Description
`workflow_id`	string	Yes	UUID of the workflow to trigger

Workflows created through this tool are automatically tagged with created_by_mcp_server so you can filter and audit agent-created workflows in the Narrative app. If the agent supplies the tag explicitly, it is not duplicated.

`narrative_workflows_describe`

Describes one or more workflows by id. Accepts multiple ids in a single call and fetches them in parallel.

Parameter	Type	Required	Description
`workflow_ids`	string[]	Yes	One or more workflow UUIDs to describe
`include`	string[]	No	Sections to include (default: `["metadata"]`)

Available include values:

Value	Description
`metadata`	Name, status, data plane, timestamps, tags, archived state
`specification`	Full workflow YAML — opt in, can be large

Avoid include=["specification"] when scanning many workflows. Request it only after you have narrowed to the ones you actually want to inspect.

`narrative_workflow_runs_list`

Lists runs of a single workflow, in the order the upstream returns them (typically most recent first). Mirrors the upstream paging surface — opaque cursor pagination via page_token.

Parameter	Type	Required	Description
`workflow_id`	string	Yes	UUID of the workflow whose runs to list
`per_page`	integer	No	Items per page (default: 10)
`page_token`	string	No	Opaque cursor from a previous response’s `next_page_token`. Omit for the first page

To find the jobs spawned by a specific run, call narrative_jobs_search with workflow_run_id=<run-uuid>.

Usage patterns

Recommended NQL flow

The most effective pattern for running queries is validate → execute → poll:

Validate the query with narrative_nql_validate to catch syntax errors before enqueuing a workflow.
Execute the validated query with narrative_nql_execute to submit it. The tool returns the workflow id and run id.
Poll the run with narrative_workflow_runs_list(workflow_id=...) until it reaches a terminal state, then use narrative_jobs_search(workflow_run_id=...) and narrative_jobs_describe to read the result.

This avoids enqueuing work 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.

Access rule discovery flow

To find and inspect the access rules available to your company:

Search with narrative_access_rules_search, providing at least one filter (e.g. search_term, exposed_attribute_names, tags, dataset_ids).
Describe shortlisted rules with narrative_access_rules_describe using include=["metadata", "mappings"] for an overview, or add "nql", "schema", "collaborators", or "pricing" for deeper detail.
Reference in NQL using <owning_company_slug>.<access_rule_name>.

Workflow submission flow

To submit and track a workflow from an AI assistant:

Discover available data planes with narrative_data_planes_list to pick a data_plane_id.
Create the workflow with narrative_workflows_create, passing the YAML as specification. Set trigger_immediately=true to start a run right away, or call narrative_workflows_trigger later.
Poll runs with narrative_workflow_runs_list until the most recent run reaches a terminal state.
Inspect job-level progress by calling narrative_jobs_search with workflow_run_id=<run-uuid>, then narrative_jobs_describe on the returned ids.
Describe the workflow with narrative_workflows_describe to inspect its specification or current status.

Connection creation flow

To route a dataset’s data to a destination connector from an AI assistant:

List installed connectors with narrative_installations_list and pick one whose categories include destination_connector.
Find an enabled profile with narrative_app_profiles_list on the installation id. Only enabled profiles can back a connection.
Check compatibility with narrative_dataset_get_compatible_interfaces for the target dataset. The accepted (app_id, interface_id) pairs are the ones a connection will succeed against.
Build quick_settings (optional) with narrative_app_interfaces_list on the accepted interface’s app to retrieve the interface’s quick-settings JSON Schema.
Create the connection with narrative_connection_create, passing dataset_id, the enabled profile_id, and any quick_settings.

Multi-company sessions

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.

Connecting to the Narrative MCP Server

Set up your MCP client

How the MCP server works

NQL Design Philosophy

Understand the query language behind NQL tools

Rosetta Stone

The schema normalization system behind attribute tools

​Overview

​Server URL

​Context tools

​narrative_context_get

​narrative_context_get_companies

​narrative_context_set_company

​narrative_context_search_companies

​Dataset tools

​narrative_datasets_search

​narrative_datasets_describe

​narrative_dataset_get_column_stats

​narrative_dataset_set_column_stats_config

​Dataset operation tools

​narrative_dataset_request_sample

​narrative_dataset_refresh_materialized_view

​narrative_dataset_recalculate_statistics

​narrative_dataset_update

​Attribute tools

​narrative_attributes_search

​narrative_attributes_describe

​narrative_attribute_create

​Access rule tools

​narrative_access_rules_search

​narrative_access_rules_describe

​Mapping tools

​narrative_mapping_create

​Connector tools

​narrative_installations_list

​narrative_app_profiles_list

​narrative_app_interfaces_list

​narrative_dataset_get_compatible_interfaces

​narrative_connection_create

​NQL tools

​narrative_nql_validate

​narrative_nql_execute

​Job tools

​narrative_jobs_describe

​narrative_jobs_search

​Data plane tools

​narrative_data_planes_list

​narrative_data_planes_describe

​Workflow tools

​narrative_workflows_create

​narrative_workflows_trigger

​narrative_workflows_describe

​narrative_workflow_runs_list

​Usage patterns

​Recommended NQL flow

​Dataset inspection flow

​Access rule discovery flow

​Workflow submission flow

​Connection creation flow

​Multi-company sessions

​Naming conventions

​Related content

Connecting to the Narrative MCP Server