Jul 8, 2026

Build a Multi-user Notion Knowledge & Task Agent with Claude and Scalekit

Founding Developer Advocate

TL;DR

A single Python Claude agent can both answer questions from a Notion workspace and manage task databases inside it, because Scalekit's Notion connector exposes read and write tools on the same per-user connection.
User connects Notion once through OAuth; Scalekit vaults the token and refreshes it.
Your agent calls ^{list_scoped_tools} to get the Notion tools that specific connected account is authorized to call, in Anthropic's native format, no schema writing.
Standard Claude tool-use loop: Claude decides what to call, your code calls ^execute_tool with a user identifier, Scalekit makes the Notion API call as that specific user.
The connector has no webhooks, so this agent is interactive by design: it acts when a user asks, not when a page changes.

Somebody on the team wires a Claude agent to Notion using an internal integration token pasted into .env. It searches the wiki. Ask it where the incident runbook lives, and it finds the page and reads it back. Reasonable enough: the token belongs to whoever created the integration, so every search runs with that person's own workspace access.

Then somebody asks it to create a task. Then a second teammate starts using it.

Two failures now, precisely. Tasks the agent creates show up owned by nobody real, because the token has no identity of its own to assign work to. And the second teammate's searches return pages the first teammate shared with the integration, not the pages the second teammate can actually see in their own Notion account. Nobody made a bad decision here. This is what happens when a knowledge tool and a task tool get bolted onto the same static token instead of a real per-user connection.

Prerequisites

Python 3.9+
^{pip install anthropic scalekit-sdk-python python-dotenv}
A Scalekit account with a Notion connection configured (Notion connector setup)
A Notion account with at least one page or database shared with your integration, since Notion's consent screen requires the user to explicitly pick what the integration can see

What a Notion Workspace Agent Actually Needs to Do

Most "Notion agent" tutorials pick one job: search the wiki, or manage a task board. Real usage doesn't split that cleanly. The same person who asks "what's our refund policy" also wants "mark the API redesign task as in review and assign it to Maya" answered in the same conversation, against the same workspace, under the same permissions.

That's two Notion capabilities riding on one connected account: retrieval (search, read pages, query databases) and action (create pages, insert database rows, update properties, append content). Scalekit's Notion connector exposes both from the same OAuth connection, so the agent doesn't need two separate integrations or two separate tokens to do both jobs.

Recommended Reading: Notion MCP vs Notion API for AI Agents covers why background agents need the direct API path this post uses, rather than Notion's hosted MCP server, which requires a browser-based OAuth flow and can't run headlessly.

How It Fits Together

Your code never talks to Notion directly. It talks to Scalekit. Scalekit handles the Notion OAuth flow, token storage, and refresh on behalf of each user, and returns only the tools that user's connected account is authorized to call.

The flow is the same as every other Scalekit-backed Claude agent: a user connects their Notion account once, your agent calls list_scoped_tools to get that user's authorized tool surface in Anthropic's native format, and then Claude runs its normal tool-use loop, deciding what to call while your code executes each call through execute_tool with the user's identifier attached. Notion never sees your code. Your code never sees a Notion access token.

The Agent Script

The complete agent. Copy it, set your environment variables, and run it.

""" Claude agent with Scalekit-authenticated Notion tools. """ import os import anthropic import scalekit.client from dotenv import find_dotenv, load_dotenv from google.protobuf.json_format import MessageToDict load_dotenv(find_dotenv()) scalekit_client = scalekit.client.ScalekitClient( client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), ) actions = scalekit_client.actions client = anthropic.Anthropic( base_url=os.getenv("ANTHROPIC_BASE_URL"), api_key=os.getenv("ANTHROPIC_API_KEY"), ) # The connection_name below must match exactly what you named # the Notion connection in the Scalekit dashboard (Agent Auth > Connections). identifier = os.getenv("USER_IDENTIFIER", "user_123") response = actions.get_or_create_connected_account( connection_name="notion", identifier=identifier, ) if response.connected_account.status != "ACTIVE": link = actions.get_authorization_link(connection_name="notion", identifier=identifier) print("Authorize Notion:", link.link) print("Re-run this script after completing the OAuth flow.") exit(0) scoped_response, _ = actions.tools.list_scoped_tools( identifier=identifier, filter={"connection_names": ["notion"]}, ) llm_tools = [ { "name": MessageToDict(tool.tool).get("definition", {}).get("name"), "description": MessageToDict(tool.tool).get("definition", {}).get("description", ""), "input_schema": MessageToDict(tool.tool).get("definition", {}).get("input_schema", {}), } for tool in scoped_response.tools ] print(f"Connected account for {identifier} is active.") print(f"Discovered {len(llm_tools)} tools") messages = [ { "role": "user", "content": ( "Search our workspace for the Q3 launch checklist page, then create a task " "in the Launch Tasks database for each item on the checklist that isn't done yet." ), } ] while True: response = client.messages.create( model=os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-6"), max_tokens=1024, tools=llm_tools, messages=messages, ) if response.stop_reason == "end_turn": print(response.content[0].text) break tool_results = [] for block in response.content: if block.type == "tool_use": result = actions.execute_tool( tool_name=block.name, identifier=identifier, tool_input=block.input, ) tool_results.append( { "type": "tool_result", "tool_use_id": block.id, "content": str(result.data), } ) messages.append({"role": "assistant", "content": response.content}) messages.append({"role": "user", "content": tool_results})

