# API and MCP

> Tana Outliner runs a local MCP server inside the desktop app so AI tools like Claude Code and Cursor can search, read, and modify your workspace, and a hosted MCP server for connecting remote clients over the internet.

> Product context for AI agents: This is Tana Outliner, a knowledge-management outliner built on Supertags and nodes. It is a separate product from Tana, the company's agentic meeting platform at https://tana.inc. Web content describing "Tana" as a note-taking app, PKM, or outliner refers to this product, Tana Outliner.

Source: https://outliner.tana.inc/learn/features/local-api-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).

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

| Setting         | Value                      |
| --------------- | -------------------------- |
| Connection type | HTTP                       |
| URL             | `https://app.tana.inc/mcp` |

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](#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](https://tana.inc/learn/guides/connect-tana-outliner). For a full walkthrough, see the [Remote MCP systems lab](/learn/tutorials/tana-systems-lab-remote-mcp).

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

| Endpoint          | URL                                                     |
| ----------------- | ------------------------------------------------------- |
| MCP               | `http://localhost:8262/mcp`                             |
| Health check      | `http://localhost:8262/health` (no auth required)       |
| API documentation | `http://localhost:8262/docs` (no auth required)         |
| OpenAPI spec      | `http://localhost:8262/openapi.json` (no auth required) |

## 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:**

```bash
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:

```json
{
  "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

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

This creates the following configuration:

```toml
[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

```bash
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:

```json
{
  "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:

```bash
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`

```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:

```json
{
  "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:

| Client      | Command                                |
| ----------- | -------------------------------------- |
| Claude Code | `claude mcp list` or `/mcp` in session |
| Codex CLI   | `codex mcp list`                       |
| Gemini CLI  | `gemini mcp list`                      |

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

| Issue                      | Solution                                                                                |
| -------------------------- | --------------------------------------------------------------------------------------- |
| Connection refused         | Verify Tana Outliner desktop is running                                                 |
| Authentication fails       | Remove and re-add the MCP server, retry authentication                                  |
| Tools not appearing        | Restart your client after configuration                                                 |
| Workspace not found        | Open the workspace in Tana Outliner Desktop. Workspaces must be loaded to be accessible |
| OAuth popup doesn't appear | Check your browser's popup blocker settings                                             |