> ## Documentation Index
> Fetch the complete documentation index at: https://docs.navattic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect AI coding agents to your Navattic workspace using the Model Context Protocol.

The Navattic MCP server gives AI coding agents (such as Claude Desktop, Cursor, VS Code Copilot, Windsurf, ChatGPT, and Codex) structured access to your workspace. Agents can read analytics, browse and build demos, manage Launchpad share links, and query personalization data, all scoped to your workspace.

<Frame>
  <img src="https://mintcdn.com/navattic-app/qyCBIgYm7Ylt8Sto/images/product_updates_may_2.png?fit=max&auto=format&n=qyCBIgYm7Ylt8Sto&q=85&s=ae9b69b1e56534e5350d91152ee17361" alt="Navattic MCP server connected to an AI coding agent" width="2400" height="1252" data-path="images/product_updates_may_2.png" />
</Frame>

<Note>The MCP server is available on the Startup plan and above.</Note>

## How it works

The Navattic MCP server supports two authentication methods depending on your AI client:

* **OAuth** (Claude Desktop, Claude Code, ChatGPT, Gemini Enterprise): sign in to Navattic when prompted. No Personal Access Token required.
* **Bearer token** (Cursor, VS Code, Windsurf, Codex, IBM Bob, Microsoft Copilot Studio): create a Personal Access Token. Add it to your client's config file.

All operations are scoped to your workspace. Agents cannot access data from other workspaces, even with a valid resource ID from another workspace.

<Tip>
  Go to **Settings** > **AI** > **MCP** in your workspace to find your MCP server URL and the full
  setup guide for every client in one place.
</Tip>

## Step 1: Create a Personal Access Token (bearer token clients only)

If you're using Cursor, VS Code, Windsurf, Codex, IBM Bob, or Microsoft Copilot Studio, you need a Personal Access Token. Skip this step if you're using Claude Desktop, Claude Code, ChatGPT, or Gemini Enterprise.

<Note>
  Only workspace **Admins** can create Personal Access Tokens. Builders can view existing tokens in
  **Settings** > **Workspace** > **Access Tokens** but cannot create or revoke them. Each workspace
  supports up to 25 active tokens per user.
</Note>

<Steps>
  <Step title="Go to MCP settings">
    Navigate to **Settings** > **AI** > **MCP** in your Navattic workspace.
  </Step>

  <Step title="Create a new token">
    Click **Manage personal access tokens**, then click **Create token**. Enter a name for the token (for example, "Cursor agent").
  </Step>

  <Step title="Select scopes">
    Choose the scopes your agent needs. Each scope grants access to a specific set of tools:

    | Scope                    | What it allows                                                                                   | Required role                               |
    | ------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------- |
    | **Analytics**            | View demo performance, visitor data, and account engagement                                      | Viewer or above                             |
    | **Demo Browsing**        | Browse demos, flows, and share links                                                             | Viewer or above                             |
    | **Demo Building**        | Create flows; edit steps, buttons, navigation, beacons, media, voiceover, and presenter settings | Builder or above                            |
    | **Demo Management**      | Rename and organize demos; create share links and labels                                         | Builder or above                            |
    | **Demo Publishing**      | Publish and archive demos                                                                        | Builder or above                            |
    | **Personalization**      | View custom properties and visitor activity                                                      | Viewer or above                             |
    | **Navattic Agents**      | View and update Navattic Agents and session data; read stages, topics, and conversation history  | Builder or above                            |
    | **Agent Environments**   | View and update Navattic Agent environments, flows, and step descriptions                        | Builder or above                            |
    | **Workspace Management** | Create labels and boards to organize your workspace                                              | Builder or above                            |
    | **Launchpad**            | Browse and manage Launchpad share links, interest flows, and recipient visitor data              | Viewer or above (Launchpad workspaces only) |

    <Note>
      The **Navattic Agents** and **Agent Environments** scopes only appear in workspaces with Navattic Agents enabled. The **Launchpad** scope is only available in workspaces with Launchpad enabled and is only shown to users with the Launchpad app role.
    </Note>

    <Tip>
      Start with Analytics and Demo Browsing. These cover read-only operations. Add write scopes only if your agent needs to create or modify demos.
    </Tip>
  </Step>

  <Step title="Set an expiration">
    Choose a token lifetime: 7, 30, 60, 90, or 180 days. Tokens expire automatically; you'll need to create a new token when one expires.
  </Step>

  <Step title="Copy the token">
    After creating the token, copy it immediately. You won't be able to see it again.

    <Warning>
      Store your token securely. Anyone with the token can access your workspace within the granted scopes.
    </Warning>
  </Step>
