Articles/Integrations

⬡ Integrations/2026-04-09Intermediate

Antigravity × Notion API Integration: AI-Powered Document-Driven Development

Learn how to connect Antigravity IDE with the Notion API to automate your document-driven development workflow — from spec to code, tests, and PR descriptions — using MCP servers.

antigravity⁴²⁹ notion api¹³ automation⁷⁹ workflow⁴⁹ mcp¹⁴ documentation⁷

✦ Premium Article

Setup and context: Eliminating the Gap Between Specs and Code

"We wrote the spec in Notion, but the implementation went in a completely different direction." "PR reviews stall because reviewers keep finding mismatches with the design doc." Sound familiar?

The gap between specifications and code is one of the most persistent frustrations in software development. As a project grows, this gap widens almost inevitably — not because developers are careless, but because the tools for writing specs and the tools for writing code are fundamentally disconnected.

This guide shows you how to bridge that gap using Antigravity IDE and the Notion API in a Document-Driven Development (DDD) workflow. Once set up, Antigravity reads your Notion specs directly, generates code aligned with them, and writes implementation summaries back to Notion automatically. The result: your specification database becomes a live, self-updating record of what was built and why.

Here's what the complete system looks like:

Notion → Antigravity: Specs and task details flow into Antigravity via MCP, enabling context-aware code generation
Antigravity → Notion: Implementation summaries, status updates, and PR links flow back to Notion automatically
GitHub Integration: Merged PRs trigger Notion status updates via GitHub Actions

This guide targets intermediate to advanced developers who use Notion regularly and want to go deeper with Antigravity's integration capabilities.

Prerequisites and Setup

What You'll Need

Antigravity IDE (latest version)
Notion account (free plan works)
Node.js 20+
GitHub CLI (gh) (optional, for PR automation)

Configuring the Notion API

First, create an API integration on the Notion side.

Step 1: Create an Integration

Go to Notion Developers and click "New integration."

Configuration:

Name: Antigravity Dev Assistant
Associated workspace: Select the workspace you want to connect
Capabilities: Enable Read content, Update content, and Insert content

After clicking "Submit," you'll receive an Internal Integration Secret (formatted as secret_xxx...). Save this somewhere secure.

Step 2: Set Up Your Database

Create a Notion database with the following structure:

📋 Dev Tasks DB
├── Name (Title): Task name
├── Status (Select): Todo / In Progress / Done / Blocked
├── Priority (Select): High / Medium / Low
├── Spec (Text): Detailed specification
├── Implementation (Text): Implementation summary (written by Antigravity)
├── PR URL (URL): Link to the associated pull request
└── Assignee (Person): Task owner

Extract the Database ID from the database URL:

https://www.notion.so/[workspace]/[DATABASE_ID]?v=xxx

Step 3: Connect the Integration to the Database

On the database page, click "..." → "Connections" → select your integration to grant it access.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Developers who struggled to sync Notion specs with actual code will now be able to automate that entire loop — from reading specs to generating and writing implementation summaries back to Notion

✦You'll learn how to build a production-ready MCP server that bridges Antigravity and the Notion API, enabling bidirectional spec-to-code automation with real TypeScript examples

✦By the end, you'll have a complete Document-Driven Development (DDD) pipeline that eliminates spec drift, accelerates your team's velocity, and keeps your Notion database as the single source of truth

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Building the MCP Server: Bridging Notion and Antigravity

Antigravity IDE connects to external tools via MCP (Model Context Protocol). By building a Notion MCP server, you give Antigravity the ability to read from and write to your Notion workspace directly.

Project Structure

mkdir notion-mcp-server && cd notion-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk @notionhq/client dotenv
npm install -D typescript @types/node tsx

Environment Variables

Create a .env file (make sure to add it to .gitignore):

NOTION_TOKEN=secret_YOUR_INTEGRATION_SECRET
NOTION_DATABASE_ID=YOUR_DATABASE_ID_HERE

⚠️ Security note: Never hardcode actual token values in source files. Always use environment variables or secret management tools.

MCP Server Implementation

