Notion API Docs

This is a submission for the Notion MCP Challenge
Notion API Docs: Living Documentation Powered by Notion MCP
What I Built
I built Notion API Docs, a living documentation hub where all my Notion API knowledge, examples, and workflows are stored, queried, and updated directly through the Notion API using MCP.

Instead of static docs scattered across bookmarks and random notes, this project turns a Notion workspace into:

A structured API reference (endpoints, methods, parameters, examples)

A cookbook of real-world snippets (create pages, query databases, update blocks, etc.)

A changelog and experiments log (what I tried, what worked, what broke)

Using MCP, my tools can:

Add new API examples to Notion as I experiment

Fetch relevant snippets when I’m coding

Keep a “single source of truth” for how I use the Notion API across projects

It’s basically my personal, programmable Notion API documentation site—backed by Notion itself.

Video Demo
In the demo, I walk through:

The Notion Docs database

A database with properties like: Endpoint, Method, Use Case, Code Example, Status, Tags.

Creating a new API doc entry via MCP

From a terminal or local AI chat, I say:
“Document an example for PATCH /v1/pages that updates a page title.”

MCP sends a structured payload to Notion, creating a new row with the code snippet and metadata.

Querying docs while coding

I ask: “Show me all examples tagged databases and TypeScript.”

MCP queries the Notion database and returns matching entries, which I can paste or adapt.

Keeping docs in sync

When I refine a snippet, I trigger an update that patches the corresponding Notion entry via the API.

The result: my docs evolve with my work instead of falling out of date.

Show Us the Code
The project is structured as a small, focused codebase with three main parts:

/notion – Notion API client and helpers

Typed wrappers around endpoints like search, databases.query, pages.create, pages.update.

/mcp – MCP tool definitions

Tools like createDocEntry, updateDocEntry, findDocsByTag, which internally call the Notion API.

/workflows – Example scripts / prompts

Example CLI commands or AI prompts that show how to use the tools in real workflows.

Example (pseudo-TypeScript) for creating a doc entry:

ts
async function createApiDocEntry(client, {
endpoint,
method,
useCase,
codeExample,
tags
}) {
return client.pages.create({
parent: { database_id: process.env.NOTION_DOCS_DB_ID },
properties: {
Name: { title: [{ text: { content: ${method} ${endpoint} } }] },
Endpoint: { rich_text: [{ text: { content: endpoint } }] },
Method: { select: { name: method } },
UseCase: { rich_text: [{ text: { content: useCase } }] },
Tags: { multi_select: tags.map(name => ({ name })) }
},
children: [
{
object: 'block',
type: 'code',
code: {
language: 'typescript',
rich_text: [{ text: { content: codeExample } }]
}
}
]
});
}
You can imagine similar helpers for querying and updating entries.

How I Used Notion MCP
Notion MCP is the glue that makes this feel like a living docs system instead of just a pretty database.

1. MCP Tools as “Doc Actions” I defined MCP tools that map directly to documentation actions:

create_api_doc – Create a new doc entry in the Notion database

update_api_doc – Patch an existing entry (e.g., improved snippet, new notes)

search_api_docs – Query by endpoint, tag, or keyword

list_recent_changes – Pull the latest updated entries for quick review

These tools are what my local AI or CLI calls—they hide the raw Notion API details.

1. Notion as a Structured Knowledge Base The Notion database schema is designed for API docs:

Name – METHOD /endpoint

Endpoint – /v1/databases/query, /v1/pages, etc.

Method – GET, POST, PATCH, DELETE

Use Case – Human-readable explanation of when to use this

Tags – databases, pages, blocks, auth, pagination, etc.

Status – Draft, Verified, Deprecated

MCP tools read and write to this schema, so everything stays consistent.

1. AI + Docs Feedback Loop Because MCP exposes these tools to my AI:

When I discover a new pattern, I can say:
“Save this as a Notion API example for querying databases with filters.”

When I forget how something works, I can ask:
“Show me all Notion API examples for updating blocks.”

The AI doesn’t just answer—it uses Notion as its memory.

1. Why This Setup Works Notion API gives me a flexible, structured backend.

MCP makes that backend feel native to my tools and AI.

The docs database becomes a living artifact of how I actually use the Notion API, not just how it’s described in official docs.