Browse docs

Agent (MCP)

Connect any MCP client — Claude Code, Cursor, Codex — to Post Notion, then publish pages and pull reviews without leaving your agent.

Add the server

Post Notion ships as a local MCP server that installs to ~/.post-notion/. Once it's on disk (see Local MCP for the one-time install), point your client at it.

Register the server, then run /mcp in a Claude Code session to confirm it connected.

terminal
claude mcp add post-notion --scope user \
  -- node ~/.post-notion/post-notion-mcp.js

Full reference

Local MCP covers the install, every environment variable, the config file, and the complete tool list.

Authenticate

The first call tells you whether you're signed in. Auth is a one-time device-code flow — approve it in the browser and the key is cached locally.

  1. 1In your agent, call health_check. If it returns needs_auth, call auth_status.
  2. 2auth_status returns a verificationUrl and a deviceCode. Open the URL, sign in to Post Notion, and approve access.
  3. 3Call complete_auth with the deviceCode. Your key is saved to ~/.post-notion/config.json.
  4. 4Call health_check again — it should report ok with the active endpoints.

Publish your first page

Ask your agent, in plain language, to publish something. It renders HTML and calls push_doc, and you get back a link you can open on any device.

agent side
// The agent calls push_doc with your HTML
const { url } = await push_doc({
  page: "Specs",
  slug: "product-spec",
  title: "Product spec",
  html,
});
// → https://postnotion.com/p/product-spec

Pull the review

After you comment on the page, the agent pulls the feedback back — as threads it can act on, resolve, and answer — then pushes the next version to the same slug.

agent side
const threads = await pull_threads({ slug: "product-spec" });
// address the comments, then:
await set_status({ slug: "product-spec", status: "needs review" });
await push_doc({ slug: "product-spec", title: "Product spec", html });

Next

  • Local MCP: install, config, environment, and the full tool list.
  • Remote MCP: the hosted endpoint, coming soon.
  • MCP tools: every tool with its parameters and schema.
PreviousThe agent as reviewerNextCLI