Create src/notion-mcp-server.ts:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { Client } from "@notionhq/client";
import * as dotenv from "dotenv";
 
dotenv.config();
 
const notion = new Client({ auth: process.env.NOTION_TOKEN });
const DATABASE_ID = process.env.NOTION_DATABASE_ID!;
 
const server = new Server(
  { name: "notion-dev-assistant", version: "1.0.0" },
  { capabilities: { tools: {} } }
);
 
// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_todo_tasks",
        description: "Retrieve Todo tasks from the dev database",
        inputSchema: {
          type: "object",
          properties: {
            priority: {
              type: "string",
              enum: ["High", "Medium", "Low"],
              description: "Filter by priority (omit for all)",
            },
          },
        },
      },
      {
        name: "get_task_spec",
        description: "Get the full spec for a specific task",
        inputSchema: {
          type: "object",
          properties: {
            page_id: { type: "string", description: "Notion page ID" },
          },
          required: ["page_id"],
        },
      },
      {
        name: "update_task_implementation",
        description: "Write implementation summary and update status in Notion",
        inputSchema: {
          type: "object",
          properties: {
            page_id: { type: "string" },
            implementation_summary: { type: "string" },
            status: {
              type: "string",
              enum: ["In Progress", "Done", "Blocked"],
            },
            pr_url: { type: "string" },
          },
          required: ["page_id", "implementation_summary", "status"],
        },
      },
      {
        name: "create_task",
        description: "Create a new dev task in Notion",
        inputSchema: {
          type: "object",
          properties: {
            name: { type: "string" },
            spec: { type: "string" },
            priority: { type: "string", enum: ["High", "Medium", "Low"] },
          },
          required: ["name", "spec"],
        },
      },
    ],
  };
});
 
// Tool execution handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
 
  switch (name) {
    case "get_todo_tasks": {
      const baseFilter = {
        property: "Status",
        select: { equals: "Todo" },
      };
 
      const queryFilter = args?.priority
        ? { and: [baseFilter, { property: "Priority", select: { equals: args.priority } }] }
        : baseFilter;
 
      const response = await notion.databases.query({
        database_id: DATABASE_ID,
        filter: queryFilter,
        sorts: [{ property: "Priority", direction: "ascending" }],
      });
 
      const tasks = response.results.map((page: any) => ({
        id: page.id,
        name: page.properties.Name?.title?.[0]?.plain_text ?? "",
        priority: page.properties.Priority?.select?.name ?? "",
        status: page.properties.Status?.select?.name ?? "",
        spec_preview:
          (page.properties.Spec?.rich_text?.[0]?.plain_text ?? "").slice(0, 150) + "...",
      }));
 
      return {
        content: [{ type: "text", text: JSON.stringify(tasks, null, 2) }],
      };
    }
 
    case "get_task_spec": {
      const page = (await notion.pages.retrieve({
        page_id: args!.page_id as string,
      })) as any;
 
      const spec =
        page.properties.Spec?.rich_text?.map((t: any) => t.plain_text).join("") ?? "";
      const name = page.properties.Name?.title?.[0]?.plain_text ?? "";
      const priority = page.properties.Priority?.select?.name ?? "";
 
      return {
        content: [
          {
            type: "text",
            text: `# ${name}\n\n**Priority**: ${priority}\n\n## Specification\n\n${spec}`,
          },
        ],
      };
    }
 
    case "update_task_implementation": {
      const updates: any = {
        Status: { select: { name: args!.status } },
        Implementation: {
          rich_text: [{ text: { content: args!.implementation_summary as string } }],
        },
      };
 
      if (args?.pr_url) {
        updates["PR URL"] = { url: args.pr_url as string };
      }
 
      await notion.pages.update({
        page_id: args!.page_id as string,
        properties: updates,
      });
 
      return {
        content: [
          {
            type: "text",
            text: `✅ Updated task ${args!.page_id} (Status: ${args!.status})`,
          },
        ],
      };
    }
 
    case "create_task": {
      const newPage = await notion.pages.create({
        parent: { database_id: DATABASE_ID },
        properties: {
          Name: { title: [{ text: { content: args!.name as string } }] },
          Status: { select: { name: "Todo" } },
          Priority: { select: { name: (args?.priority ?? "Medium") as string } },
          Spec: { rich_text: [{ text: { content: args!.spec as string } }] },
        },
      });
 
      return {
        content: [
          { type: "text", text: `✅ Task created: ${(newPage as any).id}` },
        ],
      };
    }
 
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});
 
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Notion MCP Server running on stdio");
}
 
