Overview

Heptabase’s MCP (Model Context Protocol) lets external AI services list, search, read, create, edit, and organize content in your Heptabase space.

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.

How to connect an external AI service to Heptabase MCP

General Flow

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.

Example: Connecting MCP with ChatGPT

Important: 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.

To connect Heptabase MCP to ChatGPT:

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

How to Work with Heptabase MCP Tools

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.

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

Tools we currently offer

The current MCP tool set can list, search, read, create, and edit content in your Heptabase space.

Browse cards, tags, and whiteboards

list_cards

Lists cards without reading their content. You can filter by card type, whiteboard or tag membership, timestamps, or known IDs, and include lightweight metadata such as tags, whiteboards, and timestamps.

list_tags

Lists tags with their hierarchy and card counts. Use it to discover a tag ID before filtering cards or reading a tag database.

list_whiteboards

Lists the whiteboard hierarchy with lightweight object counts and pagination.

Search your Heptabase space

search_by_keyword

Searches titles and supported text content using exact keywords or short phrases. PDF, video, and audio cards are searched by title only. Use a read tool when you need complete content.

search_by_semantic

Searches by meaning using a natural-language query. This is useful when relevant notes may use different wording. Semantic search does not search tags or whiteboards.

search_object_content

Searches literal or regular-expression text inside one known object. It returns matching excerpts with line numbers and can search stored parsed content for PDF cards.

Read content and structure

read_object

Reads a specific object after another tool returns its ID. Long text can be read in parts. For a PDF card, this tool returns metadata; use read_pdf for page content.

read_whiteboard

Reads either a whiteboard’s structure or the content of the objects placed on it.

read_journal_range

Reads existing daily journal entries in an inclusive date range, oldest first. Each call can cover at most 92 days.

read_database

Reads a tag database’s property schema, views, filters, sorts, select options, and relation targets.

read_pdf

Reads an inclusive, 1-indexed page range from a parsed PDF card. The PDF must already be supported and successfully parsed.

read_image

Reads an image referenced by read_object using the image reference’s file and source-object information.

PDF highlight source anchors are not currently included in MCP read results. MCP does not provide the source PDF ID, page number, highlighted region coordinates/rects, or an equivalent precise deep link for an individual highlight. There is also no whiteboard-scoped export containing those anchors. A full-account export is currently required if you need to reconstruct them.

Read the MCP reference

read_system_manual_page

Reads Heptabase MCP reference pages for core concepts, rich-text syntax, and database properties.

Create and edit content

Important: Heptabase MCP can currently create note cards and journal entries, but it cannot upload files or create new image cards. To use an image, upload or paste it into Heptabase first. MCP can then find, read, or place the existing image card on a whiteboard. If you only need a reference, create a note card containing the image URL.

create_object

Creates a new note card, or creates a journal entry when no journal exists for that date.

append_to_journal

Appends content to an existing journal entry, or creates the journal entry if it does not exist.

edit_object_content

Finds and replaces exact text in a note card or journal entry.

edit_card_properties

Updates property values for a card in an existing tag database.

update_database_card_membership

Adds existing cards to a tag database.

place_whiteboard_objects

Places existing cards or other supported objects on a whiteboard.

Summary

A typical workflow combines several tools:

Browse: use list_cards, list_tags, or list_whiteboards to discover what exists.
Search: use search_by_keyword for exact wording, search_by_semantic for related ideas, or search_object_content inside a known object.
Read: use the relevant read tool to retrieve full content, whiteboard structure, journal ranges, database configuration, PDF pages, or images.
Create or edit: create cards, append to journals, edit card content and properties, add cards to tag databases, or place existing objects on whiteboards.

Connect Heptabase MCP with other tools

Claude Code
- Open your terminal
- Command: claude mcp add --transport http heptabase-mcp https://api.heptabase.com/mcp
- Login to Claude Code, type /mcp, then enter heptabase-mcp to authenticate.
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.

How to use Heptabase MCP?