Skip to main content
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.
Enable and configure the MCP endpoint from Settings -> MCP Endpoint. For step-by-step client setup, see Configure nao MCP endpoint in the admin guide.

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

​
Long-running analyses

ask_nao waits up to 45 seconds for the agent to finish. If the run completes within that window, the answer comes back directly with status: "complete". If it does not, ask_nao returns status: "running" with the chatId of the run, which keeps going in the background. The client then calls get_nao_answer with that chatId until status becomes complete or error. This avoids the client request timing out on multi-minute analyses. The endpoint streams responses over SSE, so progress notifications emitted during a run reach the client while it waits.

​
Clarifying questions

When the agent needs more information, ask_nao and get_nao_answer return status: "needs_clarification" and a clarification object holding the question and optional options to choose from. Relay it to the user, then call ask_nao again with the same chatId and their answer.

​
Authentication

nao uses Bearer token authentication. Your token is shown on the MCP Endpoint settings page. Include it in requests:
Keep this token secret. Rotate it from the settings page if it is compromised. Calls run as the user the token belongs to, and that user needs a role on the project other than viewer. Users with the viewer role get a 403 response. The endpoint also advertises OAuth protected-resource metadata, so clients that support it can authenticate through the standard MCP OAuth flow instead of a static token.

​
Available tools

The tools available to a connected client depend on the modes you have enabled.
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 status, chatId, chatUrl, text, the queries the agent ran, and the story_ids it created or updated.
  • Pass an optional chatId to continue an existing chat instead of starting a new one.
Polls the result of an ask_nao run that is still in progress.
  • Requires Sub-agent mode.
  • Takes the chatId returned by an ask_nao call that responded with status: "running".
  • Returns the same payload as ask_nao, plus an error field when status is error.
Runs a SQL query against your connected data warehouse and returns results.
  • Requires Context-layer mode.
Browse your nao context: list files and directories, search text patterns across them, and read individual files.
  • Requires Context-layer mode.
Create a new nao story or update an existing one from query results.
  • Requires Context-layer mode.
Renders a chart from an execute_sql result, returned as an interactive embed.
  • Available whenever either mode is enabled.
List, read, archive, and delete existing nao stories.
  • Available whenever either mode is enabled.

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

​
What gets embedded

​
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

Configure nao MCP endpoint

Step-by-step config for Cursor, Codex, Claude Code, Claude Desktop, and CLI

Chat capabilities

Explore what the nao agent can do natively in chat