main().catch(console.error);

Build Configuration

Add build scripts to package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/notion-mcp-server.js"
  }
}

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

Build and verify:

npm run build
# Output: dist/notion-mcp-server.js

Registering the MCP Server in Antigravity

Create .antigravity/mcp.json in your project root:

{
  "mcpServers": {
    "notion-dev-assistant": {
      "command": "node",
      "args": ["/path/to/notion-mcp-server/dist/notion-mcp-server.js"],
      "env": {
        "NOTION_TOKEN": "${NOTION_TOKEN}",
        "NOTION_DATABASE_ID": "${NOTION_DATABASE_ID}"
      }
    }
  }
}

Add environment variables to your shell config:

export NOTION_TOKEN="secret_YOUR_INTEGRATION_SECRET"
export NOTION_DATABASE_ID="YOUR_DATABASE_ID"

Restart Antigravity IDE. The Notion tools will now appear in the chat panel.

Practical Workflows: Spec to Code in Action

Workflow 1: Generating Code from a Notion Spec

Enter this prompt in Antigravity's chat:

@notion-dev-assistant Fetch the highest-priority Todo task, read its full spec,
implement the code in TypeScript + Next.js, generate tests,
then write the implementation summary back to Notion.

Example interaction between Antigravity and Notion:

> get_todo_tasks (priority: "High")

Response:
[
  {
    "id": "abc123-...",
    "name": "Implement User Auth API",
    "priority": "High",
    "spec_preview": "Build a JWT-based RESTful auth API with login, token refresh, and logout..."
  }
]

> get_task_spec (page_id: "abc123-...")

Response:
# Implement User Auth API

**Priority**: High

## Specification

Endpoints:
- POST /api/auth/login: Authenticate with email and password
- POST /api/auth/refresh: Issue new access token using refresh token
- DELETE /api/auth/logout: Invalidate session

Requirements:
- JWT tokens (access: 15min, refresh: 7 days)
- bcrypt password hashing
- Prisma + PostgreSQL for user data
- Rate limit: 10 requests/minute

Antigravity then generates implementation code based on this spec:

// src/app/api/auth/login/route.ts
import { NextRequest, NextResponse } from "next/server";
import bcrypt from "bcryptjs";
import jwt from "jsonwebtoken";
import { prisma } from "@/lib/prisma";
import { rateLimit } from "@/lib/rate-limit";
 
export async function POST(request: NextRequest) {
  // Rate limit check
  const ip = request.ip ?? "unknown";
  const { success } = await rateLimit(ip, { limit: 10, window: 60 });
  if (!success) {
    return NextResponse.json({ error: "Too many requests" }, { status: 429 });
  }
 
  const { email, password } = await request.json();
 
  if (!email || !password) {
    return NextResponse.json(
      { error: "Email and password are required" },
      { status: 400 }
    );
  }
 
  const user = await prisma.user.findUnique({ where: { email } });
  if (!user) {
    return NextResponse.json({ error: "Invalid credentials" }, { status: 401 });
  }
 
  const isValid = await bcrypt.compare(password, user.passwordHash);
  if (!isValid) {
    return NextResponse.json({ error: "Invalid credentials" }, { status: 401 });
  }
 
  const payload = { userId: user.id, email: user.email };
  const accessToken = jwt.sign(payload, process.env.JWT_SECRET!, {
    expiresIn: "15m",
  });
  const refreshToken = jwt.sign(payload, process.env.JWT_REFRESH_SECRET!, {
    expiresIn: "7d",
  });
 
  await prisma.refreshToken.create({
    data: {
      token: refreshToken,
      userId: user.id,
      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
    },
  });
 
  return NextResponse.json({
    accessToken,
    refreshToken,
    user: { id: user.id, email: user.email },
  });
}

