Quick Start

Workers let Custom Agents reach beyond the Notion ecosystem by running your own code to call any external API. This guide walks you through setting up your environment, creating your first Worker, deploying it to Notion, and testing it end to end.

Worker vs MCP

Before diving in, let's clarify the difference between Workers and MCP:

• MCP is "using a bridge someone else built." Notion provides pre-built MCP servers for services like Stripe, GitHub, and Figma — you can connect them with a few clicks, but you're limited to the tools others have defined.
• Worker is "building your own bridge." You define tool behavior in code, with full control over the requests you send, the parameters you pass, and how you handle the responses.

In short: Workers fill the gaps that MCP can't cover. If you want to see Workers in action, check out this hands-on walkthrough.

Prerequisites

Worker development requires the following:

• Node.js >= 22
• npm >= 10.9.2
• A Notion Business plan (Worker access requires a Business subscription)

Once your environment is ready, install the Notion CLI:

npm i -g ntn

Then log in to your Notion workspace:

ntn login

Create Your First Worker

Notion provides an official template repository. Clone it locally to get started:

npx degit makenotion/workers-template my-worker
cd my-worker
npm install

Open src/index.ts and you'll see the project's core structure is straightforward:

import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

worker.tool("sayHello", {
  title: "Say Hello",
  description: "Return a greeting",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" }
    },
    required: ["name"],
    additionalProperties: false
  },
  execute: ({ name }, _context) => `Hello, ${name}`,
});

This is a minimal Worker. It does one thing: takes a name and returns a greeting.

Each tool is a capability the Agent can invoke. Here's what each part does:

• title and description appear in the Notion Agent's tool list and help the Agent understand what the tool is for.
• schema defines the parameters the Agent must provide when calling the tool (in JSON Schema format).
• execute contains the actual logic that runs.

Deploy

Once your code is ready, deploy with a single command:

ntn workers deploy

After deployment, the Worker's tools will automatically appear in the Custom Agent tool list within your Notion workspace.

If your Worker needs sensitive information like API keys, set them as environment variables:

ntn workers env set API_KEY=your-api-key

Access them in your code via process.env.API_KEY.

Test

After deploying, you can test your tools directly from the command line:

# Test the deployed remote Worker
ntn workers exec sayHello -d '{"name": "World"}'

# Test locally (no deployment needed; .env files are loaded automatically)
ntn workers exec sayHello --local -d '{"name": "World"}'

Local testing is ideal during development — edit your code and run it immediately without redeploying each time.

OAuth Integration

If your Worker needs to act on behalf of a user with a third-party service (e.g., posting tweets or managing GitHub repos), you'll need to configure OAuth:

const myOAuth = worker.oauth("myOAuth", {
  name: "my-provider",
  authorizationEndpoint: "https://provider.example.com/oauth/authorize",
  tokenEndpoint: "https://provider.example.com/oauth/token",
  scope: "read write",
  clientId: "your-client-id",
  clientSecret: process.env.MY_OAUTH_SECRET ?? "",
});

After deploying a Worker with OAuth, you also need to configure the callback URL on the third-party platform. Run the following command to get the redirect URL assigned by Notion:

ntn workers oauth show-redirect-url

Then enter this URL in the third-party platform's OAuth application settings.

Debugging

Once your Worker is deployed, use ntn workers runs to view execution history and logs:

# List recent runs
ntn workers runs list

# View detailed logs for a specific run
ntn workers runs logs <runId>

# Quickly view logs from the most recent run
ntn workers runs list --plain | head -n1 | cut -f1 | xargs -I{} ntn workers runs logs {}

The --plain flag outputs plain text, making it easy to pipe into other commands for further processing.

To troubleshoot CLI configuration issues, run:

ntn debug

Feature Availability

Workers are currently in Alpha. Here's the status of each feature:

• ✅ Agent Tools — Public; this is the core functionality covered in this guide
• ✅ OAuth (User Management) — Public; used to connect third-party services that require authorization
• 🔧 OAuth (Notion Management) — In private beta
• 🔧 Syncs (Data Synchronization) — In private beta
• 🔧 Automations — In private beta

Workers are free to use during the Alpha phase. Pricing for the general release has not been announced.

Next Steps

Now that your environment is set up and you understand the basics, you can:

• Read Worker in Practice: Automated Blog Publishing for a complete real-world example
• Try wrapping your frequently used third-party APIs as Worker tools
• Visit the Custom Agent docs to learn how to add Worker tools to your Agent