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

# MCP Endpoint

> Expose nao as an MCP server so external AI clients can query your data

nao can act as an MCP (Model Context Protocol) server, letting external AI clients (Claude, Cursor, Codex, and others) connect directly to your analytics agent.

Once enabled, those clients can ask analytics questions, run SQL, browse your context files, and manage stories, all without leaving their own chat interface.

<div style={{ maxWidth: '1400px', margin: '1.5rem auto 0' }}>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/AyG2XqnOQDI?modestbranding=1&rel=0&iv_load_policy=3&showinfo=0" title="nao MCP Demo" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</div>

<Info>
  Enable and configure the MCP endpoint from **Settings** -> **MCP Endpoint**. For step-by-step client setup, see [Configure nao MCP endpoint](/nao-agent/chat/admin/setup#configure-nao-mcp-endpoint) in the admin guide.
</Info>

## Modes

Two modes control which capabilities are exposed. Enable either or both, depending on how much of the workflow you want the external client to drive.

| Mode                   | What it exposes                                                                                                                                                                                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sub-agent mode**     | `ask_nao`: sends a question to the nao agent, which runs the full agentic loop and streams the answer back. The reasoning trace is saved as a chat visible in the nao UI. Use this when you want the external client to delegate analytics questions to nao.                                       |
| **Context-layer mode** | `ls_nao_context`, `grep_nao_context`, `read_nao_context`, `execute_sql`, `create_story`, `update_story`: lets the external client browse your context files, run queries, and build stories step by step. Use this for tighter integration where the external client drives the tool calls itself. |

You can enable either mode or both.

### Story and chart tools

Whenever **either** mode is enabled, a shared set of story and chart tools is also exposed: `display_chart`, `list_stories`, `get_story`, `archive_story`, and `delete_story`. These let a connected client render charts and manage existing nao stories regardless of which mode drives the workflow.

## Authentication

nao uses Bearer token authentication. Your token is shown on the **MCP Endpoint** settings page. Include it in requests:

```
Authorization: Bearer <your-token>
```

Keep this token secret. Rotate it from the settings page if it is compromised.

## Available tools

The tools available to a connected client depend on the modes you have enabled.

<AccordionGroup>
  <Accordion title="ask_nao" icon="robot">
    Sends a natural language question to the nao agent and streams the response.

    * Requires **Sub-agent mode**.
    * Streams progress as the agent reasons and calls tools.
    * Returns the final answer including any charts or SQL outputs.
  </Accordion>

  <Accordion title="execute_sql" icon="database">
    Runs a SQL query against your connected data warehouse and returns results.

    * Requires **Context-layer mode**.
  </Accordion>

  <Accordion title="ls_nao_context, grep_nao_context, read_nao_context" icon="folder-tree">
    Browse your nao context: list files and directories, search text patterns across them, and read individual files.

    * Requires **Context-layer mode**.
  </Accordion>

  <Accordion title="create_story, update_story" icon="pen-to-square">
    Create a new nao story or update an existing one from query results.

    * Requires **Context-layer mode**.
  </Accordion>

  <Accordion title="display_chart" icon="chart-bar">
    Renders a chart from an `execute_sql` result, returned as an interactive embed.

    * Available whenever **either** mode is enabled.
  </Accordion>

  <Accordion title="Story management: list_stories, get_story, archive_story, delete_story" icon="book">
    List, read, archive, and delete existing nao stories.

    * Available whenever **either** mode is enabled.
  </Accordion>
</AccordionGroup>

## nao MCP app

The nao MCP app brings the nao UI directly into your AI agent. When a connected client calls `display_chart` or the story tools (`create_story`, `update_story`, `get_story`), nao returns an interactive embed that renders inline in the conversation - the same charts and stories you see in the nao web UI, without leaving your agent.

Clients that don't support iframes get a sandboxed HTML fallback.

<div style={{ maxWidth: '1400px', margin: '1.5rem auto 0' }}>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/c2Se2w8dWfE?modestbranding=1&rel=0&iv_load_policy=3&showinfo=0" title="nao MCP App Demo" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</div>

### What gets embedded

| Tool                                          | Embed                                                                                                                                                       |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `display_chart`                               | Interactive chart with hover values, zoom, and axis controls - same design as the nao UI                                                                    |
| `create_story` / `update_story` / `get_story` | Full story view with sections, charts, and a download button (PDF or HTML). Click the link to open the story in the nao UI for further editing and sharing. |

### How it works

1. Ask a question (e.g. "analyze number of PRs merged every week"). The agent runs SQL via nao MCP.
2. nao stores the query results in a temporary table (retained for 7 days) and returns an embed URL.
3. The MCP client renders the chart or story inline as an interactive iframe - you can hover over data points to see values, just like in the nao web UI.
4. To keep editing, click the link to open the story in the nao UI where you can share it with your team.

### Why this matters

The MCP app gives you the best of both worlds: the power of your AI agent for analysis, and the nao UI for visualization. Everyone at the company gets the same data reliability, the same chart design, and the data team keeps full observability - regardless of which agent the end user is working in.

### Supported clients

The nao MCP app works in any MCP client that supports iframes. Tested clients:

* Cursor
* GitHub Copilot
* ChatGPT
* Claude Desktop

### Story downloads

From the embed header, viewers can export a story as PDF or HTML. The download endpoint validates the same signed token as the view, so anyone with the embed link can download the story within the 7-day window.

## What's next

<CardGroup cols={2}>
  <Card title="Configure nao MCP endpoint" icon="plug" href="/nao-agent/chat/admin/setup#configure-nao-mcp-endpoint">
    Step-by-step config for Cursor, Codex, Claude Code, Claude Desktop, and CLI
  </Card>

  <Card title="Chat capabilities" icon="messages" href="/nao-agent/chat/capabilities/overview">
    Explore what the nao agent can do natively in chat
  </Card>
</CardGroup>