After generating the code, Antigravity writes the summary back to Notion:

> update_task_implementation (
    page_id: "abc123-...",
    status: "In Progress",
    implementation_summary: "Implemented JWT auth API:
    - POST /api/auth/login: bcrypt verification + JWT issuance
    - POST /api/auth/refresh: refresh token validation and rotation
    - DELETE /api/auth/logout: token invalidation from DB
    Rate limiting (10 req/min) and full error handling included."
  )

✅ Updated task abc123-... (Status: In Progress)

Workflow 2: Automated PR Creation and Notion Sync

When implementation is complete:

Generate a PR using GitHub CLI and update the Notion task status to Done with the PR URL.

Antigravity executes:

gh pr create \
  --title "feat: JWT auth API implementation (#abc123)" \
  --body "## Summary
Implementation PR for Notion task 'Implement User Auth API'.
 
## Changes
- POST /api/auth/login: bcrypt + JWT auth
- POST /api/auth/refresh: token rotation
- DELETE /api/auth/logout: session invalidation
- Rate limiting (10 req/min)
 
## Tests
- Unit tests: 15 passing
- Integration tests: 8 passing"

Then it updates Notion with the PR URL and sets the status to Done.

Advanced: GitHub Actions for Bidirectional Sync

For a fully automated pipeline, trigger Notion updates when PRs are merged.

`.github/workflows/notion-sync.yml`

name: Sync Notion on PR Merge
 
on:
  pull_request:
    types: [closed]
 
jobs:
  update-notion:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
 
    steps:
      - name: Extract Notion Page ID from PR title
        id: extract
        run: |
          PAGE_ID=$(echo "${{ github.event.pull_request.title }}" \
            | grep -oP '\(#\K[a-z0-9-]+(?=\))')
          echo "page_id=$PAGE_ID" >> $GITHUB_OUTPUT
 
      - name: Update Notion Task to Done
        if: steps.extract.outputs.page_id != ''
        env:
          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
        run: |
          PAGE_ID="${{ steps.extract.outputs.page_id }}"
          PR_URL="${{ github.event.pull_request.html_url }}"
 
          curl -s -X PATCH \
            "https://api.notion.com/v1/pages/${PAGE_ID}" \
            -H "Authorization: Bearer ${NOTION_TOKEN}" \
            -H "Content-Type: application/json" \
            -H "Notion-Version: 2022-06-28" \
            -d "{
              \"properties\": {
                \"Status\": {\"select\": {\"name\": \"Done\"}},
                \"PR URL\": {\"url\": \"${PR_URL}\"}
              }
            }"
 
          echo "✅ Notion updated: ${PAGE_ID} → Done"

This ensures that every merged PR automatically closes the corresponding Notion task.

Spec Template Design for Maximum Effectiveness

The quality of Antigravity's output is directly proportional to the clarity of your spec. This template consistently produces strong results:

## Feature Overview
[1–2 sentences describing what this implements]
 
## Target Users
[Who will use this feature]
 
## Input/Output Specification
### Input
- param1: type, validation rules
- param2: type, validation rules
 
### Output
- Success: response format
- Error: error codes and messages
 
## Business Logic
1. Step 1 processing
2. Step 2 processing
3. Edge case handling
 
## Tech Stack
- Language/Framework: TypeScript / Next.js
- DB: PostgreSQL + Prisma
- Dependencies: bcryptjs, jsonwebtoken
 
## Test Requirements
- [ ] Happy path: [specific test cases]
- [ ] Error cases: [error scenarios]
- [ ] Performance: [thresholds]
 
## References
- [Related existing code]
- [External API docs]

Testing the MCP Server and Integration

Before wiring everything into Antigravity, it's worth verifying each component independently. This saves a lot of debugging time later.

Unit Testing the MCP Tools

Create src/__tests__/notion-tools.test.ts to test the Notion API calls in isolation:

import { describe, it, expect, vi, beforeEach } from "vitest";
import { Client } from "@notionhq/client";
 
