# Notion — how to use (mcp.ai)

Notion via linguagem natural: crie, busque e edite páginas, notas, tarefas, wiki, documentos e bancos de dados, organizando seus projetos. Plataforma fornece a aplicação OAuth, você só clica em Conectar e autoriza seu workspace Notion. Vários workspaces podem ser conectados no mesmo MCP.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_notion?ms=1787528400000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `notion_add_multiple_page_content`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/notion`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/notion/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/notion/add/multiple/page/content` — Efficiently adds multiple standard content blocks to a notion page in a single api call with automatic markdown parsing. the 'content' field in notionrichtext blocks now automatically detects and pars
  - body: { after?: string, content_blocks: object[], parent_block_id: string }
- `POST https://api.mcp.ai/api/notion/add/page/content` — Deprecated: appends a single content block to a notion page or a parent block (must be page, toggle, to-do, bulleted/numbered list, callout, or quote); invoke repeatedly to add multiple blocks.
  - body: { after?: string, content_block: object, parent_block_id: string }
- `POST https://api.mcp.ai/api/notion/append/block/children` — Appends complex blocks with full notion block structure to a parent block or page. use for advanced scenarios requiring precise control: code blocks, tables, embeds, nested children within blocks, or 
  - body: { after?: string, block_id: string, children: object[] }
- `POST https://api.mcp.ai/api/notion/archive/notion/page` — Archives (moves to trash) or unarchives (restores from trash) a specified notion page.
  - body: { archive?: boolean, page_id: string }
- `POST https://api.mcp.ai/api/notion/create/comment` — Adds a comment to a notion page (via `parent page id`) or to an existing discussion thread (via `discussion id`); cannot create new discussion threads on specific blocks (inline comments).
  - body: { comment: object, discussion_id?: string, parent_page_id?: string }
- `POST https://api.mcp.ai/api/notion/create/database` — Creates a new notion database as a subpage under a specified parent page with a defined properties schema; use this action exclusively for creating new databases.
  - body: { title: string, parent_id: string, properties: object[] }
- `POST https://api.mcp.ai/api/notion/create/notion/page` — Creates a new empty page in a notion workspace.
  - body: { icon?: string, cover?: string, title: string, parent_id: string }
- `POST https://api.mcp.ai/api/notion/delete/block` — Archives a notion block, page, or database using its id, which sets its 'archived' property to true (like moving to "trash" in the ui) and allows it to be restored later.
  - body: { block_id: string }
- `POST https://api.mcp.ai/api/notion/duplicate/page` — Duplicates a notion page, including all its content, properties, and nested blocks, under a specified parent page or workspace.
  - body: { title?: string, page_id: string, parent_id: string }
- `POST https://api.mcp.ai/api/notion/fetch/block/contents` — Retrieves a paginated list of direct, first-level child block objects along with contents for a given parent notion block or page id; use block ids from the response for subsequent calls to access dee
  - body: { block_id: string, page_size?: integer, start_cursor?: string }
- `POST https://api.mcp.ai/api/notion/fetch/block/metadata` — Fetches metadata for a notion block (or page, as pages are blocks) using its valid uuid; if the block has children, use fetch block contents to fetch their contents.
  - body: { block_id: string }
- `POST https://api.mcp.ai/api/notion/fetch/comments` — Fetches unresolved comments for a specified notion block or page id.
  - body: { block_id: string, page_size?: integer, start_cursor?: string }
- `POST https://api.mcp.ai/api/notion/fetch/data` — Fetches notion items (pages and/or databases) from the notion workspace, use this to get minimal data about the items in the workspace with a query or list all items in the workspace with minimal data
  - body: { query?: string, get_all?: boolean, get_pages?: boolean, page_size?: integer, get_databases?: boolean }
- `POST https://api.mcp.ai/api/notion/fetch/database` — Fetches a notion database's structural metadata (properties, title, etc.) via its `database id`, not the data entries; `database id` must reference an existing database.
  - body: { database_id: string }
