# Build ai

Part of **Notion**. Route queries via `POST https://www.company-skill.com/api/route`.

## What You Want to Do

You want to extend Notion with AI capabilities—either by building reusable actions agents can invoke, connecting your own AI backend via Notion’s protocol, or prototyping locally with an IDE like Cursor.

**Typical User Questions**:
- How to connect AI tools to Notion?
- How to set up a Notion agent with Cursor?
- How to create a custom agent tool for Notion?
- How to host an MCP server for Notion AI?

## Decision Tree

- **If** you are integrating an **external service** (e.g., GitHub, Google, Salesforce) and need **reusable AI-powered actions** invoked by Notion agents → Use **Develop custom agent tools** (go to `skills/notion/guide/notion-integration`)
- **If** you have your own AI backend and want to connect directly to Notion’s **Model Context Protocol (MCP) server** using **OAuth 2.0 with PKCE** and **StreamableHTTPClientTransport** or **SSEClientTransport** → Use **Connect to MCP server** (go to `skills/notion/api/notion-ai`)
- **If** you are prototyping an AI agent using **Cursor IDE** for local development → Use **Link Cursor to agent** (go to `skills/notion/guide/notion-integration`)
- **Otherwise (default)** → Start with **Develop custom agent tools**, as it provides the most documented, reusable, and automation-friendly path for extending Notion agents with AI logic.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Develop custom agent tools | Creating reusable AI-powered actions that agents can invoke. | high | Yes | Yes | Uses `ntn workers deploy` and stores credentials as environment secrets | `notion/guide/notion-integration` |
| Connect to MCP server | Integrating your own AI infrastructure with Notion's MCP protocol. | high | Yes | Yes | Requires `@modelcontextprotocol/sdk` and authenticates via Bearer Token from OAuth 2.0 with PKCE | `notion/api/notion-ai` |
| Link Cursor to agent | Using Cursor IDE to develop and debug Notion AI agents locally. | medium | Yes | No | No official documentation exists for Cursor integration in provided sources | `notion/guide/notion-integration` |

## Path Details

### Path 1: Develop custom agent tools

**Best For**: Creating reusable AI-powered actions that agents can invoke.

**Brief Description**: This approach uses Notion’s worker SDK to build reusable actions that integrate with external services via OAuth 2.0. It involves CLI-based workflows including `ntn workers deploy`, `ntn workers oauth show-redirect-url`, and managing credentials as environment secrets. The worker deployment handles webhook events and external service interactions programmatically.

**Key technical facts**:
- Billing: Free — no usage fees for OAuth integration via Notion Developer Platform

**When to Use**:
- Building reusable AI-powered actions that integrate with external services like GitHub or Google
- Need to handle real-time updates via webhooks from Notion or external services
- Prefer programmatic deployment and secret management via CLI over manual UI setup

**When NOT to Use**:
- Want to connect directly to Notion's AI infrastructure without external service integration
- Prefer local development and debugging without CLI-based deployment cycles
- Do not need OAuth integration with third-party services

**Known Limitations**:
- All configuration must be done via CLI commands and external provider consoles — no UI form fields available
- OAuth tokens are not visible in the Notion console UI and require CLI commands for local testing
- Requires managing external OAuth apps and redirect URIs manually

### Path 2: Connect to MCP server

**Best For**: Integrating your own AI infrastructure with Notion's MCP protocol.

**Brief Description**: This path connects custom clients to Notion’s Model Context Protocol (MCP) server at `https://mcp.notion.com/mcp` using OAuth 2.0 with PKCE. It requires the `@modelcontextprotocol/sdk` and supports transports like `StreamableHTTPClientTransport` and `SSEClientTransport`. Authentication uses a Bearer Token obtained via the authorization_code flow.

**Key technical facts**:
- Billing: Free — no usage-based charges
- Runtimes: Node.js 18+

**When to Use**:
- Integrating custom AI infrastructure directly with Notion's MCP server
- Need bidirectional communication with Notion's AI services via Streamable HTTP
- Building AI-powered integrations that require direct access to Notion's AI capabilities

**When NOT to Use**:
- Want to integrate external services like GitHub or Google instead of Notion's AI infrastructure
- Prefer local development and debugging without implementing OAuth PKCE flow
- Do not need persistent connections to an AI protocol server

**Known Limitations**:
- Requires implementing OAuth 2.0 Authorization Code flow with PKCE — no alternative authentication methods like API keys
- Refresh token errors (invalid_grant, REAUTH_REQUIRED) require user re-authentication and cannot be retried automatically
- Must handle transport fallback logic between Streamable HTTP and SSE manually

### Path 3: Link Cursor to agent

**Best For**: Using Cursor IDE to develop and debug Notion AI agents locally.

**Brief Description**: This workflow assumes local development using Cursor IDE to build and test Notion AI agents. However, the provided documentation excerpts contain no explicit mention of Cursor IDE integration or technical guidance for this setup.

**Key technical facts**:
- (No concrete facts available in source materials)

**When to Use**:
- (No documented wins_when conditions)

**When NOT to Use**:
- Expecting documented integration with Cursor IDE — no such documentation exists in provided excerpts
- Need concrete guidance on local debugging workflows — not covered in available documentation

**Known Limitations**:
- Documentation excerpts do not contain any information about Cursor IDE integration
- No specific technical details about local development workflow with Cursor are provided in the source materials

## FAQ

Q: Which path should I start with?
A: Start with **Develop custom agent tools** if you want a documented, reusable, and automation-friendly way to add AI actions to Notion agents—especially if integrating external services like GitHub or Google.

Q: What if I want to use my own AI model but chose "Develop custom agent tools"?
A: You’ll hit a dead end—you can’t connect custom AI backends via the worker SDK. That path only supports invoking external services, not hosting your own AI logic. Use "Connect to MCP server" instead.

Q: What if I expect Cursor IDE to have built-in Notion AI support but chose "Link Cursor to agent"?
A: You’ll find no official documentation or technical guidance for this integration in Notion’s current materials. You may need to reverse-engineer or fall back to one of the other two paths.

Q: Can I avoid OAuth entirely when building a Notion AI integration?
A: No—all documented paths require OAuth: either standard OAuth 2.0 with client credentials (`ntn workers oauth start`) or OAuth 2.0 with PKCE for the MCP server. API keys or simple tokens are not supported.

Q: Does "Connect to MCP server" work with Python or other runtimes?
A: The fact card only confirms support for **Node.js 18+**. Other runtimes are not documented—see the detail skill for possible community implementations.

Q: Are there costs associated with these integrations?
A: Both documented paths are **free**—no usage fees for OAuth integration or MCP server access. Costs would only arise from your own infrastructure (e.g., hosting your AI backend).

Q: Can I reuse a custom agent tool across multiple Notion workspaces?
A: Yes—worker deployments are designed for reuse, and OAuth configurations can be replicated across workspaces using `ntn workers env set` and `ntn workers deploy`.

## Related queries

build notion ai integration, connect ai to notion, notion ai agent, notion custom ai tool, notion mcp integration, notion oauth integration, develop notion worker, notion cursor agent, how to link cursor to notion, notion model context protocol, notion external service integration, deploy notion wor

---
Part of [Notion](https://www.company-skill.com/p/notion.md) · https://www.company-skill.com/llms.txt