// Mock Notion client
vi.mock("@notionhq/client", () => ({
  Client: vi.fn().mockImplementation(() => ({
    databases: {
      query: vi.fn().mockResolvedValue({
        results: [
          {
            id: "test-page-id-001",
            properties: {
              Name: { title: [{ plain_text: "Test Task" }] },
              Status: { select: { name: "Todo" } },
              Priority: { select: { name: "High" } },
              Spec: {
                rich_text: [{ plain_text: "Implement user auth API" }],
              },
            },
          },
        ],
      }),
    },
    pages: {
      retrieve: vi.fn().mockResolvedValue({
        id: "test-page-id-001",
        properties: {
          Name: { title: [{ plain_text: "Test Task" }] },
          Priority: { select: { name: "High" } },
          Spec: {
            rich_text: [
              { plain_text: "Full spec content here..." },
            ],
          },
        },
      }),
      update: vi.fn().mockResolvedValue({ id: "test-page-id-001" }),
    },
  })),
}));
 
describe("Notion MCP Tools", () => {
  it("should query todo tasks and filter by priority", async () => {
    const notion = new Client({ auth: "test-token" });
    const result = await notion.databases.query({
      database_id: "test-db-id",
      filter: {
        and: [
          { property: "Status", select: { equals: "Todo" } },
          { property: "Priority", select: { equals: "High" } },
        ],
      },
    } as any);
 
    expect(result.results).toHaveLength(1);
    expect((result.results[0] as any).properties.Priority.select.name).toBe("High");
  });
 
  it("should update task status and implementation summary", async () => {
    const notion = new Client({ auth: "test-token" });
    await notion.pages.update({
      page_id: "test-page-id-001",
      properties: {
        Status: { select: { name: "Done" } },
        Implementation: {
          rich_text: [{ text: { content: "Auth API implemented with JWT" } }],
        },
      } as any,
    });
 
    expect(notion.pages.update).toHaveBeenCalledWith(
      expect.objectContaining({
        page_id: "test-page-id-001",
      })
    );
  });
});

Integration Testing with a Real Notion Sandbox

For integration testing, create a dedicated Notion workspace or a separate database for tests. Set NOTION_DATABASE_ID_TEST as a separate environment variable:

// test/integration/notion-integration.test.ts
import { Client } from "@notionhq/client";
import { describe, it, expect, afterAll } from "vitest";
 
const notion = new Client({ auth: process.env.NOTION_TOKEN });
const TEST_DB = process.env.NOTION_DATABASE_ID_TEST!;
 
const createdPageIds: string[] = [];
 
describe("Notion API Integration", () => {
  it("should create a task and retrieve it", async () => {
    const page = await notion.pages.create({
      parent: { database_id: TEST_DB },
      properties: {
        Name: { title: [{ text: { content: "Integration Test Task" } }] },
        Status: { select: { name: "Todo" } },
        Priority: { select: { name: "Low" } },
        Spec: {
          rich_text: [
            { text: { content: "This is an integration test task." } },
          ],
        },
      },
    });
 
    createdPageIds.push((page as any).id);
 
    const retrieved = await notion.pages.retrieve({
      page_id: (page as any).id,
    }) as any;
 
    expect(retrieved.properties.Name.title[0].plain_text).toBe(
      "Integration Test Task"
    );
  });
 
  afterAll(async () => {
    // Archive test pages to keep the DB clean
    for (const id of createdPageIds) {
      await notion.pages.update({
        page_id: id,
        archived: true,
      });
    }
  });
});

Run integration tests with:

NOTION_TOKEN=secret_xxx NOTION_DATABASE_ID_TEST=your-test-db-id \
  npx vitest run test/integration/

Verifying MCP Tool Registration in Antigravity

Once the MCP server is registered, you can verify the tools are available by typing in Antigravity's chat:

List all available MCP tools from notion-dev-assistant.

Antigravity should respond with the four tool names: get_todo_tasks, get_task_spec, update_task_implementation, and create_task. If any are missing, check the MCP server logs for initialization errors.

Scaling the Workflow: Multi-Project and Team Setups

