API and MCP

The Tana Outliner Local API provides direct access to Tana Outliner data from the desktop application. It exposes an MCP (Model Context Protocol) endpoint allowing AI tools to connect.

Tana Outliner offers two MCP servers: a local server that runs inside the desktop app (free, and the main subject of this page), and a hosted server for connecting remote clients over the internet. See Hosted MCP server.

Hosted MCP server (beta)

Alongside the local server, Tana Outliner offers a hosted MCP server, also called Remote MCP, that you can connect to from anywhere without the desktop app running. Because it is hosted rather than on localhost, remote-only clients work with it, and you can connect the new Tana so your Tana Outliner graph is available in its AI chat.

Setup is much simpler than the local server: there is no desktop app to keep running, no localhost port, and no API token to manage. Point any MCP client that supports HTTP and OAuth at the hosted URL, authorize when prompted, and you are connected.

Connect the new Tana:

1. In the new Tana, open Settings, Custom MCP servers
2. Click Add server and paste https://app.tana.inc/mcp
3. Give it a name, for example "Tana Outliner", and add it
4. Tana Outliner asks you to allow the connection; click Allow

Once connected, the new Tana can reach your Outliner graph from any chat, using the same tools as the local server (see Available tools): search nodes, read and navigate the node tree, read and edit supertags and fields, and create nodes. The connection runs both ways, so you can pull Outliner context into a Tana document or meeting and send new content back into a node in Outliner. The same URL works for other remote clients, including Claude Desktop, Codex, and always-on cloud agents.

When you move content between the tools, ask the AI to carry the Outliner node IDs across. A node ID points at one exact node, so the AI can go straight back to it to read or update it later, and structured references survive the trip instead of flattening into plain text.

For the step-by-step setup and the workflows it opens up, see Connect Tana to Tana Outliner. For a full walkthrough, see the Remote MCP systems lab.

The hosted server is in beta and requires a paid plan. The local server described below stays free for everyone.

Local MCP server

The rest of this page covers the local server, which runs inside the Tana Outliner desktop app. It is on by default and stays on localhost, so your data stays on your machine until a client requests it. The requirements and setup below all apply to this local server.

Requirements

• Tana Outliner desktop app (latest version)
• MCP-compatible client (Claude Code, Gemini CLI, Codex CLI, Cursor, VS Code, etc.)
• Desktop app must be running for client connections

Enabling the API

The Local API / MCP server is enabled by default and runs whenever the Tana Outliner desktop app is open, so there's nothing to switch on. You can optionally have Tana Outliner auto-configure a client for you from OS menu → Options → Local API settings (currently Claude Code only); other clients use the manual setup below.

Connection details

Setup by client

All CLI tools use the same connection details:

• Transport: HTTP
• URL: http://localhost:8262/mcp

Claude Code

Auto-configure (recommended):

1. In Tana Outliner, go to OS menu → Options → Local API settings
2. Enable the Claude Code option

This auto-configures while Tana Outliner runs and removes the configuration on close.

Manual setup:

claude mcp add --transport http tana-local http://localhost:8262/mcp

Scope options (-s):

• -s local — only you in current project, not shared (default)
• -s project — shared with everyone in project via .mcp.json
• -s user — available to you across all projects

This creates the following configuration:

{
  "mcpServers": {
    "tana-local": {
      "type": "http",
      "url": "http://localhost:8262/mcp"
    }
  }
}

For authentication, run /mcp in Claude Code, select the tana-local server, and complete the OAuth flow. A modal appears in Tana Outliner Desktop for approval, then a browser window confirms authentication status.

Codex CLI

codex mcp add tana-local --url http://localhost:8262/mcp

This creates the following configuration:

[mcp_servers.tana-local]
url = "http://localhost:8262/mcp"

The command writes to user scope (~/.codex/config.toml) by default and initiates authentication immediately. A modal appears in Tana Outliner Desktop for approval, followed by browser confirmation.

For project scope, manually create .codex/config.toml in the project root. Run codex mcp login tana-local to authenticate if not already completed.

Gemini CLI

gemini mcp add -t http -s user tana-local http://localhost:8262/mcp

Scope options (-s):

• -s project — current project only (.gemini/settings.json, default)
• -s user — available across all projects (~/.gemini/settings.json)

This creates the following configuration:

{
  "mcpServers": {
    "tana-local": {
      "url": "http://localhost:8262/mcp",
      "type": "http"
    }
  }
}

To authenticate, start a Gemini CLI session and run /mcp auth. Select the tana-local server, then approve the permissions prompt in Tana Outliner Desktop. A browser window confirms authentication status.

Claude Desktop

Claude Desktop requires the mcp-remote bridge since it cannot connect to local HTTP servers directly.

First, install mcp-remote:

npm install -g mcp-remote

Then in Claude Desktop, go to Settings → Developer and click "Edit Config". This opens claude_desktop_config.json. Add the following to the MCP server config:

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tana-local": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8262/mcp"]
    }
  }
}

After saving, restart Claude Desktop. The tana-local server should display as running when properly configured.

Personal API token method (advanced fallback)

If your MCP client is not listed here, or if you have OAuth issues with the built-in authorization flow, you can connect to Tana Outliner's local MCP server with a personal API token instead.

This is an advanced fallback. If your client supports the built-in Tana Outliner authorization flow above and it works reliably, that is still the recommended option.

1. Open your profile settings from the top right of Tana Outliner, go to API tokens, then the Personal Tokens tab
2. Create a Personal Token
3. Create or update your MCP config file for Tana Outliner (you can do this manually or ask your coding agent to do it for you)

Your MCP config should include a Tana Outliner entry like this:

{
  "mcpServers": {
    "tana-local": {
      "transport": {
        "type": "sse",
        "url": "http://127.0.0.1:8262/mcp",
        "headers": {
          "Authorization": "Bearer ${TANA_API_TOKEN}"
        }
      }
    }
  }
}

Set TANA_API_TOKEN in your environment before starting your MCP client.

For example:

• macOS/Linux: run export TANA_API_TOKEN="your-token-here" in the terminal, then start your MCP client from that same shell
• Windows PowerShell: run $env:TANA_API_TOKEN="your-token-here", then start your MCP client

Important notes:

• Tana Outliner Desktop must still be running, because the MCP server is hosted locally
• Keep your personal token private and never commit it to source control
• Prefer using an environment variable rather than pasting the token directly into a config file
• Different MCP clients may use different config file names and schemas, but the required values are the same: the local MCP URL plus the Authorization: Bearer ... header

Verify your connection

After setup, verify the connection is working:

You should see the tana-local server listed with a connected status.

Available tools

Read operations

• list_workspaces - List available workspaces
• search_nodes - Search for nodes using structured queries
• read_node - Read a node and its children as markdown
• get_children - Get paginated children of a node
• list_tags - List supertags in a workspace
• get_tag_schema - Get the schema definition of a supertag

Mutation operations

• import_tana_paste - Import content using Tana Paste format
• tag - Add or remove supertags from a node
• set_field_option - Set a field to a predefined option value
• set_field_content - Set a field's content to a string value
• create_tag - Create a new supertag
• add_field_to_tag - Add a field to an existing supertag
• set_tag_checkbox - Configure the done checkbox for a supertag
• check_node / uncheck_node - Check or uncheck a node's checkbox
• trash_node - Move a node to trash
• get_or_create_calendar_node - Get or create a calendar node
• edit_node - Edit a node's name or description using search-and-replace

Troubleshooting