Use the official Heptabase plugin to search, read, create, and organize content in Heptabase from ChatGPT or Codex. You do not need to enable Developer mode, configure an MCP server manually, or install the Heptabase CLI.
Install and connect Heptabase
ChatGPT and Codex use the same Plugins Directory:
Open the Plugins Directory in ChatGPT or Codex.
Search for Heptabase and install the plugin.
When prompted, sign in to Heptabase, review the requested permissions, and approve the connection.
After installation, start a new chat or Codex task. You can ask the assistant to use Heptabase, or type
@Heptabaseto select the plugin explicitly.
If you use Codex CLI, enter /plugins to install Heptabase, then start a new session.
The interface may change as OpenAI updates its products. See OpenAI's plugin guide for the latest instructions.
Get started
You do not need to remember MCP tool names. Describe what you want to find and what you want the assistant to do with it. For example:
“Find my cards about Mindstorms, summarize the main ideas, and show me the most relevant cards.”
“Append the key takeaways from this discussion to today's journal.”
“Update the conclusion in my ‘Research plan’ card based on what we just discussed.”
“Add this card to my existing ‘Reading’ tag and place it on my ‘Mindstorms’ whiteboard.”
“Read this PDF and summarize the main argument of each section.”
After finding, creating, or editing a card, you can ask the assistant to display it. Select Open in Heptabase to continue working with it in Heptabase.
You can also watch the short demo to see how to find and display cards, then save a discussion summary back to Heptabase.
Supported content and actions
The Heptabase plugin can:
Search and read cards, journals, whiteboards, and tag databases.
Read images and successfully parsed PDFs.
Create note cards and journals.
Edit card content or append content to a journal.
Add cards to existing tags and update existing property values.
Place existing cards and other supported content on a whiteboard.
Display cards in supported ChatGPT or Codex interfaces.
Current limitations:
It cannot create new tags, property columns, or options.
It cannot upload files or create new image cards.
Objects placed on a whiteboard are arranged automatically. The plugin cannot precisely edit their position, size, or connections.
To-dos cannot currently be checked off in the ChatGPT card preview. Select Open in Heptabase to complete them.
Text-only interfaces such as Codex CLI do not display interactive cards and will present the result as text instead.
See the Heptabase MCP tool reference for the complete supported scope.
Permissions and connection issues
The available actions depend on the permissions granted when you connect the plugin. A read-only connection can search and read content, but it cannot create or edit content.
If the plugin is not working as expected:
After installing the plugin, start a new chat or Codex task.
If Heptabase is not being used, type
@Heptabaseto select it explicitly.If the available actions appear incomplete or outdated, select Refresh in the plugin settings, then start a new chat.
If the assistant cannot find expected content, confirm that you connected the intended Heptabase account.
If the connection has expired, reconnect it. If this happens repeatedly, contact support with the app you are using, the time of the error, and the error message.
Do not send passwords, API keys, or authorization tokens to Heptabase support.
Other connection methods
To connect another MCP-compatible AI service, see Heptabase MCP.
For terminal workflows or precise whiteboard layout operations through the running desktop app, use the Heptabase CLI.
If you still need help, contact Heptabase support.