The single-database setup works well for solo developers or small teams. As your workflow grows, here are patterns for scaling it.

Pattern 1: Multi-Database Router

When managing multiple projects with separate Notion databases, add a routing layer to the MCP server:

// Multi-database configuration
const DATABASES: Record<string, string> = {
  frontend: process.env.NOTION_DB_FRONTEND!,
  backend: process.env.NOTION_DB_BACKEND!,
  mobile: process.env.NOTION_DB_MOBILE!,
};
 
// Extended tool: get tasks from a specific project database
{
  name: "get_project_tasks",
  description: "Get Todo tasks from a specific project database",
  inputSchema: {
    type: "object",
    properties: {
      project: {
        type: "string",
        enum: ["frontend", "backend", "mobile"],
        description: "Which project database to query",
      },
      priority: { type: "string", enum: ["High", "Medium", "Low"] },
    },
    required: ["project"],
  },
}

In the handler, route to the correct database:

case "get_project_tasks": {
  const dbId = DATABASES[args!.project as string];
  if (!dbId) throw new Error(`Unknown project: ${args!.project}`);
 
  const response = await notion.databases.query({
    database_id: dbId,
    filter: args?.priority
      ? { and: [
          { property: "Status", select: { equals: "Todo" } },
          { property: "Priority", select: { equals: args.priority } },
        ]}
      : { property: "Status", select: { equals: "Todo" } },
  });
 
  // ... process and return results
}

Pattern 2: Sprint-Aware Task Fetching

Add a sprint property to your Notion database and extend the tool to filter by sprint number:

// Notion database property: Sprint (Number)
// Usage: "Get all High-priority tasks in Sprint 12"
 
case "get_sprint_tasks": {
  const response = await notion.databases.query({
    database_id: DATABASE_ID,
    filter: {
      and: [
        { property: "Status", select: { equals: "Todo" } },
        { property: "Sprint", number: { equals: args!.sprint as number } },
      ],
    },
    sorts: [{ property: "Priority", direction: "ascending" }],
  });
  // ...
}

Pattern 3: Dependency-Aware Task Ordering

