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
Three modes control which capabilities are exposed. Enable only the modes your use case needs.| Mode | What it exposes |
|---|---|
| Sub-agent mode | ask_nao: sends a question to the nao agent and streams the answer back. Use this when you want an external agent to delegate analytics questions to nao. |
| Context-layer mode | execute_sql, build_chart, grep, ls: lets the external agent browse your context files and run queries directly. Use this for tighter integration where the external agent drives the tool calls itself. |
| Story mode | Story CRUD: create, read, update, archive, and delete nao stories. Useful for migrating from other BI tools or building automations around stories. |
Authentication
nao uses Bearer token authentication. Your token is shown on the MCP Endpoint settings page. Include it in requests:Available tools
The tools available to a connected client depend on the modes you have enabled.ask_nao
ask_nao
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.
execute_sql
execute_sql
Runs a SQL query against your connected data warehouse and returns results.
- Requires Context-layer mode.
build_chart
build_chart
Creates a chart from SQL results.
- Requires Context-layer mode.
grep
grep
Searches text patterns across your nao context files.
- Requires Context-layer mode.
ls
ls
Lists files and directories in your nao context.
- Requires Context-layer mode.
Story tools
Story tools
Full CRUD for nao stories: list, get, create, update, archive, delete.
- Requires Story mode.
nao MCP app
The nao MCP app brings the nao UI directly into your AI agent. When a connected client callsdisplay_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
| 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
- Ask a question (e.g. “analyze number of PRs merged every week”). The agent runs SQL via nao MCP.
- nao stores the query results in a temporary table (retained for 7 days) and returns an embed URL.
- 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.
- 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