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.
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.
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.
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
company_ids
integer[]
No
Filter to rules owned by any of these companies
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
include
string[]
No
Sections to include per match (default: ["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
description
Rule description
mappings
Attributes the rule exposes
tags
Tags attached to the rule
dataset_ids
Datasets the rule references
pricing
Price in CPM USD
To reference a rule in NQL, use <owning_company_slug>.<access_rule_name>.
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.
Job tools let you discover and follow Narrative jobs — the asynchronous units of work spawned by narrative_nql_run, 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.
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)
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). Useful patterns: workflow_run_id=<run-uuid>, workflow_id=<workflow-uuid>
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
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")
Multiple filters compose with AND. Pass the returned ids to narrative_jobs_describe for full per-job detail.
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_run.
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.
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.
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.
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 tags=["workflow_run_id=<run-uuid>"].
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>.
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 tags=["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.