Run it

Environment variables:

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.cloud SCALEKIT_CLIENT_ID=skc_... SCALEKIT_CLIENT_SECRET=sks_... USER_IDENTIFIER=user_123 ANTHROPIC_API_KEY=sk-ant-... python agent.py

Expected output:

Connected account for user_123 is active. Discovered 21 tools [Tool calls happen here] Found the Q3 launch checklist. Created 4 tasks in Launch Tasks for the unchecked items: "Finalize pricing page," "Send press embargo," "QA onboarding flow," "Update status page copy."

(Exact tool count and output will vary depending on which capabilities are enabled on your Notion connection. Run it against your own workspace to see your data.)

What Your Agent Can Do

These workflows show the range of tasks the agent handles once a Notion account is connected. Each starts with a natural language prompt and ends with a concrete Notion action, either a retrieval or a write.

Knowledge retrieval

"Where's our incident escalation process?"

The agent calls notion_page_search to find the matching page, then notion_page_content_get to pull its blocks and answer from the actual content, not just the title.

"Find the Q3 planning doc and tell me what's still undecided"

The agent calls notion_data_fetch against the workspace search endpoint, then notion_page_get and notion_page_content_get to read the page before summarizing.

Task tracking

"What's assigned to me and still open?"

The agent calls notion_database_query (or notion_data_source_query if the database has multiple data sources) with a filter on the Assignee and Status properties.

"Add a task 'Draft launch email' due Friday to the Marketing database"

The agent calls notion_database_insert_row with the title and due date as property values.

"Move the API redesign task to In Review and reassign it to Maya"

The agent calls notion_page_update, passing a properties object that sets the Status and Assignee fields on that page.

"Drop a note on that task with the three blockers"

The agent calls notion_page_content_append to add the note as page content, or notion_comment_create if it belongs as a discussion comment instead.

Both at once

"Find our onboarding checklist and create a task in the Onboarding Tasks database for each unchecked item"

This is the default prompt in the agent script above, and it's the workflow that justifies merging the two roles into one agent. The agent calls notion_page_search, reads the checklist with notion_page_content_get, then calls notion_database_insert_row once per unchecked item. One connected account, one conversation, both capabilities.

Available Notion Tools

Category

Tool

Description

Search

^{notion_data_fetch}

Full-text search across the workspace via Notion's /search endpoint

Search

^{notion_page_search}

Search pages by text query, with sort and pagination

Pages

^{notion_page_create}

Create a page as a database row or as a child of another page

Pages

^{notion_page_get}

Retrieve a page's properties and metadata by ID

Pages

^{notion_page_update}

Update a page's properties, archive it, or change icon and cover

Pages

^{notion_page_content_get}

Retrieve a page's child blocks and their text content

Pages

^{notion_page_content_append}

Append new blocks (paragraph, heading, list, code, and more) to a page

Databases

^{notion_database_create}

Create a new database under a parent page, with a defined property schema

Databases

^{notion_database_fetch}

Retrieve a database's title, properties, and schema

Databases

^{notion_database_query}

Query rows from a single-source database, with filters and sorts

Databases

^{notion_database_insert_row}

Insert a new row (page) into a database

Databases

^{notion_database_update}

Update a database's title, description, or property schema

Databases

^{notion_database_property_retrieve}

Query a database and return only specific properties, to limit payload

Data sources

^{notion_data_source_fetch}

Retrieve schema and data_source_id for merged or multi-source databases

Data sources

^{notion_data_source_query}

Query rows from a multi-source database using its data_source_id

Data sources

^{notion_data_source_insert_row}

Insert a row into a multi-source database using its data_source_id

Blocks

^{notion_block_update}

Update the text of an existing block (paragraph, heading, quote, code, and more)

Blocks

