Heptabase’s MCP (Model Context Protocol) lets external AI services list, search, read, create, edit, and organize content in your Heptabase space. In compatible apps, it can also display selected cards in an interactive view.

Tools like ChatGPT or Claude can discover notes, journals, tags, whiteboards, images, and parsed PDFs, then use the relevant content for research, summarization, review, or updates.

Connect your AI assistant

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

ChatGPT

Custom MCP apps must currently be set up on ChatGPT web. The setup options are not available in the ChatGPT desktop or mobile apps.

Developer mode availability also depends on your ChatGPT plan or workspace. If Developer mode is not shown on ChatGPT web, your current plan or workspace may not support custom MCP apps.

Open ChatGPT web in your browser and sign in. Do not use the desktop or mobile app for the setup.
Open Settings → Apps → Advanced Settings.
Enable Developer mode.
Return to Apps and choose the option to create a custom app. If the create option is missing, check that Developer mode is enabled and that your plan or workspace supports custom MCP apps.
Fill in the following fields:
- Name: Choose any name you like, such as Heptabase.
- MCP Server URL: https://api.heptabase.com/mcp
- Authentication: OAuth
- Icon (optional): You can download the Heptabase logo here.
Continue to the Heptabase authorization page. Sign in if needed, then click Allow.
Return to ChatGPT web and select the Heptabase app when you want ChatGPT to use your Heptabase MCP connection.
Try asking ChatGPT, “Find my notes about X and summarize the most relevant ones” or “Show me the whiteboards related to project Y.”

Claude Code

Open your terminal

Run this command:

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

Cursor

Open ~/.cursor/mcp.json (create the file if it does not exist).

Add the following remote server configuration:

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

Save the file, refresh Cursor, and complete the authorization flow.

Antigravity CLI

Add the following remote server configuration to ~/.gemini/antigravity-cli/mcp_config.json, or to .agents/mcp_config.json in the 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 authorization begins, contact us with your Antigravity CLI version and a screenshot of the error.

Other MCP services

You can connect Heptabase MCP to any third-party AI service that supports the Model Context Protocol (MCP) — for example, ChatGPT or Claude.

In the external AI service, find where you can add or connect an MCP server.
Enter the Heptabase MCP endpoint URL:
```
https://api.heptabase.com/mcp
```
The page will automatically redirect you to Heptabase, where you’ll:
- Sign in to your account (if not already logged in)
- Authorize the connection
After authorization, you’ll be redirected back to the external AI service — the connection is now established.
You can now use Heptabase’s MCP tools directly within that service.

Try your first task

In most cases, you do not need to remember tool names. Describe what you want the AI to find, read, or update, and it can choose the appropriate Heptabase MCP tools.

Task	Example prompt
Find relevant notes	Find my notes about renewable energy and summarize the most relevant ones.
Read and summarize	Read this card and summarize its main arguments and open questions.
Update your journal	Append this summary to today’s journal.

In clients that support MCP Apps, you can also ask the assistant to show the cards it finds. Updating content requires write access.

Permissions and supported actions

The tools available to a connection depend on the permissions granted during authorization. A read-only connection can browse and read content, but writing tools will not appear in its tool list. If your assistant cannot create or edit content, check the connection’s permissions and authorize write access if you want to enable those actions.

Tool reference

If you want more precise control, you can name a tool explicitly. For example:

“Use search_by_keyword to find notes containing this exact phrase.”
“Use search_by_semantic to find notes related to this idea, even if they use different words.”
“Use read_object to read the full content of this card.”

Explore the full MCP tool reference →