Connecting to the Narrative MCP Server - Narrative I/O Knowledge Base

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

Claude Code
Claude Desktop
Cursor
Windsurf
Other clients

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.

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, 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.

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

​Prerequisites

​Server URL

​Setup by client

​Authenticate

​OAuth (default for interactive clients)

​Narrative API token (for programmatic clients)

​Verify the connection

​Troubleshooting

​Browser window doesn’t open

​Tools not appearing

​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

Troubleshooting

Browser window doesn’t open

Tools not appearing

Session expired

What’s next