Skip to main content

How to use Heptabase MCP?

Updated this week

Overview

Heptabase’s MCP (Model Context Protocol) lets external AI services work directly with your Heptabase space — not just by chatting, but by actually reading, searching, and writing to your knowledge base.

With MCP, tools like ChatGPT or Claude can discover your existing notes and whiteboards, understand their context, and then save new insights back into your space as note cards or journal entries. This creates a seamless loop between thinking with AI and growing your long-term knowledge in Heptabase.

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.

  1. In the external AI service, find where you can add or connect an MCP server.

  2. Enter the Heptabase MCP endpoint URL:

    https://api.heptabase.com/mcp

  3. The page will automatically redirect you to Heptabase, where you’ll:

    • Sign in to your account (if not already logged in)

    • Authorize the connection

  4. After authorization, you’ll be redirected back to the external AI service — the connection is now established.

  5. You can now use Heptabase’s MCP tools directly within that service.

Example: Connecting MCP with ChatGPT

Note: ChatGPT’s Team Plan currently does not support MCP connections.

You’ll need to use a Personal Plus Plan or a higher plan.

To connect Heptabase MCP to ChatGPT:

  1. Open ChatGPT Settings → Apps & Connectors → Advanced settings.

  2. Enable Developer mode.

  3. In Apps & Connectors, click Create (top right corner).

  4. Fill in the following fields:

    • Icon: You can download our logo file here

    • Name: You can choose any name you like

    • MCP Server URL: https://api.heptabase.com/mcp

    • Authentication: OAuth

  5. You’ll be redirected to the Heptabase login page:

    • Log in (if needed) and click Allow to grant authorization.

  6. Return to ChatGPT. In the chat box, click the “+” button on the left, and select the MCP integration you just created.

  7. You can now use Heptabase MCP commands directly within ChatGPT conversations! Try saying, "Send this conversation to my journal" or "Create a card in Heptabase for me" and see how it works.

How to Work with Heptabase MCP Tools

In most cases, you don’t need to remember any tool names or think about which tool to use. Just talk to the AI naturally (e.g., “Summarize my notes about X and save the result so I can review it later”), and it will decide which tools to call on its own.

If the AI’s behavior doesn’t match what you expect — for example, it doesn’t save something where you want it, or it seems to ignore existing notes — you can scroll down to the detailed tool descriptions below and explicitly tell it what to use. For instance, you might say:

  • “Use save_to_note_card to save this answer as a new note card.”

  • “Use append_to_journal to add this summary to today’s journal.”

  • “Use semantic_search_objects to search my existing notes about this topic first.”

This way, you can start simple and natural, and only reach for specific tool names when you want more precise control.

Tools we currently offer

1. Save as a card (save_to_note_card)

Use this when you want the AI to turn part of your conversation into a reusable note.

  • Allows the AI to create a new note card in your Heptabase space.

  • The created card appears in your Inbox, similar to content added via the Web Clipper.

Great for:

  • Turning long AI answers into permanent notes

  • Saving structured outputs like outlines, plans, and summaries

  • Capturing “aha” moments so you can organize them later on a whiteboard

Behind the scenes, the AI uses the save_to_note_card tool to send whatever content you asked it to save into a new note card.

2. Append to Journal (append_to_journal)

Use this when you want the AI to add something to today’s journal, instead of creating a new note.

  • Allows the AI to add content as new blocks to today’s journal.

  • If today’s journal doesn’t exist yet, it will be created automatically.

  • This will not overwrite existing content — it works like adding a voice note.

Ideal for:

  • Daily reflections generated with AI

  • Quick logs (e.g., “Summarize what I worked on today and add it to my journal”)

  • Capturing ideas that belong in your ongoing daily record

3. Semantic search for your knowledge base (semantic_search_objects)

Before the AI answers many of your questions, it first checks what you’ve already written.

  • Finds which objects in your Heptabase space are relevant to a topic:

  • Uses a mix of:

    • Full-text search (keywords)

    • Semantic search (meaning-based similarity)

The AI uses this when you:

  • Ask about topics you’ve taken notes on before (e.g., “What are my key takeaways from those machine learning papers?”)

  • Want to rediscover related content (e.g., “Find my project notes on X”)

  • Need the AI to reason using your existing knowledge instead of starting from scratch

Once it identifies useful objects, it can then:

  • Pull the full content with get_object (for deep reading and summarization)

  • Explore the related whiteboards with search_whiteboards and get_whiteboard_with_objects

4. Find whiteboards by topic (search_whiteboards)

Whiteboards are where you visually organize related ideas. The AI can search them too.

  • Searches your whiteboards by:

    • Names and titles

    • Keywords related to the topic

  • Helps the AI understand how your content is organized:

    • Which whiteboards exist around a project or theme

    • How you’ve grouped related notes visually

  • Especially useful when:

    • You ask to “look at my X project whiteboard”

    • You want the AI to understand your workspace structure, not just individual notes

    • Semantic search finds objects that reference interesting whiteboards

After finding relevant whiteboards, the AI can use get_whiteboard_with_objects to see what’s actually on them.

5. Understand a Whiteboard in Context (get_whiteboard_with_objects)

See the structure and relationships on a whiteboard.

  • Returns the full structure of a whiteboard:

    • Cards placed on the board

    • Sections and text elements

    • Mindmaps, images, and their relationships

  • Includes partial content for many objects, so the AI can:

    • See how ideas are grouped

    • Understand which cards belong to which topic

    • Follow the flow of your thinking on that board