When tasks have dependencies (Task B can't start until Task A is done), store dependency page IDs as a Relation property in Notion:

case "get_ready_tasks": {
  // Get tasks with no incomplete dependencies
  const allTasks = await notion.databases.query({
    database_id: DATABASE_ID,
    filter: { property: "Status", select: { equals: "Todo" } },
  });
 
  const readyTasks = [];
 
  for (const page of allTasks.results as any[]) {
    const deps = page.properties.Dependencies?.relation ?? [];
    let allDepsComplete = true;
 
    for (const dep of deps) {
      const depPage = await notion.pages.retrieve({ page_id: dep.id }) as any;
      if (depPage.properties.Status?.select?.name !== "Done") {
        allDepsComplete = false;
        break;
      }
    }
 
    if (allDepsComplete) {
      readyTasks.push({
        id: page.id,
        name: page.properties.Name?.title?.[0]?.plain_text ?? "",
        priority: page.properties.Priority?.select?.name ?? "",
      });
    }
  }
 
  return {
    content: [{ type: "text", text: JSON.stringify(readyTasks, null, 2) }],
  };
}

This allows Antigravity to understand task dependencies and sequence its work intelligently.

Common Errors and Fixes

Error 1: MCP server fails to start

Error: Cannot connect to MCP server "notion-dev-assistant"

Cause: Wrong path or missing environment variables.

Fix:

# Test the server standalone
NOTION_TOKEN=secret_xxx NOTION_DATABASE_ID=xxx \
  node /path/to/notion-mcp-server/dist/notion-mcp-server.js
# Should print: "Notion MCP Server running on stdio"

Error 2: 401 Unauthorized from Notion API

Cause: Integration not connected to the database.

Fix: On the Notion database page, go to "Connections" and re-add your integration.

Error 3: Page ID not found

APIResponseError: Could not find block with ID

Cause: Mixing up Database ID and Page ID, or wrong format.

Fix:

function normalizePageId(idOrUrl: string): string {
  if (idOrUrl.match(/^[a-f0-9-]{36}$/)) return idOrUrl;
  const match = idOrUrl.match(/([a-f0-9]{32})/);
  if (match) {
    const r = match[1];
    return `${r.slice(0,8)}-${r.slice(8,12)}-${r.slice(12,16)}-${r.slice(16,20)}-${r.slice(20)}`;
  }
  throw new Error(`Invalid Notion page ID: ${idOrUrl}`);
}

Best Practices

1. Use Notion Filtered Views to Scope Antigravity's Context

For large projects, create filtered Notion views (by sprint, assignee, or component) and pass the view context to Antigravity. This keeps the AI focused and reduces irrelevant noise in generated code.

2. Standardize Implementation Summary Format

Agree on a summary format across your team and include it in Antigravity's prompt. Consistent summaries make it easy for anyone — including your future self — to understand what was built from Notion alone.

3. Secure Your Notion Token

The Notion Integration Secret grants read/write access to all connected databases. Always store it in environment variables, GitHub Secrets, or a secrets manager. Never commit it to version control.

4. Respect the Notion API Rate Limit

Notion enforces a rate limit of 3 requests per second. When processing multiple tasks in a loop, add a small delay between requests or implement a request queue to avoid 429 errors.

Monitoring and Observability for the MCP Integration

Once your DDD workflow is live, it's important to track its health and usage. Here are practical monitoring strategies.

Logging MCP Tool Calls

Add structured logging to the MCP server so you can audit how often each tool is called and identify failures:

import { createWriteStream } from "fs";
import { join } from "path";
 
const logStream = createWriteStream(
  join(process.cwd(), "mcp-audit.log"),
  { flags: "a" }
);
 
function logToolCall(toolName: string, args: any, success: boolean, error?: string) {
  const entry = JSON.stringify({
    timestamp: new Date().toISOString(),
    tool: toolName,
    args: JSON.stringify(args).slice(0, 200), // Truncate for safety
    success,
    error: error ?? null,
  });
  logStream.write(entry + "\n");
}
 
// Wrap each tool handler:
try {
  const result = await handleTool(name, args);
  logToolCall(name, args, true);
  return result;
} catch (err: any) {
  logToolCall(name, args, false, err.message);
  throw err;
}

Tracking Notion Update Success Rates

Add a simple health check endpoint (if you deploy the MCP server as an HTTP service) that reports:

// GET /health
app.get("/health", async (req, res) => {
  try {
    // Verify Notion connectivity
    await notion.databases.query({
      database_id: DATABASE_ID,
      page_size: 1,
    });
    res.json({ status: "ok", notion: "connected" });
  } catch (err: any) {
    res.status(503).json({ status: "error", notion: err.message });
  }
});

Alerting on Notion API Failures

If you're running this in a team environment, set up an alert when the Notion API returns repeated errors. A simple approach using a webhook:

async function notifyOnFailure(tool: string, error: string) {
  const webhookUrl = process.env.ALERT_WEBHOOK_URL;
  if (!webhookUrl) return;
 
  await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `⚠️ Notion MCP tool \`${tool}\` failed: ${error}`,
    }),
  });
}

This gives you visibility into failures without having to manually check logs.

Summary

In this guide, we walked through building a complete Document-Driven Development pipeline with Antigravity and the Notion API:

MCP Server: Built with @modelcontextprotocol/sdk and @notionhq/client, exposing Notion as tools inside Antigravity
Bidirectional Sync: Specs flow from Notion into Antigravity for code generation; implementation summaries flow back automatically
GitHub Actions: PR merges trigger automatic Notion status updates
Testing Strategy: Unit tests with mocked Notion clients, integration tests against sandbox databases
Scaling Patterns: Multi-project routing, sprint-aware filtering, and dependency-aware task ordering for growing teams
Observability: Structured logging, health checks, and failure alerting to keep the pipeline reliable
Best Practices: Spec template design, rate limit handling, and secure token management

The gap between specs and code doesn't have to be a fact of life. With this system in place, your Notion database becomes a living record of everything your team has built — and the foundation for everything you'll build next.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.