What is MCP?
MCP is an open protocol that standardizes how AI applications connect to external tools and data sources. It defines a universal interface so that any MCP-compatible AI client — Claude Code, Claude Desktop, Cursor, Windsurf, and others — can discover and call tools exposed by an MCP server. The protocol handles:- Tool discovery. The client asks the server what tools are available and receives their names, descriptions, and parameter schemas.
- Authentication. OAuth-based flows let the server verify your identity without you sharing API keys with the AI client.
- Tool execution. The client calls a tool on your behalf, and the server returns structured results that the AI can reason about.
Why use an AI assistant with Narrative?
Working with data collaboration platforms often involves switching between multiple screens — searching for datasets, inspecting schemas, writing queries, monitoring jobs. An AI assistant connected via MCP can compress these multi-step workflows into a conversational loop:- Explore datasets naturally. Ask “what datasets do I have about mobile identifiers?” instead of navigating through the UI. The assistant searches, describes schemas, and summarizes what it finds.
- Write and validate NQL iteratively. Describe what you want in plain language, and the assistant drafts NQL, validates it against your schema, and fixes errors before submitting — all without you writing a query from scratch.
- Operate on datasets without context-switching. Trigger samples, refresh materialized views, and recalculate statistics through conversation. The assistant polls job status and reports when operations complete.
- Work across companies. If you belong to multiple companies, the assistant can switch context on your behalf, making cross-tenant operations seamless.
How it works
The Narrative MCP server sits between your AI client and the Narrative API:- You connect once. Add the server URL to your AI client’s MCP configuration. The first time the assistant calls a tool, a browser window opens for you to log in with your Narrative credentials.
- The assistant discovers tools. On connection, the client fetches the list of available tools — dataset operations, NQL execution, attribute search, and more.
- Tools call the Narrative API. When the assistant uses a tool, the MCP server translates the request into the appropriate Narrative API calls, using your authenticated session.
- Results flow back as context. The server returns structured responses that the assistant incorporates into the conversation, so it can chain operations (e.g., describe a dataset, then write a query against it).
- OAuth login — Interactive MCP clients (Claude Code, Claude Desktop, Cursor, Windsurf) open a browser-based login, and the server exchanges the resulting credential for a scoped Narrative access token. Your session persists across tool calls, so you only log in once per session.
- Narrative API token — Server-to-server callers and scripted clients can send a long-lived Narrative API token directly in the
Authorization: Bearerheader, skipping the browser flow. The token’s existing user, company, and permission scope apply. See Connecting to the Narrative MCP Server for setup details.
Available tools
The server organizes its tools into these categories:| Category | What you can do |
|---|---|
| Context | Inspect the current session, list your companies, switch the active company, search companies by name |
| Datasets | Search and describe datasets, inspect column statistics, configure stats collection |
| Dataset operations | Request samples, refresh materialized views, recalculate statistics |
| Attributes | Search and describe Rosetta Stone attributes |
| Access rules | Discover and inspect the access rules your company owns or has been granted |
| NQL | Validate queries and submit them for execution |
| Jobs | Search and describe jobs to track asynchronous work — NQL runs, samples, materialized-view refreshes |
| Data planes | Discover available data planes and their compute pools |
| Workflows | Create, trigger, describe, and follow runs of multi-step workflows |
Other Narrative MCP servers
Narrative publishes a small suite of MCP servers alongside the Data Collaboration server. You can add any of them to your client independently:| Server | URL | Auth | What it does |
|---|---|---|---|
| Data Collaboration | https://mcp.narrative.io/mcp | OAuth | Query datasets, run NQL, manage workflows |
| Knowledge Base | https://docs.narrative.io/mcp | None | Search the Narrative docs and answer questions with citations |
| Agent Feedback | https://narrative.support/mcp | None | Submit structured product feedback and bug reports from a session |
Getting started
To connect your AI assistant to Narrative, follow the setup guide for your client:Connecting to the Narrative MCP Server
Step-by-step setup for Claude Code, Claude Desktop, Cursor, and other MCP clients
Tool Reference
Complete catalog of available tools with parameters and usage patterns