Notion Release Notes

Atomic batched content updates in Notion MCP

notion-update-page calls that use the update_content command now apply every content-changing replacement in the batch or none of them. Previously, when one old_str matched no page content and another one in the same call did, the matching replacements were saved and the call returned success — so a batch that removed content in one operation and reinserted it in another could drop that content. These calls now return a validation_error naming the old_str that wasn't found, and the page is left unchanged. Operations whose old_str and new_str are identical are ignored without checking for a match. See Supported tools for the tool's matching rules.

old_str must also be a non-empty string. Empty values were previously ignored, which silently skipped the replacement; they now fail validation on both notion-update-page and Update a page's content as markdown.

Notion Agent APIs in public beta

The Notion Agent APIs are now in public beta. Use sessions to start a chat with a Custom Agent, stream its reply, submit an action, and page through a session's event history, so you can bring Custom Agents into a Slack bot, an internal tool, or a mobile client. The quickstart walks through a first request end to end with a personal access token.

The beta also covers managing Custom Agents programmatically: find the agents a token can reach with Query agents, read per-agent usage with Retrieve agent insights, and set credit limits, enable, disable, or delete agents — individually or in an asynchronous batch.

If you built against the private alpha routes for agents, threads, messages, or chat, see Upgrading to public beta. The replacements take JSON request bodies instead of query parameters and return sessions and events instead of threads and messages. Migrate off the alpha routes by September 30, 2026.

More filters in Notion MCP view tools

The notion-create-view and notion-update-view tools now apply relation, person, status, created by, last edited by, unique ID, last visited, verification, and place filters. Previously, some calls succeeded but saved a view without the requested filter.

Use a page URL or ID for relation filters and a user ID or "me" for person filters. Invalid values now return an error. See Supported tools for accepted values, and read the notion://docs/view-dsl-spec resource for the full configuration syntax.

Verification filters now round-trip through view responses for both matching (status) and non-matching (does_not_equal) conditions. Data source queries accept the same conditions.

Updating the query tool list in Notion MCP

New tool-list responses no longer include notion-query-database-view. Use notion-query-data-sources with mode: "view" for saved views. Clients with a cached tool list can still call notion-query-database-view; those calls continue to work and return migration guidance.

The current_tool_access map returned by notion-fetch with the id self no longer has a query_database_view entry, since the map describes the tools that a current tool list advertises. See Supported tools for the tool list.

Multi-source SQL on Business plans in Notion MCP …

prop() references in formula property writes

Formula expressions submitted through Update a data source now store prop("Property Name") references exactly as written. Previously, the API accepted some expressions but silently rewrote them — most visibly, a reference to a unique ID property dropped the ID's prefix from computed values, and a prop() reference inside an array literal emptied the array. Expressions the API can't store now return a validation_error instead. Formulas saved before this fix keep their old stored expression until you resubmit the update.

Formula properties created through the API also now keep their result type, so number formatting options stay available in Notion and other formulas can reference them with prop().

Readable formula expressions in data source schemas

Retrieve a data source now returns formula expressions using the same prop("Property Name") syntax you write. Expressions that can't be rendered faithfully in this syntax continue to use the internal property reference syntax.

Admin API reference for agents

The Admin API reference now covers the endpoints for managing agents in a workspace: credit usage and limits, permissions, status, creation policy, and workflow metadata.

Filter properties on page writes …

unsupported formula and rollup property values

The API can now return formula and rollup page property values and property item values with type set to "unsupported" and an empty unsupported object. This happens when a value depends on too many related pages or nested formulas and rollups. The response doesn't include a partial value. Treat the property as unavailable. Rollups still include the function field. To make the value available, reduce the number of related pages or simplify the nested formulas and rollups.

JavaScript SDK 5.24.0

We released @notionhq/client v5.24.0. It adds client.blocks.meetingNotes.create() for creating a meeting note, typed unsupported formula and rollup values, and APIErrorCode.InvalidBeta for handling invalid_beta responses.

Clearer per-tool access status

The current_tool_access status previously called limited_free_trial is now available_with_limit. The new name makes clear that a tool is available until the usage limit included with the workspace's plan is reached. This is a naming and description update only; it does not change tool availability or usage limits.

Fetch documentation resources with the fetch tool

The Notion MCP fetch tool now accepts notion://docs/* URIs (for example, notion://docs/enhanced-markdown-spec) and returns the same content as the MCP resource of the same URI. This gives MCP clients that cannot read MCP resources a way to load the specs referenced in tool descriptions.

Per-tool access map in notion-fetch self

The notion-fetch MCP tool's self response now includes a current_tool_access map, so clients can tell before making a call which tools will actually run on the connected workspace's plan and which would only return an upgrade prompt. Each entry's status is available, limited_free_trial (calls succeed via a free or metered trial allowance), upgrade_required (the entry also carries an upgrade_url into the workspace's upgrade flow), or not_enabled. See Integrating your own MCP client.

New identity fields in OAuth token responses

User objects now include an email_verified boolean next to person.email, indicating whether Notion has verified that email address. The field appears anywhere person emails do, including the owner in OAuth token responses and List all users results.

Notion MCP token responses now include top-level user_id, workspace_id, and email_domain fields on successful authorization-code exchanges, so MCP clients can associate a connection with a Notion user and workspace without an extra call. See Integrating your own MCP client.

New response fields like these are backwards-compatible additions and appear on every API version. Parse responses leniently: ignore fields you don't recognize rather than rejecting them.

Notion app links in API responses use the new app domain …