</Steps>

## Step 2: Configure your MCP client

Connect your AI agent using the Navattic MCP server URL:

```
https://app.navattic.com/api/mcp
```

You can copy this URL from **Settings** > **AI** > **MCP** in your workspace. Use the instructions below for your client:

<Tabs>
  <Tab title="ChatGPT">
    ChatGPT uses OAuth, so no Personal Access Token is needed.

    <Steps>
      <Step title="Open ChatGPT settings">
        Open ChatGPT on the web → your profile → **Settings** → **Connectors**.
      </Step>

      <Step title="Enable developer mode">
        Open **Advanced** and enable **Developer mode**.
      </Step>

      <Step title="Create a connector">
        Go to **Connectors** → **Create**.
      </Step>

      <Step title="Add the Navattic MCP URL">
        Enter a name, choose **OAuth**, and paste the Navattic MCP URL: `https://app.navattic.com/api/mcp`.
      </Step>

      <Step title="Authorize">
        Click **Create**, then sign in to Navattic when prompted.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop uses OAuth, so no Personal Access Token is needed.

    <Steps>
      <Step title="Open Claude Desktop settings">
        In Claude Desktop, go to **Settings** → **Connectors**.
      </Step>

      <Step title="Add a custom connector">
        Click **+ Add custom connector**.
      </Step>

      <Step title="Enter the Navattic MCP URL">
        Paste `https://app.navattic.com/api/mcp` and click **Add**.
      </Step>

      <Step title="Authorize the connection">
        Claude Desktop will open a Navattic authorization page. Sign in and grant access.
      </Step>
    </Steps>

    <Accordion title="Alternative: edit the config file manually">
      If you prefer to configure Claude Desktop by editing the config file directly, add the following to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

      ```json theme={null}
      {
        "mcpServers": {
          "navattic": {
            "url": "https://app.navattic.com/api/mcp",
            "headers": {
              "Authorization": "Bearer YOUR_TOKEN"
            }
          }
        }
      }
      ```

      Replace `YOUR_TOKEN` with the Personal Access Token you created in Step 1. Restart Claude Desktop after saving.
    </Accordion>
  </Tab>

  <Tab title="Claude Code">
    Claude Code uses OAuth. Run this command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http navattic https://app.navattic.com/api/mcp
    ```

    Then run `/mcp` in your Claude Code session and select **navattic** to authenticate.

    <Accordion title="Alternative: add to settings.json manually">
      Add to `~/.claude/settings.json`:

      ```json theme={null}
      {
        "mcpServers": {
          "navattic": {
            "type": "url",
            "url": "https://app.navattic.com/api/mcp",
            "headers": {
              "Authorization": "Bearer YOUR_TOKEN"
            }
          }
        }
      }
      ```

      Replace `YOUR_TOKEN` with the Personal Access Token you created in Step 1.
    </Accordion>
  </Tab>

  <Tab title="Codex">
    Add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.navattic]
    url = "https://app.navattic.com/api/mcp"
    bearer_token_env_var = "NAVATTIC_TOKEN"
    ```

    Then set the environment variable in your shell (or add it to your shell profile):

    ```bash theme={null}
    export NAVATTIC_TOKEN=your_token_here
    ```

    Replace `your_token_here` with the Personal Access Token you created in Step 1.
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "navattic": {
          "url": "https://app.navattic.com/api/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
          }
        }
      }
    }
    ```

    Replace `YOUR_TOKEN` with the Personal Access Token you created in Step 1.
  </Tab>

  <Tab title="VS Code">
    Add to your VS Code settings (the `mcp` section):

    ```json theme={null}
    {
      "servers": {
        "navattic": {
          "type": "http",
          "url": "https://app.navattic.com/api/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
          }
        }
      }
    }
    ```

    Replace `YOUR_TOKEN` with the Personal Access Token you created in Step 1.
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "navattic": {
          "serverUrl": "https://app.navattic.com/api/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
          }
        }
      }
    }
    ```

    Replace `YOUR_TOKEN` with the Personal Access Token you created in Step 1.
  </Tab>

  <Tab title="IBM Bob">
    Add to `~/.bob/mcp.json` for a global config, or `.bob/mcp.json` in your project root for a project-specific config:

    ```json theme={null}
    {
      "mcpServers": {
        "navattic": {
          "url": "https://app.navattic.com/api/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
          }
        }
      }
    }
    ```

    Replace `YOUR_TOKEN` with the Personal Access Token you created in Step 1. You can configure MCP from the **Bob settings menu** under the **MCP** tab.
  </Tab>

  <Tab title="Gemini (Enterprise)">
    Gemini for Google Workspace Enterprise uses OAuth, so no Personal Access Token is needed. Setup requires admin access to your Google Workspace account.

    <Steps>
      <Step title="Open Gemini Enterprise settings">
        In the Google Cloud Console, navigate to **Gemini Enterprise** → **Data stores**.
      </Step>

      <Step title="Create a data store">
        Click **Create data store**, then search for **Custom MCP Server** and select it.
      </Step>

      <Step title="Add the Navattic MCP URL">
        Enter a name for the connection and paste the Navattic MCP URL: `https://app.navattic.com/api/mcp`. Set the transport to **StreamableHTTP**.
      </Step>

      <Step title="Configure authentication">
        Under **Authentication settings**, select **OAuth 2.0** and complete the authorization flow to connect your Navattic account.
      </Step>
    </Steps>

    <Note>
      Gemini Enterprise MCP integration requires a Google Workspace Enterprise plan with Gemini Enterprise add-on. Contact your Google Workspace admin if you do not have access.
    </Note>
  </Tab>

  <Tab title="Microsoft Copilot Studio">
    Microsoft Copilot Studio supports connecting to MCP servers via its onboarding wizard.

    <Steps>
      <Step title="Open Copilot Studio">
        In Microsoft Copilot Studio, open your agent and navigate to **Actions** → **Add an action** → **Connect an MCP server**.
      </Step>

      <Step title="Fill in server details">
        Enter a name (for example, "Navattic") and the Navattic MCP URL: `https://app.navattic.com/api/mcp`.
      </Step>

      <Step title="Add your token">
        In the **API key** field, enter your Personal Access Token.

        <Warning>
          Enter only the raw token value. Do not include `Bearer` or any other prefix. Copilot Studio automatically sends the request as `Authorization: Bearer <your-token>`. Including the prefix yourself will cause authentication to fail.
        </Warning>
      </Step>

      <Step title="Save and test">
        Click **Save**. The Navattic tools will appear in your agent's action list.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## What you can do

