Using ChatGPT, Codex, Claude, or Claude Code? Install the official Heptabase plugin instead: see Use Heptabase with ChatGPT and Codex or Use Heptabase with Claude and Claude Code. The setup on this page is for connecting other AI services, or for connecting manually.

Heptabase MCP (Model Context Protocol) lets AI assistants work with your Heptabase space. Your assistant can search and read your cards, journals, whiteboards, and tag databases, write notes, save files and links as cards, organize tags, process your Inbox, and lay out whiteboards.

MCP requires a Heptabase Pro, Premium, or Premium+ subscription, or an active free trial. This includes read-only connections.

What your assistant can do

Find and read: search by keyword or by meaning, and read cards, journals, whiteboards, tag databases, PDFs, images, highlights, and backlinks.
Write: create and edit note cards and journals, including images, videos, audio, and attachments.
Save files and links: create PDF, image, audio, video, web, and YouTube cards from files or URLs.
Organize: create and edit tag databases, add or remove cards in them, set card properties, create tag groups, move tags, and trash or restore cards.
Process your Inbox: read your Inbox, add cards to it, mark items done or set a reminder, and remove items you added.
Follow your Space Instructions: read the standing rules you set for how AI works in your space, and set a card as your Space Instructions.
Work on whiteboards: create whiteboards, sections, connections, and mind maps, and move, align, resize, recolor, or remove objects.
Show results: display cards in the chat, or open a whiteboard right inside ChatGPT, Claude, Codex, and Claude Code in the Claude desktop app.

See the MCP tool reference for every tool.

Some actions need Heptabase open

Whiteboard editing, editing and querying tag databases, removing cards from tag databases, renaming, and reading backlinks run in the Heptabase app. For these, keep the Heptabase desktop app or the web app open and signed in to the same account. When you connect through ChatGPT or Claude, the assistant can open Heptabase right inside the chat instead, also in Codex and in Claude Code in the Claude desktop app. The mobile app does not run these actions.

When Heptabase is open, the assistant also reads from it, so it sees edits that have not synced yet. Everything else works without the app.

Connect your AI assistant

Choose your AI service: ChatGPT · Claude Code · Cursor · Antigravity CLI · Other services

ChatGPT: custom MCP app

The official plugin is the simpler option. Use these steps only if you want a custom MCP app. Custom MCP apps need Developer mode, which depends on your ChatGPT plan or workspace, and they can only be set up on ChatGPT web.

Open ChatGPT web and sign in.
Open Settings → Apps → Advanced Settings, and turn on Developer mode.
Return to Apps and create a custom app. If the option is missing, check that Developer mode is on and that your plan or workspace supports custom MCP apps.
Fill in the fields:
- Name: any name, such as Heptabase.
- MCP Server URL: https://api.heptabase.com/mcp
- Authentication: OAuth
- Icon (optional): the Heptabase logo.
Sign in to Heptabase if needed, and click Allow.
In a chat, select the Heptabase app when you want ChatGPT to use it.

Claude Code

The official plugin is the simpler option. To connect manually:

Run this command in your terminal:

claude mcp add --transport http heptabase-mcp https://api.heptabase.com/mcp

Then start Claude Code, enter /mcp, and select heptabase-mcp to sign in.

Cursor

Add this server to ~/.cursor/mcp.json, creating the file if it does not exist:

{
    "mcpServers": {
        "heptabase-mcp": {
            "url": "https://api.heptabase.com/mcp"
        }
    }
}

Save the file, refresh Cursor, and complete the sign-in.

Antigravity CLI

Add this server to ~/.gemini/antigravity-cli/mcp_config.json, or to .agents/mcp_config.json in your workspace:

{
    "mcpServers": {
        "heptabase-mcp": {
            "serverUrl": "https://api.heptabase.com/mcp"
        }
    }
}

Antigravity CLI connects directly through serverUrl and does not need mcp-remote. If it shows Unauthorized before sign-in starts, contact us with your Antigravity CLI version and a screenshot of the error.

Other services

Any AI service that supports remote MCP servers can connect to Heptabase.

In the service, find where to add an MCP server.
Enter https://api.heptabase.com/mcp.
Sign in to Heptabase when you are redirected, and authorize the connection.
Return to the service. Heptabase is now connected.

Try your first task

You do not need to know tool names. Describe what you want, and the assistant picks the tools.

Task	Example prompt
Find and summarize	Find my notes about renewable energy and summarize the most relevant ones.
Write to your journal	Append this summary to today's journal.
Save a source	Save this paper as a PDF card and summarize its first section: https://arxiv.org/pdf/1706.03762
Organize a whiteboard	Group the cards on my "Thesis" whiteboard into sections by theme.
Process your Inbox	Go through my Inbox and suggest a whiteboard or tag for each card.

Permissions

What the assistant can do depends on the access you grant when you connect. A read-only connection can search and read, but cannot change anything. To let the assistant make changes, reconnect and grant write access.

Tool reference

To control exactly what the assistant does, you can name a tool, for example: "Use search_by_keyword to find notes containing this exact phrase."

See the full MCP tool reference →