- `POST https://api.mcp.ai/api/notion/fetch/row` — Retrieves a notion database row's properties and metadata; use fetch block contents for page content blocks.
  - body: { page_id: string }
- `POST https://api.mcp.ai/api/notion/get/about/me` — Retrieves the user object for the bot associated with the current notion integration token, typically to obtain the bot's user id for other api operations.
- `POST https://api.mcp.ai/api/notion/get/about/user` — Retrieves detailed information about a specific notion user, such as their name, avatar, and email, based on their unique user id.
  - body: { user_id: string }
- `POST https://api.mcp.ai/api/notion/get/page/property/action` — Call this to get a specific property from a notion page when you have a valid `page id` and `property id`; handles pagination for properties returning multiple items.
  - body: { page_id: string, page_size?: integer, property_id: string, start_cursor?: string }
- `POST https://api.mcp.ai/api/notion/insert/row/database` — Creates a new page (row) in a specified notion database.
  - body: { icon?: string, cover?: string, properties?: object[], database_id: string, child_blocks?: object[] }
- `POST https://api.mcp.ai/api/notion/list/users` — Retrieves a paginated list of users (excluding guests) from the notion workspace; the number of users returned per page may be less than the requested `page size`.
  - body: { page_size?: integer, start_cursor?: string }
- `POST https://api.mcp.ai/api/notion/query/database` — Queries a notion database for pages (rows), where rows are pages and columns are properties; ensure sort property names correspond to existing database properties.
  - body: { sorts?: object[], page_size?: integer, database_id: string, start_cursor?: string }
- `POST https://api.mcp.ai/api/notion/retrieve/comment` — Tool to retrieve a specific comment by its id. use when you have a comment id and need to fetch its details.
  - body: { comment_id: string }
- `POST https://api.mcp.ai/api/notion/retrieve/database/property` — Tool to retrieve a specific property object of a notion database. use when you need to get details about a single database column/property.
  - body: { database_id: string, property_id: string }
- `POST https://api.mcp.ai/api/notion/search/notion/page` — Searches notion pages and databases by title; an empty query lists all accessible items, useful for discovering ids or as a fallback when a specific query yields no results.
  - body: { query?: string, direction?: string, page_size?: integer, timestamp?: string, filter_value?: string, start_cursor?: string, filter_property?: string }
- `POST https://api.mcp.ai/api/notion/update/block` — Updates an existing notion block's textual content or type-specific properties (e.g., 'checked' status, 'color'), using its `block id` and the specified `block type`.
  - body: { content: string, block_id: string, block_type: string, additional_properties?: object }
- `POST https://api.mcp.ai/api/notion/update/page` — Tool to update the properties, icon, cover, or archive status of a page. use when you need to modify existing page attributes.
  - body: { icon?: object, cover?: object, page_id: string, archived?: boolean, properties?: object }
- `POST https://api.mcp.ai/api/notion/update/row/database` — Updates or archives an existing notion database row (page) using its `row id`, allowing modification of its icon, cover, and/or properties; ensure the target page is accessible and property details (n
  - body: { icon?: string, cover?: string, row_id: string, delete_row?: boolean, properties?: object[] }
- `POST https://api.mcp.ai/api/notion/update/schema/database` — Updates an existing notion database's title, description, and/or properties; at least one of these attributes must be provided to effect a change.
  - body: { title?: string, properties?: object[], database_id: string, description?: string }

## Example prompts
- "Crie uma página 'Notas da reunião' com os tópicos de hoje"
- "Busque páginas que mencionam 'roadmap Q3'"
- "Adicione um item na database de tarefas com prazo amanhã"

## More
- Page: https://mcp.ai/notion
- Agent spec (llms.txt): https://mcp.ai/notion/llms.txt
- Postman collection: https://mcp.ai/notion/postman.json