Connecting to the Narrative MCP Server

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.

Claude Desktop connects to remote MCP servers through its built-in Connectors UI. The claude_desktop_config.json file only supports stdio-based servers, so don’t add Narrative there.

Open Settings (gear icon, or ⌘,).
In the left nav, select Connectors.
Scroll to the bottom and click Add custom connector.
Enter the following:
- Name: Narrative
- Remote MCP server URL: https://mcp.narrative.io/mcp
Click Add. A browser window opens for OAuth — sign in with your Narrative credentials.
Return to Claude Desktop. The connector should show Connected.

The Narrative tools appear in the tools menu (hammer icon) at the bottom of the chat input.

If you don’t see Add custom connector, update Claude Desktop — native remote MCP support requires a recent version.

Open Settings > MCP.
Click + Add new MCP server.
Enter the following:
- Name: narrative
- Type: http
- URL: https://mcp.narrative.io/mcp
Click Add and confirm the server appears in the list.

Narrative tools are available in Cursor’s Agent mode.

Run the following command in your terminal:

cortex mcp add -t http narrative https://mcp.narrative.io/mcp

-t http is required. The flag defaults to stdio, and a server registered as stdio is launched as a subprocess, so it never reaches the hosted URL.The first Narrative tool call opens a browser window for OAuth login.

Open the Command Palette and search for MCP Configuration.
Add the Narrative server to your configuration:

{
  "mcpServers": {
    "narrative": {
      "type": "http",
      "url": "https://mcp.narrative.io/mcp"
    }
  }
}

Save and restart Windsurf.

Any MCP-compatible client that supports HTTP transport can connect using:

Transport: HTTP (Streamable HTTP)
URL: https://mcp.narrative.io/mcp

Refer to your client’s documentation for how to add a remote MCP server.

Authenticate

The MCP server accepts two kinds of bearer credential in the Authorization header:

OAuth login (interactive clients). A standard OAuth flow exchanges your Narrative login for a scoped session token. This is what Claude Code, Claude Desktop, Cursor, Cortex Code, and Windsurf use by default.
Narrative API token (programmatic clients). Long-lived API tokens are accepted directly, which lets server-to-server callers and scripted MCP clients connect without a browser-based login.

The server distinguishes the two by token shape — JWTs (three dot-separated segments) follow the OAuth path, and opaque tokens are treated as Narrative API tokens.

OAuth (default for interactive clients)

The first time your assistant calls a Narrative tool, the MCP server initiates an OAuth login:

A browser window opens with the Narrative login page.
Sign in with your Narrative credentials.
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.

Narrative API token (for programmatic clients)

If your MCP client supports a static bearer token, you can authenticate with a Narrative API key instead of OAuth. Set the Authorization header on every MCP request:

Authorization: Bearer <your-narrative-api-token>

The server validates the token, resolves the associated user and default company, and reuses the same token for downstream Narrative API calls. The token’s existing permissions and company access apply.

Use API token auth for headless workloads — CI jobs, agent orchestrators, and other server-to-server callers that can’t complete an interactive OAuth flow.

An OAuth session requires you to select a company before any tool other than the context tools will run. A session authenticated with an API token is locked to that token’s company and skips the step.

Verify the connection

Ask your assistant something like:

“Who am I logged in as on Narrative?”

The assistant should call narrative_context_get, which answers with your account, your role, and the company selection:

User: [email protected] (id: 1248)
Role: partner_user
Active company: none set. Call narrative_context_set_company to choose a company.

narrative_context_get reads only the session — it takes no arguments and makes no downstream API calls, so it returns immediately and behaves the same for every role. That makes it the cheapest available proof that the transport, your credential, and your client’s tool loop are all working.

Active company: none set is the expected reply on a fresh OAuth session, including when you belong to exactly one company. Selecting a company is the next step.

Select a company

Every tool except the four context tools — narrative_context_get, narrative_context_get_companies, narrative_context_search_companies, and narrative_context_set_company — requires an explicitly selected company. Until you choose one, the rest fail with:

No company selected. Call narrative_context_get_companies to see available companies, then call narrative_context_set_company to choose one.

Ask your assistant to make the choice:

“Switch to Acme Corp on Narrative.”

The assistant calls narrative_context_set_company, and every subsequent tool call in the session operates against that company until you change it.

An OAuth session never pre-selects a company, even for a user who belongs to only one — the choice is always explicit. An API-token session is locked to the token’s company when it connects, so it skips this step.

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.

”No company selected”

Every tool except the four context tools needs a company chosen for the session. See Select a company. This is expected on a new OAuth session and is not a connection fault.

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

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

Server URL

Setup by client

Authenticate

OAuth (default for interactive clients)

Narrative API token (for programmatic clients)

Verify the connection

Select a company

Troubleshooting

Browser window doesn’t open

Tools not appearing

”No company selected”

Session expired

What’s next

Data Collaboration MCP Server

Tool Reference

NQL Guide

Dataset Statistics

​Prerequisites

​Server URL

​Setup by client

​Authenticate

​OAuth (default for interactive clients)

​Narrative API token (for programmatic clients)

​Verify the connection

​Select a company

​Troubleshooting

​Browser window doesn’t open

​Tools not appearing

​”No company selected”

​Session expired

​What’s next

Data Collaboration MCP Server

Tool Reference

NQL Guide

Dataset Statistics

Prerequisites

Server URL

Setup by client

Authenticate

OAuth (default for interactive clients)

Narrative API token (for programmatic clients)

Verify the connection

Select a company

Troubleshooting

Browser window doesn’t open

Tools not appearing

”No company selected”

Session expired

What’s next