Once connected, your agent can perform actions based on the scopes granted to its Personal Access Token. The available capabilities depend on which scopes you selected when creating your token.

**Analytics**

View demo engagement metrics and visitor data. Ask your agent to surface views, session counts, and click-through rates across all active demos. It can also drill into individual visitors and company accounts, including session history, demos viewed, and firmographic details. Filter by demo, company, location, industry, employee count, and custom properties.

**Demo browsing**

Search and read your workspace library. Your agent can list all demos, find demos by name or keyword, and read flow step content. It can list a demo's share links with their public URLs and check whether a demo has unpublished draft changes. It can also read the workspace's product knowledge base and browse the captures available to anchor new or edited steps, including identifying which captures have editable web content.

**Demo building**

Create new flows in an existing project and edit existing flows. Agents can edit all aspects of a flow's content:

* **Steps**: Add, remove, move, or update steps; change tooltip text, overlay style, and progress indicator behavior.
* **Buttons**: Change button labels, URLs, and click actions.
* **Navigation and exit views**: Update navigation behavior between steps and configure what viewers see at the end of a demo.
* **Beacons and triggers**: Add or update hotspot beacons and the click triggers that advance viewers through the flow.
* **Media and voiceover**: Swap out capture images or videos, and add or remove voiceover audio.
* **Presenter settings**: Update presenter notes and presenter mode configuration.

Edits are validated and applied atomically: if any action fails, nothing is saved.

You can also copy captures from one demo into another, and duplicate existing flows for reuse across demos.

**Demo management**

Create new demos, rename demos, create share links, and create labels and boards to organize your workspace. When creating a new demo in a workspace that uses boards, the agent first checks workspace settings and prompts you to select a board before proceeding.

**Demo publishing**