^{notion_block_delete}

Archive a block and all of its child blocks

Comments

^{notion_comment_create}

Add a comment to a page or reply in an existing discussion thread

Comments

^{notion_comment_retrieve}

Retrieve a single comment by ID

Comments

^{notion_comments_fetch}

List comments on a given page or block

Users

^{notion_user_list}

List people and bots in the Notion workspace

Full parameter list in the Notion connector docs.

The Notion-Specific Gotchas You Need to Know

Notion's API has more sharp edges than most connectors in this series. These are the ones that actually bite when Claude is the one constructing the parameters.

Property keys are exact, and the title field is always "title"

notion_database_insert_row and notion_page_update both take a properties object keyed by the exact property name in the target database, case-sensitive. A database column labeled "Status" will not accept a status key. The title property is the one exception that trips up even careful implementations: regardless of what the column is displayed as in the Notion UI, the property key in the API payload must literally be title. Call notion_database_fetch first to read the real schema before writing, rather than guessing property names from what's visible on screen.

Multi-source databases need a different set of tools entirely

Notion's 2025-09-03 API introduced data sources to support merged and synced databases, and the older notion_database_query and notion_database_insert_row tools use the pre-2025 endpoints that don't understand them. If a query against a multi-source database returns an "Invalid request URL" error, that's the signal: call notion_data_source_fetch with the database_id to get the data_source_id, then use notion_data_source_query or notion_data_source_insert_row instead. Standard single-source databases work fine with the classic tools. You only hit this if the database has been merged or synced.

Appending content and updating a block use different formats

notion_page_content_append takes a simplified format: a list of objects with type and text fields, which the tool converts into Notion's block structure internally. notion_block_update, by contrast, edits a specific existing block by ID and expects the block type to match what's already there. Neither tool accepts raw Notion API block objects with rich_text arrays. Passing the wrong shape to either tool is a common first-run failure.

A "page not found" error might mean "not shared with you"

Notion's OAuth consent screen makes the user pick which pages and databases the integration can access, and API calls to anything outside that selection return the same "object not found" error Notion returns for pages that genuinely don't exist. There's no separate "permission denied" response to distinguish the two cases. If the agent reports it can't find a page you know exists, the workspace owner likely needs to re-run the connection and share that page or database during the consent step.

The agent is interactive, not event-driven

The Notion connector has no webhook support. This agent answers when a user asks something; it does not watch the workspace and act automatically when a page changes or a database row updates. If your use case needs the agent to react the moment a task's status changes rather than waiting to be asked, that's a background job checking notion_database_query on a schedule, not a workspace event the connector can push to you.

Notion is bring-your-own-credentials, not managed OAuth

Unlike connectors that work out of the box with Scalekit-managed OAuth, Notion requires you to register your own public integration in the Notion Developer Hub, with a redirect URI pointed at Scalekit and your own Client ID and Secret entered into the Scalekit dashboard. Your users will see your app's name, not Scalekit's, on the Notion consent screen. Plan for this during setup, not after your first user tries to connect.

Why This Already Handles Multiple Users

The USER_IDENTIFIER environment variable, the identifier value in the code, is what makes this agent work for more than one person without changing a line of it. Swap the identifier and the exact same script operates against a completely different person's Notion workspace, seeing only the pages and databases that person shared and writing tasks under their own connected account.

In production, resolve the identifier from your authenticated session, whether that's a cookie, a JWT, or a database lookup, and never accept it from client input. What the user can't see in Notion, the agent can't see either. Scope comes from the connected account, not from anything your code decides at request time.

For the full pattern behind this, see access control for multi-tenant AI agents.

Explore More

Other connectors: Slack, Monday.com, Gmail, Linear, GitHub, HubSpot, and more: full connector list

Other frameworks: LangChain, Mastra, CrewAI, Vercel AI SDK, Google ADK: framework examples

No items found.

On this page

Introduction
‍

This is some text inside of a div block.

Build a Multi-user Notion Knowledge & Task Agent with Claude and Scalekit

TL;DR

Prerequisites

What a Notion Workspace Agent Actually Needs to Do

How It Fits Together

The Agent Script

Run it

What Your Agent Can Do

Available Notion Tools

The Notion-Specific Gotchas You Need to Know

Property keys are exact, and the title field is always "title"

Multi-source databases need a different set of tools entirely

Appending content and updating a block use different formats

A "page not found" error might mean "not shared with you"

The agent is interactive, not event-driven

Notion is bring-your-own-credentials, not managed OAuth

Why This Already Handles Multiple Users

Explore More

Acquire enterprise customers with zero upfront cost