Skip to main content

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.

This guide walks you through connecting an MCP-compatible AI assistant to the Narrative platform. Once connected, your assistant can search datasets, run NQL queries, manage materialized views, and more — all from within your conversation.

​
Prerequisites

  • A Narrative account with access to at least one company
  • An MCP-compatible AI client installed (see supported clients below)

​
Server URL

All clients connect to the same endpoint: 
https://mcp.narrative.io/mcp

​
Setup by client

Run the following command in your terminal:
claude mcp add --transport http narrative https://mcp.narrative.io/mcp
This registers the Narrative MCP server in your Claude Code configuration. The next time Claude calls a Narrative tool, a browser window opens for you to authenticate.To verify the server is registered:
claude mcp list
You should see narrative in the output with the server URL.

​
Authenticate

The first time your assistant calls a Narrative tool, the MCP server initiates an OAuth login:
  1. A browser window opens with the Narrative login page.
  2. Sign in with your Narrative credentials.
  3. Return to your AI client — the session is now authenticated.
Your session persists across tool calls. You only need to log in once per session.
If you belong to multiple companies, the server defaults to your primary company. Ask the assistant to switch companies during the conversation — for example, “switch to Acme Corp” — and it will use the narrative_context_set_company tool.

​
Verify the connection

After setup, test the connection by asking your assistant something like:
“What companies do I have access to on Narrative?”
The assistant should call narrative_context_get_companies and return a list of your companies. If you see results, the connection is working.

​
Troubleshooting

​
Browser window doesn’t open

Some terminal environments block browser launches. If the OAuth login window doesn’t appear:
  • Check that your default browser is configured correctly.
  • Try opening the server URL directly in a browser to confirm network access: https://mcp.narrative.io/mcp

​
Tools not appearing

If your AI client doesn’t show Narrative tools:
  • Verify the server URL is exactly https://mcp.narrative.io/mcp (no trailing slash).
  • Restart your AI client after adding the server configuration.
  • Check your client’s MCP logs for connection errors.

​
Session expired

If tool calls start failing with authentication errors, your session may have expired. Ask the assistant to retry — the server will prompt you to log in again.

​
What’s next

Data Collaboration MCP Server

Understand how the MCP server works and what it enables

Tool Reference

Browse the complete catalog of available tools

NQL Guide

Learn NQL basics to get more from query tools

Dataset Statistics

Configure column statistics that the MCP server can read and trigger