Publish demos, archive demos, and restore archived demos. Publishing makes any draft changes immediately visible to all visitors on the demo's share links and embeds. Archiving takes the demo offline: its share links and embeds stop resolving until it is restored. Restoring an archived demo brings it back to active status. Restore fails if the workspace is already at its demo limit. Some workspaces restrict publishing to the demo's creator or admins.

**Personalization**

List custom properties set up for visitor personalization.

**Navattic Agents** (Navattic Agents workspaces only)

View your Navattic Agents and session data. Your agent can list agents, retrieve agent details, and browse stages and topics. It can search and retrieve individual session records, summarize sessions by sentiment or outcome, and update conversation settings or qualification configuration on an existing agent.

Edits apply to the agent's draft. Publishing an agent is only possible from the Navattic app. There is no publish tool available through MCP.

<Note>
  Session filters in the session search tool (sentiment, outcome, duration, turn count, flag) apply
  to the page selected by `take`, not the entire workspace. A narrow filter over a workspace with
  many sessions needs a larger `take` value to avoid silently under-reporting results.
</Note>

**Agent Environments** (Navattic Agents workspaces only)

View and update Navattic Agent environments. Your agent can list environments and retrieve environment details. It can list and retrieve individual flows within an environment, search flows by name or content, and update step descriptions.

There is no create or delete for agents or environments through MCP, only updates to existing records.

**Launchpad** (Launchpad workspaces only)

Browse, create, and look up 1-1 Launchpad share links with recipient and engagement data. Search interest flows by name or description.

Your agent also has access to three workspace resources regardless of scopes:

* **Workspace overview**: current demo count, member count, and plan type
* **Navattic concepts**: a reference guide to the Navattic data model (demos, flows, steps, share links)
* **Flow editing guide**: explains the read→edit loop, step and button locators, the entity\_tag concurrency token, and how index positions shift after structural changes

<Note>
  When asking your agent to edit a flow, have it read the current flow document first to get the
  step structure and a version token. Pass that version token when requesting edits. If the flow has
  been changed since the read, the edit is rejected to prevent conflicts. After any structural
  change (inserting, moving, or removing a step), step indices shift; re-read the flow before
  sending the next batch. All edits in a batch apply atomically. If any action fails, nothing is
  saved.
</Note>

## Suggested prompts

Copy any of these prompts into your AI agent to get started. Replace the placeholder text in brackets with your own values.

**Analytics**

* "Which of our demos has the highest engagement rate over the past 30 days?"
* "List the top 10 visitors by total time spent across all demos this month."
* "Show me all visitors from \[company name] who have viewed our demos."
* "Which companies in the \[industry] sector have engaged with our demos recently?"
* "How many unique visitors did \[demo name] get last week, and what was the average session duration?"

**Demo library**

* "List all demos in the workspace and show how many flows each one has."
* "Find all demos related to \[product area or keyword]."
* "List all share links for \[demo name] and show their public URLs."
* "Does \[demo name] have any unpublished changes?"
* "Publish \[demo name] so the latest changes go live."
* "List all archived demos in the workspace."
* "Restore the archived demo \[demo name] so its links are live again."

**Demo editing**

* "Read the flow document for \[flow name] in \[demo name] and summarize what each step says."
* "Update step 3 of \[flow name] in \[demo name] to say: \[new text]."
* "Add a new step after step 5 in \[flow name] with the title \[title] and body text \[body]."
* "Rename the demo \[current name] to \[new name]."
* "Create a new demo called \[name]."
* "Duplicate the flow \[flow name] in \[demo name]."
* "Copy the captures from \[source demo name] into \[target demo name] so I can reuse them."

**Launchpad share links**

* "Create a Launchpad share link for \[first name] \[last name] at \[company] using the \[interest flow name] interest flow."
* "List all Launchpad share links created this week and show which recipients have viewed their demos."
* "Find the Launchpad share link for \[recipient name] and show me their engagement details."

**Personalization**

* "List all custom properties configured in the workspace."

## Use cases

