---
title: Notion
description: Search and edit Notion pages and databases over MCP or OpenAPI.
type: connection
keywords:
  - mcp
  - openapi
  - docs
  - wiki
  - knowledge base
  - connect
---

# Notion

Connection integration for eve. Search and edit Notion pages and databases over MCP or OpenAPI.

## Install

Add the connection from eve's registry. This writes the initial definition under `agent/connections/` and installs its authentication dependency when needed:

```bash
eve add connection/notion
```

## Quick start

### MCP · User

Create `agent/connections/notion.ts`. The connection name is derived from the filename:

```ts
// agent/connections/notion.ts
import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";

export default defineMcpClientConnection({
  url: "https://mcp.notion.com/mcp",
  description: "Notion workspace: search and edit pages and databases.",
  auth: connect("notion"),
});
```

Connect owns the OAuth flow, and each end-user authorizes in their own browser before their first tool call.

### MCP · App

Create `agent/connections/notion.ts`. The connection name is derived from the filename:

```ts
// agent/connections/notion.ts
import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";

export default defineMcpClientConnection({
  url: "https://mcp.notion.com/mcp",
  description: "Notion workspace: search and edit pages and databases.",
  auth: connect({ connector: "notion", principalType: "app" }),
});
```

Connect authenticates as the agent itself through one shared installation, with no per-user consent.

### MCP · JWT bearer

Create `agent/connections/notion.ts`. The connection name is derived from the filename:

```ts
// agent/connections/notion.ts
import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";

export default defineMcpClientConnection({
  url: "https://mcp.notion.com/mcp",
  description: "Notion workspace: search and edit pages and databases.",
  auth: connect({
    connector: "notion",
    principalToSubject: (principal) => {
      const email = principal.type === "user" ? principal.attributes?.email : undefined;
      if (typeof email !== "string") {
        throw new Error("JWT bearer authentication requires a user principal with an email.");
      }
      return { type: "jwt-bearer", sub: email };
    },
  }),
});
```

Connect exchanges a JWT bearer assertion for a provider token. `principalToSubject` maps each principal to the subject your IdP expects.

### OpenAPI · User

Create `agent/connections/notion.ts`. The connection name is derived from the filename:

```ts
// agent/connections/notion.ts
import { connect } from "@vercel/connect/eve";
import { defineOpenAPIConnection } from "eve/connections";

export default defineOpenAPIConnection({
  spec: "https://developers.notion.com/openapi.json",
  baseUrl: "https://api.notion.com",
  description: "Notion workspace: search and edit pages and databases.",
  auth: connect("notion"),
  headers: () => ({
    "Notion-Version": "2022-06-28",
  }),
});
```

Connect owns the OAuth flow, and each end-user authorizes in their own browser before their first tool call.

### OpenAPI · App

Create `agent/connections/notion.ts`. The connection name is derived from the filename:

```ts
// agent/connections/notion.ts
import { connect } from "@vercel/connect/eve";
import { defineOpenAPIConnection } from "eve/connections";

export default defineOpenAPIConnection({
  spec: "https://developers.notion.com/openapi.json",
  baseUrl: "https://api.notion.com",
  description: "Notion workspace: search and edit pages and databases.",
  auth: connect({ connector: "notion", principalType: "app" }),
  headers: () => ({
    "Notion-Version": "2022-06-28",
  }),
});
```

Connect authenticates as the agent itself through one shared installation, with no per-user consent.

### OpenAPI · JWT bearer

Create `agent/connections/notion.ts`. The connection name is derived from the filename:

```ts
// agent/connections/notion.ts
import { connect } from "@vercel/connect/eve";
import { defineOpenAPIConnection } from "eve/connections";

export default defineOpenAPIConnection({
  spec: "https://developers.notion.com/openapi.json",
  baseUrl: "https://api.notion.com",
  description: "Notion workspace: search and edit pages and databases.",
  auth: connect({
    connector: "notion",
    principalToSubject: (principal) => {
      const email = principal.type === "user" ? principal.attributes?.email : undefined;
      if (typeof email !== "string") {
        throw new Error("JWT bearer authentication requires a user principal with an email.");
      }
      return { type: "jwt-bearer", sub: email };
    },
  }),
  headers: () => ({
    "Notion-Version": "2022-06-28",
  }),
});
```

Connect exchanges a JWT bearer assertion for a provider token. `principalToSubject` maps each principal to the subject your IdP expects.

## Configure

### MCP · User

Link your project, create the connector, and pull OIDC locally:

```bash
vercel link
vercel connect create notion
vercel env pull
```

The OpenAPI setup sends the required `Notion-Version` header; bump it as Notion ships new API versions.

See the [Connections docs](/docs/connections) for principal types, headers, approval, and protocol-specific filters.

### MCP · App

Link your project, create the connector, and pull OIDC locally:

```bash
vercel link
vercel connect create notion
vercel env pull
```

The OpenAPI setup sends the required `Notion-Version` header; bump it as Notion ships new API versions.

See the [Connections docs](/docs/connections) for principal types, headers, approval, and protocol-specific filters.

### MCP · JWT bearer

Link your project, create the connector, and pull OIDC locally:

```bash
vercel link
vercel connect create notion
vercel env pull
```

For JWT bearer, `principalToSubject` controls the asserted subject. The default maps app principals to `{ type: "app" }` and user principals to `{ type: "user", id, issuer }`.

The OpenAPI setup sends the required `Notion-Version` header; bump it as Notion ships new API versions.

See the [Connections docs](/docs/connections) for principal types, headers, approval, and protocol-specific filters.

### OpenAPI · User

Link your project, create the connector, and pull OIDC locally:

```bash
vercel link
vercel connect create notion
vercel env pull
```

The OpenAPI setup sends the required `Notion-Version` header; bump it as Notion ships new API versions.

See the [Connections docs](/docs/connections) for principal types, headers, approval, and protocol-specific filters.

### OpenAPI · App

Link your project, create the connector, and pull OIDC locally:

```bash
vercel link
vercel connect create notion
vercel env pull
```

The OpenAPI setup sends the required `Notion-Version` header; bump it as Notion ships new API versions.

See the [Connections docs](/docs/connections) for principal types, headers, approval, and protocol-specific filters.

### OpenAPI · JWT bearer

Link your project, create the connector, and pull OIDC locally:

```bash
vercel link
vercel connect create notion
vercel env pull
```

For JWT bearer, `principalToSubject` controls the asserted subject. The default maps app principals to `{ type: "app" }` and user principals to `{ type: "user", id, issuer }`.

The OpenAPI setup sends the required `Notion-Version` header; bump it as Notion ships new API versions.

See the [Connections docs](/docs/connections) for principal types, headers, approval, and protocol-specific filters.

[Read the full connection documentation](/docs/connections)

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)