Skip to main content

​
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

​
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). 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. 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.

​
narrative_context_search_companies

Searches companies by name using case-insensitive substring matching. Available to global administrators only. Returns { id, name } for each matching company.

​
Dataset tools

Dataset tools let you search, describe, and inspect datasets. 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. 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. Available include values: In the metadata section, default_compute_pool_id appears only when the dataset has its own default compute pool configured. Jobs against the dataset that don’t name a pool (such as sample requests) run on that pool, taking precedence over the company-level and data-plane-level defaults shown by the data plane tools. See compute pools for the full resolution chain. When mappings is in the include set, the section lists the dataset’s stored mappings plus the derived mappings they imply. A derived row has source: derived, no id (it is computed on the request from a stored mapping and a derivation rule, nothing is stored), and a provenance naming the source mapping, the derivation path, and whether the result is exact, lossy, or imprecise. Fetching without mappings (or from any other tool that reads a dataset) skips derivation and returns only stored rows.

​
narrative_dataset_get_column_stats

Returns per-column statistics for a single dataset. Available include values:

​
narrative_dataset_set_column_stats_config

Replaces the column-statistics configuration for a dataset. This is a write that overwrites whatever configuration was previously stored.
Omit a configuration slot entirely to inherit from the parent level. An explicit null is not the same thing, and the API rejects it where a value is required.

​
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

Triggers a workflow that samples a dataset and runs Narrative’s privacy model over those rows in a single run, so the sample redaction is written against the rows it is masking. Returns the workflow’s id and metadata plus a run_id. Poll the run with narrative_workflow_runs_list until it reaches a terminal state, then read the sample (already redacted) with narrative_datasets_describe using include=["sample"]. Pass redacted=false on that call to read the raw unredacted rows behind the mask.

​
narrative_dataset_refresh_materialized_view

Triggers a refresh of a materialized-view dataset. 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. 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. 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.

​
narrative_dataset_activate

Activates a Narrative dataset. Activation locks in the dataset’s schema and lets Narrative start ingesting data into it. Wraps PUT /datasets/:id/activate. New datasets start inactive with status pending, as does the cache dataset that narrative_mapping_create creates for a cached_mapping. Activation is a one-time step: the API rejects the call with an error if the dataset is already active, does not exist, or is not accessible to the current company. Use narrative_datasets_describe to inspect the dataset before or after activating it. Returns the dataset id and its new status.

​
Attribute tools

Attribute tools let you explore, inspect, and create Rosetta Stone attributes. Searches Rosetta Stone attributes by name. Available include values:

​
narrative_attributes_describe

Describes one or more attributes by id. Accepts multiple attribute ids in a single call. Uses the same include values as narrative_attributes_search. derivations is on by default here: the tool fetches each attribute’s derivation graph from GET /attributes/{id}/derivation-graph alongside the attribute itself. Reading derivation edges. Each edge renders on one line: derives <target> via <rule> means the attribute is upstream of the target, and derived from <source> via <rule> means the source is upstream. Each line also flags whether the rule is exact, lossy, or imprecise, plus any fidelity note. When the attribute has no edges, the section renders _none_. Both attribute tools tell connected AI assistants to map a dataset column to the attribute closest to the root of the derivation graph: the one with no derived from line that the column actually contains. A dataset mapped to the source attribute of a derivation rule automatically gets mappings to every derived attribute, whereas a mapping created directly to a descendant covers only that one attribute. Mapping directly to a derived attribute is right only when the dataset holds nothing but the derived form, such as hashed emails with no plain addresses.

​
narrative_attribute_create

Creates a new attribute owned by the currently selected company. Wraps POST /attributes. 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. 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. 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: 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. Available include values:

​
Mapping tools

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

​
narrative_mapping_create

Creates a 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. 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.
Before committing to a target attribute, check its derivation edges with narrative_attributes_describe and map to the attribute closest to the root of the derivation graph that the column actually contains. One mapping to the source attribute of a derivation rule covers every derived attribute automatically; a mapping created directly to a descendant covers only that one attribute. The tool’s description carries this same guidance for connected AI assistants.
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.

​
Derivation tools

Derivation tools let you list, describe, and (for Narrative global admins) create derivation rules — the transformations that compute one Rosetta Stone attribute from another. Use narrative_attributes_describe first to see which rules already touch an attribute; each edge names the rule and its id.

​
narrative_derivations_list

Lists the derivation rules the currently selected company can use — the ones it owns plus the ones shared with it. Wraps GET /derivations. The full list is returned in one call; the API does not page. Filters combine with AND. Omit both filters to list every usable rule.

​
narrative_derivations_describe

Describes one or more derivation rules by id, transformation included. Accepts multiple ids in a single call and fetches them in parallel. Wraps GET /derivations/{id}. Any id the current company cannot use is reported as not found. Available include values (shared by both read tools):

​
narrative_derivation_create

