> ## 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. # Data Collaboration MCP Server > Tool reference for the Narrative Model Context Protocol 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](/guides/mcp/connecting-an-ai-assistant). For background on how the server works, see [MCP Server for Agents](/concepts/mcp/overview). ## 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` | Generated NQL snippet to query the dataset | ### `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. ## Attribute tools Attribute tools let you explore and inspect [Rosetta Stone](/concepts/rosetta-stone/overview) 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`. ## Access rule tools Access rule tools let you discover and inspect [access rules](/concepts/primitives/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](/concepts/rosetta-stone/overview) 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 `.`. ### `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, 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 | ## NQL tools NQL tools let you validate, execute, and track [NQL](/concepts/nql/design-philosophy) 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_run` Submits an NQL query for asynchronous execution. Supports `SELECT` queries and `CREATE MATERIALIZED VIEW` statements. | Parameter | Type | Required | Description | | ----------------- | ------ | -------- | ------------------------------------------------------------------ | | `query` | 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 a job descriptor in `state: pending`. Poll it with `narrative_jobs_describe`. ## Job tools 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. ### `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). Useful patterns: `workflow_run_id=`, `workflow_id=` | | `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 Data plane tools let you discover the [data planes](/concepts/primitives/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`. ### `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 | | `platform` | Platform-specific configuration as JSON | ## Workflow tools Workflow tools let you submit, inspect, and track runs of [workflows](/concepts/workflows/workflow-orchestration). The workflow YAML is passed as a free-form string — see the [workflow task reference](/reference/workflows/tasks) 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 `tags=["workflow_run_id="]`. ## Usage patterns ### Recommended NQL flow The most effective pattern for running queries is **validate → run → poll**: 1. **Validate** the query with `narrative_nql_validate` to catch syntax errors before enqueuing a job. 2. **Run** the validated query with `narrative_nql_run` to submit it for execution. 3. **Poll** with `narrative_jobs_describe` 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: 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 `.`. ### 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 `tags=["workflow_run_id="]`, then `narrative_jobs_describe` on the returned ids. 5. **Describe** the workflow with `narrative_workflows_describe` to inspect its specification or current status. ### 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 Set up your MCP client How the MCP server works Understand the query language behind NQL tools The schema normalization system behind attribute tools