The AI uses this when:

  • It already knows which whiteboard to look at (from search_whiteboards or semantic_search_objects)

  • You want help understanding or reorganizing a complex board

  • You ask for summaries, overviews, or insights based on how you’ve arranged things visually, not just on a single note

If the AI needs more detail about a specific card or object on the whiteboard, it can then call get_object for a deeper read.

6. Deep Dive into a Single Object (get_object)

Read the full content of a specific object.

  • Can retrieve full content for:

    • Note cards (regular text notes)

    • Journals

    • Media cards (video, audio, image cards) and their transcripts

    • Highlights

    • Whiteboard elements (sections, text elements)

    • Chat-related objects (chat, chat messages, chat message elements)

  • Works without chunk limits:

    • The AI can see the entire object, not just the first part

    • It checks a hasMore flag to know whether it already has all the content

The AI uses this when you:

  • Ask for detailed summaries, translations, or explanations of a specific note

  • Refer to a known object (e.g., “Summarize my note ‘X’,” or “Translate this journal into English.”)

  • Need precise answers based on the full content, not just a snippet

Note: The AI avoids using get_object on very large PDF cards, since those can be too big to read entirely at once.

7. Review Past Journals by Date Range (get_journal_range)

Look back over your journals for a specific period

Sometimes you don’t just want “today’s” journal — you want to see what you were thinking over a stretch of days, weeks, or months.

  • Retrieves all daily journal entries between a start date and an end date (both inclusive).

  • Returns the complete content of each journal entry in that period.

  • Perfect for:

    • Reviewing what you worked on over the last week or month

    • Preparing summaries or retrospectives based on your past notes

Constraints & behavior

  • Each request can cover up to roughly three months of journals.

  • For longer time ranges (e.g., a whole year), the AI will split it into multiple calls behind the scenes.

You can prompt the AI with things like:

  • “Show me everything I wrote in my journal last month.”

  • “Summarize my journals from 2025-01-01 to 2025-03-31.”

8. Search Within Large PDFs (search_pdf_content)

Find what you need inside long PDFs

When you have a big PDF (papers, books, reports), it’s often not practical to read or summarize the whole thing at once. This tool helps the AI zoom in on the relevant parts first.

  • Searches within a specific PDF using keyword-based matching (with fuzzy OR logic).

  • Returns up to 80 ranked chunks that match your keywords.

  • For each hit, it also expands to nearby text, giving more context around the matching sections.

The AI uses this when you:

  • Ask about content inside a particular PDF (e.g., “What does this paper say about regularization?”).

  • Want to find specific information, topics, or terms in a large document.

  • Need a quick way to locate relevant sections before doing a deeper read or summary.

How it works in practice

  • The AI first needs to know which PDF card to search (by using tools like semantic_search_objects or get_object to find the right PDF).

  • Then it calls search_pdf_content with broad, flexible keywords (including synonyms and related terms) to maximize coverage.

  • Once it finds the right regions, it can follow up with get_pdf_pages to pull full pages for summarization or translation.

Example prompts:

  • “Search this PDF for anything related to ‘gradient descent’ and show me the relevant parts.”

  • “Find where this document talks about user research methods.”

9. Read Specific PDF Pages (get_pdf_pages)

Retrieve exact pages from a PDF

Once the AI knows which area of a PDF matters — either from your instructions or from search_pdf_content — it can fetch full pages for deeper analysis.

  • Retrieves the complete content from a given page range.

  • Page numbers are inclusive: from startPageNumber to endPageNumber.

  • Useful for:

    • Summarizing specific chapters or sections

    • Translating certain pages

    • Answering detailed questions about a particular part of a PDF

Behavior & guidelines

  • Page numbers start from 1 (not 0).

  • The AI can retrieve as many pages as needed, typically in reasonable batches:

    • For short sections: “Get pages 5–10.”

    • For longer sections (e.g., >100 pages), the AI may ask you to confirm before pulling everything.

Typical flows:

  • After search_pdf_content:

    • “Now fetch the full content for the pages where those chunks came from and summarize them.”

  • Directly by page:

    • “Get pages 20–25 of this PDF and explain the main ideas.”

Summary

In many real-world tasks, the AI chains multiple tools together for you:

  1. Discover relevant content

    • Use semantic_search_objects to find notes, journals, PDFs, and other objects related to your question.

    • Use search_whiteboards to find whiteboards that organize those objects visually.

  2. Understand structure and context

    • Use get_whiteboard_with_objects to see how cards and ideas are arranged on a whiteboard.

    • Use get_object to fully read any specific note, journal, media card, or other object.

  3. Work with journals over time

    • Use append_to_journal to add new reflections or summaries to today’s journal.

    • Use get_journal_range to review or summarize what you wrote across a period (days, weeks, or months).

  4. Work with large PDFs

    • Use search_pdf_content to locate where relevant topics appear inside long documents.

    • Use get_pdf_pages to pull full pages for summarization, translation, or detailed Q&A.

  5. Save outcomes back into your knowledge base

    • Use save_to_note_card to turn AI outputs into reusable notes in your Inbox.

    • Or use append_to_journal to store them as part of your daily record.

Current known issues:

Last updated: 2025/11/03

  • You might run into errors when trying to use tools on the ChatGPT mobile app.

Related Articles
How to import my notes from other softwares into Heptabase?
Does Heptabase offer a free plan?
How to use deeplinks in Heptabase?
How do I add an image into an AI chat as context?
How to fix “Something went wrong” when using GPT-5 series or Gemini 3 with AI Chat?
Did this answer your question?