Creates a derivation rule owned by the currently selected company. Wraps POST /derivations.
This tool is only visible and callable for Narrative global admins. For every other session the tool is hidden from tools/list and tools/call reports it as an unknown tool. Non-admins who name it directly still receive a permission error.
The mapping argument accepts one of two 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 into the target attribute (e.g. value) and expression is an NQL expression over the source attribute read through $source (e.g. SHA2(LOWER($source.value), 256)). Provide a mapping for each of the target’s required properties.
  • value_mapping — for scalar targets. Supply type: "value_mapping" and a single expression producing the target’s value.
Before adding a rule, call narrative_attributes_describe on both attributes (derivations are on by default) and check that no existing rule already covers the same source and target pair — the API rejects duplicates with a conflict. Every expression is validated against the source attribute’s shape and the target’s declared type before the rule is written; failures come back as a descriptive error. A rule that closes a cycle in the derivation graph is still created, and the cycle is returned as a warning on the response.
Global admin status is carried by the caller’s user, not the token — an MCP token minted for a global admin can create rules without any explicit admin grant. See Derivation rules permissions.

​
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. 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. 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. Available include values:
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. Available include values: 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. 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.
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. 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. Available include values:
Reading job timings: created_at to dequeued_at is time spent queued, and dequeued_at to ended_at is execution (cluster launch plus the work itself). Do not report ended_at - created_at as the job’s runtime; it includes queue time. An attempt_version greater than 1 means the job was retried, and attempted_at is when the latest attempt started.
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. 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. Matches carry the same metadata fields as narrative_jobs_describe, and both tools carry the timing guidance above in their descriptions.

​
Model training tools

Model training tools let you train models on Narrative datasets. Training runs asynchronously as a job — the tool returns the job id, and the agent polls completion with narrative_jobs_describe.

​
narrative_classifier_train

Enqueues a classifier training run against a dataset. Submits to POST /v1/model-training/train-classifier. The dataset must be owned by the active company, active, and materialized on a Snowflake data plane; the trained model is saved to the Snowflake ML Registry in that data plane’s account. The API validates model_name, feature names, and every column reference against the dataset’s schema before enqueueing a job — bad references fail this tool call rather than the job. The model hyperparameters and each feature’s settings block are validated later by the training procedure inside the job, so a bad value there surfaces as a failed job that you read through narrative_jobs_describe. Feature types. Each feature_inputs entry picks one of: Classifiers. model.type picks the variant; every variant also accepts random_state: Returns the id of the enqueued job. Poll it with narrative_jobs_describe(job_ids=["..."]).
A successful classifier training job returns a large result payload (full metrics, per-class breakdowns, and the echoed config). Polling such a job through narrative_jobs_describe can return a lot of text.

​
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.

​
narrative_data_planes_describe

Describes one or more data planes by id. Accepts multiple ids in a single call and fetches them in parallel. Available include values (shared by both data plane tools): 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. The pool with a non-null default_source is where the company’s jobs run when they don’t name a pool themselves: company means the company set its own default for the data plane, data_plane means the default was set by the data plane’s owner. See reading the effective default for the full behavior.

​
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. 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.
Agents started by a workflow’s RunConversation task cannot call this tool — the platform refuses the call and returns a tool error the model can adapt to. This keeps a workflow from nesting another workflow through its own agent.

​
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.
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. Available include values:
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. To find the jobs spawned by a specific run, call narrative_jobs_search with workflow_run_id=<run-uuid>.

​
Usage patterns

The most effective pattern for running queries is validate → execute → poll:
  1. Validate the query with narrative_nql_validate to catch syntax errors before enqueuing a workflow.
  2. Execute the validated query with narrative_nql_execute to submit it. The tool returns the workflow id and run id.
  3. 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:
  1. Search with narrative_datasets_search to find datasets by name or description.
  2. Describe with narrative_datasets_describe using include=["metadata", "schema"] for an overview, or add "sample" and "stats" for deeper inspection.
  3. 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:
  1. Search with narrative_access_rules_search, providing at least one filter (e.g. search_term, exposed_attribute_names, tags, dataset_ids).
  2. 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.
  3. Reference in NQL using <owning_company_slug>.<access_rule_name>.

​
Workflow submission flow

To submit and track a workflow from an AI assistant:
  1. Discover available data planes with narrative_data_planes_list to pick a data_plane_id.
  2. 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.
  3. Poll runs with narrative_workflow_runs_list until the most recent run reaches a terminal state.
  4. Inspect job-level progress by calling narrative_jobs_search with workflow_run_id=<run-uuid>, then narrative_jobs_describe on the returned ids.
  5. 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:
  1. List installed connectors with narrative_installations_list and pick one whose categories include destination_connector.
  2. Find an enabled profile with narrative_app_profiles_list on the installation id. Only enabled profiles can back a connection.
  3. 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.
  4. Build quick_settings (optional) with narrative_app_interfaces_list on the accepted interface’s app to retrieve the interface’s quick-settings JSON Schema.
  5. 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:
  1. List your companies with narrative_context_get_companies.
  2. Switch with narrative_context_set_company to set the active company.
  3. 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