Tools, MCPs, Skills

Agent Tools

The nao agent uses built-in tools autonomously to answer user requests.

execute_sql

Execute SQL against connected databases and return structured results.

Supports multiple database connections.
Returns typed columns and row counts.
Outputs can be reused by other tools.
Pass duckdb_local as the database to use nao’s own DuckDB engine instead of a warehouse: it queries CSV, JSON, Parquet, and Excel files by path, and joins them against earlier query results. See Files and Storage.
save_to writes the result to a CSV or Parquet file in permanent storage, on top of returning the rows.

display_chart

Create charts from SQL results.Supported chart types:

Bar charts
Stacked bar charts
Line charts
Pie charts
KPI cards

Charts are rendered in chat and can also be sent in Slack conversations.

execute_sandboxed_code

Execute code in an isolated sandbox (micro-VM) for advanced analysis.

Supports Python and shell execution.
Can install Python packages for a run.
Can reuse prior SQL outputs as CSV inputs.
Images uploaded to the chat are mounted into the sandbox, so the agent can read or manipulate them directly from Python (e.g. OCR, cropping, chart comparison).
Files in permanent storage are mounted the same way through storage_files, for formats the other tools cannot parse.
Requires enabling Sandboxes in Admin -> Agent -> Experimental.

write

Save a file to permanent storage, under the user’s /home folder.

/home is the only writable place in the file tree; project context is read-only.
Used for exports, spreadsheets the agent builds, and intermediate results worth reusing.
Unavailable when the deployment sets NAO_STORAGE_BACKEND=none. See Files and Storage.

Search files with glob patterns in your context.

list

List files and directories so the agent can navigate project structure.

read

Read context files such as SQL models, docs, and rule files.

grep

Search text patterns across context files with regex.

web_search / web_fetch

Search the public web with your model provider tools and fetch cited pages when needed.

Uses provider-native capabilities (OpenAI, Anthropic, Google) when enabled.
Lets the agent answer questions that need fresh external information.
Sources are shown in tool call output for traceability.

clarification

Ask the user a focused question when their request is genuinely ambiguous (multiple plausible tables, unclear metric, missing time range, etc.).

Renders a “Quick question” card with the question and up to 5 clickable answer chips.
Clicking a chip sends the answer directly - no extra Enter press required.
Free-form answers via the normal chat input are also supported.
The agent pauses and waits for the user’s reply before continuing.
Multi-turn clarification works naturally: previous cards switch to an “Answered” state with a checkmark on the selected chip so the full decision trail stays visible.

You do not need to select tools manually. The agent chooses and orchestrates tools based on each question.

Web search is optional and can be enabled per project from Settings -> Project -> Agent -> Web search.

MCPs

MCP (Model Context Protocol) servers expose external tools that the agent can call next to built-in tools. Configure MCP servers in agent/mcps/mcp.json:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["-y", "@getnao/metabase-mcp-server@latest"],
      "env": {
        "METABASE_URL": "http://localhost:3008/",
        "METABASE_API_KEY": "your-metabase-api-key"
      },
      "disabled": false,
      "autoApprove": [],
      "disabledTools": []
    }
  }
}

Do not commit secrets. Store credentials in runtime environment variables or a secrets manager.

Remote HTTP servers

Alongside local command servers, you can connect to remote MCP servers over HTTP. Set transport to streamable-http and point url at the server endpoint:

{
  "mcpServers": {
    "notion": {
      "transport": "streamable-http",
      "url": "https://mcp.notion.com/mcp"
    },
    "linear": {
      "transport": "streamable-http",
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

Accepted transport values are streamable-http, sse, and http. Servers declared with a command run over stdio.

How nao loads MCP tools

nao does not hold a live client connection to each server, and it never loads every tool definition into the context window. Instead:

nao connects to the server once and reads its tool list.
It writes one OpenAPI JSON file per enabled tool into the context filesystem, at agent/mcps/<server>/<tool>.json. The file name is the tool name.
The agent discovers what it needs on demand with the normal list, read, and grep tools, then invokes it through a single mcp_call tool.

mcp_call takes the server name, the tool to run (the operation’s operationId), and an arguments object matching that operation’s request body schema. Arguments are validated against the schema before the call runs, so a malformed call comes back as a validation error listing the specific issues rather than failing at the server.

The generated spec directories are gitignored - they are discovered at runtime and do not need to be committed.

Inline authentication

When a remote server requires OAuth, nao prompts the user to sign in inline the first time its tools are needed, so each user authenticates with their own account instead of sharing one organization-wide login. The connection is authorized per user and reused on later runs. If the agent calls a tool on a server the user has not connected yet, the call returns an auth-required result and a Connect button is shown below the conversation. The agent stops and waits instead of retrying.

Managing servers and tools

Admins manage MCP servers from Settings -> MCP Servers. The table lists each server declared in agent/mcps/mcp.json with its transport, connection status, the number of enabled tools out of the total, and a toggle to enable or disable the whole server. Connect all MCP servers re-runs discovery across every server, and each row has its own refresh action to reconnect a single server. Connection status shows as Connected, Cached (discovered previously, not re-tested), Waiting for connection (OAuth pending), Error, or Not tested. Expanding a row shows the path where that server’s specs were written, plus its tools grouped by category - Read-only, Write, Delete, or Unknown - inferred from the tool name. Each category has a toggle to enable or disable the whole group at once, and each tool has its own toggle. Disabled tools are not written to the context filesystem, so the agent cannot discover or call them. See Admin Setup for the full configuration walkthrough. In chat, MCP tool calls and their outputs are rendered with a dedicated block: each call shows the server name, the tool used, and the returned payload formatted for readability (tables, JSON, and text are laid out distinctly rather than dumped as raw strings).

Skills

Skills are reusable workflows defined as markdown files in agent/skills/. A file is recognized as a skill only if:

It is stored in agent/skills/.
It starts with YAML frontmatter including name and description.

---
name: top-customers
description: Analyze database to find top 5 customers by total payments.
---

In chat, users can trigger skills through / shortcuts or natural prompts that match skill descriptions.

Get Started

Context Builder

Context Engineering

Chat Interface

Connectors

Self-Hosting

nao Cloud

nao Enterprise

Developers

Tools, MCPs, Skills

Agent Tools

MCPs

Remote HTTP servers

How nao loads MCP tools

Inline authentication

Managing servers and tools

Skills

​Agent Tools

​MCPs

​Remote HTTP servers

​How nao loads MCP tools

​Inline authentication

​Managing servers and tools

​Skills

Agent Tools

MCPs

Remote HTTP servers

How nao loads MCP tools

Inline authentication

Managing servers and tools

Skills