> ## 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.
# Connecting to the Narrative MCP Server
> Set up your MCP client to interact with Narrative through an AI agent
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:
```bash theme={null}
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:
```bash theme={null}
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.
1. Open **Settings** (gear icon, or `⌘,`).
2. In the left nav, select **Connectors**.
3. Scroll to the bottom and click **Add custom connector**.
4. Enter the following:
* **Name:** `Narrative`
* **Remote MCP server URL:** `https://mcp.narrative.io/mcp`
5. Click **Add**. A browser window opens for OAuth — sign in with your Narrative credentials.
6. 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.
1. Open **Settings** > **MCP**.
2. Click **+ Add new MCP server**.
3. Enter the following:
* **Name:** `narrative`
* **Type:** `http`
* **URL:** `https://mcp.narrative.io/mcp`
4. Click **Add** and confirm the server appears in the list.
Narrative tools are available in Cursor's Agent mode.
1. Open the **Command Palette** and search for **MCP Configuration**.
2. Add the Narrative server to your configuration:
```json theme={null}
{
"mcpServers": {
"narrative": {
"type": "http",
"url": "https://mcp.narrative.io/mcp"
}
}
}
```
3. 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:
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.
### Narrative API token (for programmatic clients)
If your MCP client supports a static bearer token, you can authenticate with a [Narrative API key](/account-settings/api-keys) instead of OAuth. Set the `Authorization` header on every MCP request:
```http theme={null}
Authorization: Bearer
```
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
Understand how the MCP server works and what it enables
Browse the complete catalog of available tools
Learn NQL basics to get more from query tools
Configure column statistics that the MCP server can read and trigger