<AccordionGroup>
  <Accordion title="Analyze demo performance in your coding environment">
    Ask your AI agent questions about demo engagement and visitor behavior. For example: "Which of
    our demos got the most engagement last quarter?", "Who from Acme Corp has viewed our demos
    recently?", or "What companies are showing the most interest this month?" The agent uses the
    analytics tools to query your workspace data and present results directly in your editor.
  </Accordion>

  <Accordion title="Build demos programmatically">
    Use your agent to create new demos and flows, duplicate existing flows, or copy captures between
    demos. Describe the steps you want in natural language and let the agent structure and create
    them for you. This is useful when building many similar demos, scaling a template across
    multiple demos, or automating demo creation as part of a deployment workflow.
  </Accordion>

  <Accordion title="Browse your demo library">
    Ask the agent to list all demos and find specific demos by name or description. The agent has
    access to your full workspace library, including flow structure and share links.
  </Accordion>

  <Accordion title="Automate demo maintenance">
    Use the agent to rename, archive, or restore demos as part of a release workflow. For example,
    archive old version demos when a new version is deployed, or restore a demo that was
    temporarily taken offline. The restore tool returns an error if the workspace is at its demo
    limit, so the agent can surface that constraint before you act.
  </Accordion>

  <Accordion title="Manage Launchpad share links and track engagement (Launchpad)">
    Use the Launchpad capabilities to automate 1-1 share link creation and track which recipients
    have visited their demos. For example, ask the agent: "List all share links sent to prospects
    this week and show which ones have been viewed." You can also ask the agent to find the right
    interest flow for a prospect before generating a personalized link.
  </Accordion>

  <Accordion title="Edit a demo using AI">
    Use the Demo Building scope to read and update steps in an existing flow. The agent first reads
    the current flow to understand the step structure, then applies a batch of ordered edits:
    updating text, buttons, beacons, voiceover, and more. All edits in the batch apply atomically,
    so a partial failure leaves the flow unchanged. After any structural change (inserting, moving,
    or removing a step), the agent re-reads the flow because step indices shift. This approach makes
    it straightforward to apply consistent changes across many steps or flows at once.
  </Accordion>
</AccordionGroup>

## Managing tokens

You can view all active tokens from **Settings** > **Workspace** > **Access Tokens**. From there you can:

* See each token's name, scopes, creation date, and expiration
* Revoke a token at any time; revocation takes effect immediately

When a token expires or is revoked, any agent using it will receive authentication errors until you update its configuration with a new token.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I create multiple tokens for different agents?">
    Yes. Create a separate token for each agent or environment, and name them to make revocation
    easier. For example, "Cursor - local dev" or "VS Code - production".
  </Accordion>

  <Accordion title="Is there a limit to how many tokens I can have?">
    Yes. Each user can have up to 25 active (non-expired, non-revoked) tokens per workspace. If you
    reach the limit, revoke unused tokens from **Settings** > **Workspace** > **Access Tokens**
    before creating new ones.
  </Accordion>

  <Accordion title="What happens if my token is compromised?">
    Revoke the token immediately from **Settings** > **Workspace** > **Access Tokens**. Then create
    a new token and update your agent configuration. The revoked token stops working as soon as you
    revoke it.
  </Accordion>

  <Accordion title="Who can create Personal Access Tokens?">
    Only workspace Admins can create Personal Access Tokens. Builders have view-only access to the
    tokens list and cannot create or revoke tokens. Viewer and Launchpad Rep roles cannot access the
    tokens settings at all.
  </Accordion>

  <Accordion title="Can a Viewer-role user create a token with write scopes?">
    No. The scope picker automatically disables write scopes (Demo Building, Demo Management, Demo
    Publishing) for users with Viewer-only roles.
  </Accordion>

  <Accordion title="Does the agent see all my workspace data?">
    The agent can only access data within the scopes you selected when creating the token. All data
    is also restricted to your workspace. The agent cannot access data from other workspaces.
  </Accordion>

  <Accordion title="Why don't I see the Launchpad scope when creating a token?">
    The Launchpad scope is only available to workspaces with Launchpad enabled and only shown to
    users with the Launchpad app role. If you don't see it, confirm your workspace has Launchpad and
    that your account has the Launchpad role. Contact your workspace admin if you need access.
  </Accordion>

  <Accordion title="Do I need a Personal Access Token for Claude Desktop or Claude Code?">
    No. Claude Desktop, Claude Code, ChatGPT, and Gemini Enterprise authenticate via OAuth. You
    simply sign in to Navattic when prompted. Personal Access Tokens are only needed for Cursor, VS
    Code, Windsurf, Codex, IBM Bob, and Microsoft Copilot Studio.
  </Accordion>
</AccordionGroup>