# Connect Nirvana to external AI clients via MCP

Nirvana ships a native **Model Context Protocol (MCP)** server. Connect it to an external AI client — Claude, ChatGPT, Cursor, VS Code, Claude Code, or any MCP-compatible app — and that client can read and write your tasks and projects directly, without the Nirvana app running.

This is separate from Nirvana's [built-in AI assistant](/content/help/ai/using-the-chat-panel/index.html), which lives inside the Nirvana app. MCP is for connecting _external_ AI clients to your account.

## What the AI client can access

Once connected, the client can:

- **Read your tasks** — by GTD state (Inbox, Next, Waiting, Scheduled, Someday, Later, Focus), by project, by tag, or by date range
- **Read task counts** — totals per GTD list
- **Read your tags** — contexts and areas with usage counts
- **Create tasks and projects** — with name, notes, state, tags, due date, scheduled start date, energy, and time estimate
- **Update tasks** _(requires Nirvana Pro)_ — change any field, complete, star/unstar, move between lists, or soft-delete to trash

The client can only access _your_ data. It cannot see any other user's account, and it never sees your Nirvana password.

## How to connect

Open the **[Nirvana MCP dashboard](https://mcp.nirvanahq.com/dashboard)** and pick the client you want to connect. Each card opens a short install guide tailored to that client:

| Client | Install path |
| --- | --- |
| **Claude** (claude.ai) | One-click **Open in Claude** — launches the Add custom connector dialog |
| **ChatGPT** | One-click **Open in ChatGPT** — lands on Settings → Connectors → Advanced |
| **Cursor** | One-click **Add to Cursor** deeplink |
| **Claude Code** | Copyable `claude mcp add` CLI command |
| **VS Code** | One-click **Add to VS Code** with the server pre-filled |
| **Other clients** | Copyable `mcpServers.json` snippet (Continue, Zed, and any client that reads that format) |

The dashboard is the source of truth for install steps — it stays up-to-date as connectors evolve. The Nirvana MCP server URL is always `https://mcp.nirvanahq.com/mcp`.

## Plan requirements

**On the Nirvana side:** Free accounts get full read access plus task and project creation. **Updating** existing tasks (renaming, retagging, completing, starring, moving between lists) requires **Nirvana Pro**.

**On the client side:** Most MCP clients (Claude, Cursor, Claude Code, VS Code) work on their free or paid tiers. **ChatGPT** is the exception — MCP connectors live in Developer Mode, which is available on:

- **Pro** — read-only (ChatGPT blocks write actions like `create_tasks` and `update_tasks` on this tier regardless of your Nirvana plan)
- **Business, Enterprise, Edu** — full access, including write actions

ChatGPT Free, Plus, and Team plans do not have Developer Mode at this time. The flow is also web-only — there's no MCP support in the ChatGPT mobile app yet.

## Security model

Every supported client authenticates through Nirvana's sign-in screen and receives a short-lived access token plus a refresh token — no password or long-lived secret is ever pasted into the AI client.

All requests are scoped to your single Nirvana account. The MCP server cannot read or write to anyone else's data.

## Manage and revoke access

Visit the **[Nirvana MCP dashboard](https://mcp.nirvanahq.com/dashboard)** to see every client connected to your account. Disconnect any client to revoke its access immediately.

If you suspect a session is compromised, disconnect it from the dashboard and reconnect the affected client.

## Troubleshooting

**"No tools available" or zero actions shown after connecting.**  The access token most likely expired and the client didn't refresh cleanly. Disconnect from the dashboard, then reconnect from the client.

**Create or update actions fail with "requires a Pro subscription".** `update_tasks` requires Nirvana Pro. `create_tasks` works on Free. If you're on ChatGPT Pro, _any_ write action is blocked by ChatGPT regardless of your Nirvana plan — upgrade to ChatGPT Business+ or use a different client.

**ChatGPT shows tasks but won't create or update them.** You're on ChatGPT Pro. Developer Mode on Pro is read-only. Switch to Business, Enterprise, or Edu, or use one of the other clients above for full read+write.

**Connector worked yesterday, broke today.** Disconnect and reconnect from the dashboard. OAuth refresh tokens sometimes drop after long idle periods, and the cleanest fix is a fresh handshake.