Use the official Heptabase plugin to search, read, create, and organize your Heptabase cards in ChatGPT or Codex. You do not need to set up a custom MCP server or install the Heptabase CLI.
Connect in ChatGPT
Open the plugin directory in ChatGPT. Depending on your interface, this may be labeled Plugins or Apps.
Search for Heptabase, open its listing, and choose the install or connect option.
Follow the authorization flow. Sign in to the Heptabase account containing your knowledge base, review the requested access, and approve the connection.
Return to your conversation and select Heptabase using the available plugin menu or an @ mention.
Connect in Codex
Open the plugin directory in the Codex app and search for Heptabase.
Install the plugin and complete the Heptabase account authorization when prompted.
In a supported task view, open Sources → Use plugins and select Heptabase.
Plugin availability and controls can vary by account, interface, and workspace. See OpenAI’s plugin guide if your interface differs. These steps are for the official plugin, not the separate Heptabase CLI.
Find and read your cards
Start with a topic you have already saved in Heptabase:
Find my notes about Mindstorms, summarize the main ideas, and show me the relevant cards.
The assistant can search and read supported cards, journals, whiteboards, and tag databases. It can also read images and successfully parsed PDF pages. In ChatGPT, it can display selected cards directly in the conversation so you can read the original content and ask follow-up questions. You can also ask to see a card after it creates or edits it.
Your cards remain in Heptabase. Displaying a card in ChatGPT does not move it out of your knowledge base. Use Open in Heptabase in the card view to continue in Heptabase.
Watch the short demo to see card search, display, and saving a summary back to Heptabase on a phone.
Save and organize what you discuss
Describe what you want to save and where it belongs. For example:
“Save this summary as a new card and add it to my Mindstorms whiteboard.”
“Append the key takeaways from this conversation to today’s journal.”
“Add this card to my existing Reading tag and set its Status property to an existing option, ‘Read’.”
“Update the conclusion in my existing card with what we just discussed.”
Use the names of your own whiteboards, tags, properties, and options. The plugin can add cards to existing tag databases and update supported property values; this does not create new tags, property columns, or select options. Set those up in Heptabase first. Whiteboard placement is automatic, not precise layout editing.
Continue from your phone to your computer
You can use the plugin in ChatGPT on your phone to find cards or save ideas while you are out. Open a displayed card in the Heptabase mobile app whenever you want to browse it there. Heptabase syncs across devices in real time, so saved changes will also appear on your computer once your devices are online and synced. Use the same Heptabase account on each device.
Common questions
Why can it read my cards but not edit them?
Creating or editing content requires write access. Review the Heptabase connection’s permissions and reconnect with write access if needed. Workspace restrictions or action approval settings in ChatGPT or Codex may also affect what the assistant can do.
Why can’t it find my cards?
Check that you connected the Heptabase account containing those cards and that they have synced. Ask the assistant to search for a specific card title. If you connected the wrong account, disconnect the Heptabase connection and sign in again with the intended account.
Why do I only see a text answer?
Ask the assistant to show the relevant Heptabase cards. Interactive display requires a compatible interface, such as ChatGPT or the Codex app; a terminal client may return text instead.
How do I disconnect?
In ChatGPT, open Settings → Apps or Plugins, select Heptabase, and use the connection or connected-account menu to disconnect. See OpenAI’s account connection guide for current controls. In Codex, manage the Heptabase connection through its plugin settings.
When should I use MCP or the CLI instead?
Use Heptabase MCP to connect another compatible AI service manually. Use the Heptabase CLI for terminal workflows or detailed whiteboard layout operations through the running desktop app. See the MCP tool reference for supported actions and limits.
If you need help, contact Heptabase support with the app you are using, the task you tried, and any error message. Do not include passwords or authorization tokens.