Draft long documents in Markdown files. Keep Notion for the work you share with a team: task boards, databases, and pages other people comment on. Claude Code can write in both. In a folder it edits the document itself. In Notion it edits a Markdown copy that Notion’s server translates to and from the page.
This comparison comes from Notion’s documentation and from the instructions its MCP server gives to agents, which we read on September 18, 2026. We haven’t run the two setups side by side.
What does Claude Code work on in Notion?
In a folder, Claude Code opens the document. It reads the file and edits the lines it wants to change. It can also search the other files in the folder.
In Notion, it never opens the page. Notion’s MCP server turns the page into Notion-flavored Markdown, Claude edits that text, and the server turns it back into blocks. Each step is a call to Notion’s servers.
Notion built it this way for a reason. Its older server sent pages as hierarchical JSON, and Notion’s engineers wrote that Markdown needs fewer tool calls and costs less. I believe that. It’s still a second format, and the server tells Claude to read the spec before it writes.
Where does Notion’s Markdown differ from the standard?
Most of it looks like the Markdown Claude already writes. The spec lists the differences, and several are things a technical post uses all the time:
- Tables are written with
<table>,<tr>and<td>tags. “Table cells can only contain rich text,” so a cell can’t hold a list or an image. - A quote that runs over several lines needs
<br>tags inside one>line. “Multiple>lines render as separate quote blocks.” - “Plain empty lines are stripped out.” To keep one, you write
<empty-block/>. - “Headings 5 and 6 are converted to heading 4.”
- Outside code blocks, these characters need a backslash:
\ * ~ ` $ [ ] < > { } | ^
The instructions the MCP server gives to agents add a few more. Claude can’t merge table cells; it’s told to say the user “must do it in the UI.” When it reads a page, it’s told to check whether the content came back truncated, and how many blocks were of a type the API doesn’t support yet.
One rule worries me more than the rest. A child page shows up in the text as a <page> tag, and the server’s copy of the spec warns that “removing a <page> block deletes the child page.” Notion guards against it: an update that would delete a child page fails unless the agent sets allow_deleting_content. In a folder, editing one document can’t delete another.
I think Notion has this the wrong way round. Claude Code and Codex were built to work on files, and standard Markdown is the format they know best. Notion asks them to learn its version and to reach every page through its servers. It can’t drop that format without dropping blocks, and blocks are what give Notion its databases, live editing and page permissions. So the cost stays for as long as you write there with your own agent.
What do I give up by writing in files?
| Markdown folder | Notion | |
|---|---|---|
| What Claude Code edits | The file | A Markdown copy, through Notion’s server |
| Finding text | Search across every file on disk | notion-search, limited to 30 requests a minute |
| Record of changes | Git, if you set it up | Page history: 7 days on Free, 30 on Plus, 90 on Business |
| Working with teammates | Share the folder or a repository; no live editing | Live editing, comments, permissions |
| Phone | Depends on how you sync the folder | Notion’s own apps |
The search limit is in Notion’s MCP tool list, and page history is on its pricing page.
If several people edit the same page during the day, files won’t replace that. Git shows each change Claude made, line by line, but someone has to set it up, and most teammates outside engineering won’t open a diff.
Can Notion’s own agent do the writing instead?
Yes, and it skips the translation, because it works on blocks directly. Since August 28, 2026 you can ask it to suggest edits and approve them one at a time. Notion Agent comes with the Business plan, at $20 a seat per month billed monthly.
You can also run Claude inside Notion on the same plans. It’s billed in Notion credits, and Notion’s help page says “using your own Anthropic account isn’t possible.” If you already pay for Claude or ChatGPT, that subscription reaches Notion only from Claude Code or Codex, through MCP.
How do I use both?
Keep the draft in a file and copy it to Notion when people need to read it.
- Draft and revise in the folder with Claude Code.
- When it’s ready for others, ask Claude Code to create a Notion page from the file. Connect Notion first.
- Teammates comment in Notion. Claude Code can read page comments and comments on blocks with the server’s
notion-get-commentstool. - Make the changes in the file, then update the page.
The file stays the original. After the first push, check tables and multi-line quotes on the Notion page, because those are the parts where the two formats differ. If a teammate edits the page directly, have Claude fetch it and show you the differences before it overwrites either side. Hannah Stulberg describes a similar routine in Draft in Claude Code, Collaborate in Notion.
Where does StashBase fit?
If you’re thinking of moving your writing out of Notion altogether, AI-native Notion alternatives compares Palette, StashBase and Obsidian for people who already pay for Claude Code or Codex.
How does StashBase help with writing in files?
StashBase is an open-source app for writing in a local folder with Claude Code, Codex or Antigravity:
- Open a folder of Markdown files. Read and edit a document beside the chat, and review the agent’s file edits.
- Choose Claude Code, Codex or Antigravity from the agent picker and sign in with the subscription you already have. See the agent setup guide.
- PDFs, Word files and images in the folder are prepared as searchable text, so the agent can use them as sources.
It doesn’t sync between devices or offer live editing with teammates. It runs on macOS 12 or later and Windows 10 or later. Download StashBase.
What we checked
We read Notion’s MCP guide, tool list, Markdown spec, pricing, and the help pages for Notion Agent and Claude agents on September 18, 2026. The same day, we read the MCP server’s tool descriptions and its copy of the spec through a Claude connection. We didn’t time either setup or count tokens.