remote MCP server · TypeScript + Hono · Streamable HTTP

Notion as MCP tools,
running in production.

Built properly: Streamable HTTP, bearer auth, tested.

https://notion-mcp-hono-production.up.railway.app/mcp

I take AI systems from demo production. @ldamoredev

Architecture

Three layers, dependencies pointing inward. The MCP layer never imports the Notion SDK — the integration is swappable without touching tool code.

MCP client claude.ai · Claude Code · any Streamable HTTP client

POST /mcp · Authorization: Bearer <key>

Transport Hono routes · timing-safe bearer auth · body limit · JSON request logs

src/app.ts

MCP McpServer · 5 tool registrations · Zod input schemas · tool runner — raw errors never reach the client

src/mcp/

Notion NotionGateway interface (domain types only) · @notionhq/client v5 adapter · markdown converted natively by Notion

src/notion/

Notion API · 2025-09-03

Notion workspace pages · databases · markdown in, markdown out

Five tools, exactly

Scope stays small and excellent. Every input is Zod-validated with size limits; every description is written for the LLM consuming it; Notion failures come back as actionable messages, never raw API errors.

search_pages read-only

Searches pages across the workspace by title. The discovery step before get_page or append_blocks.

query: string
limit?: int 1–100

get_page read-only

Retrieves one page as clean markdown, with its ID, title, URL, and a truncation flag.

page_id: string

query_database read-only

Queries a database with Notion filters and sorts; rows come back simplified to flat JSON, with cursor-based pagination.

database_id: string
filter?: object · sorts?: array
page_size?: int 1–100 · start_cursor?: string

create_page write

Creates a page under an existing parent — a child page, or a new row in a database — optionally with initial markdown content.

parent_type: "page" | "database"
parent_id: string · title: string
markdown?: string

append_blocks write

Appends Notion-compatible markdown to the end of an existing page.

page_id: string
markdown: string

Live playground

These requests run the same tool code the MCP endpoint runs — server-side, against a dedicated demo workspace. Next to each result you get the JSON-RPC payload an MCP client would send.

test bench — demo workspace · read-only · 10 req/min

Loading tools…

Connect it yourself

Every request to /mcp requires Authorization: Bearer <MCP_API_KEY> — compared timing-safe server-side. Deploy your own from the repo in minutes and use your own key.

claude.ai — custom connector

Settings → Connectors → Add custom connector

URL:

https://notion-mcp-hono-production.up.railway.app/mcp

Advanced settings → HTTP headers:
```
Authorization: Bearer <MCP_API_KEY>
```

Claude Code

claude mcp add --transport http notion-hono \
  https://notion-mcp-hono-production.up.railway.app/mcp \
  --header "Authorization: Bearer <MCP_API_KEY>"

The five tools appear as mcp__notion-hono__*. A missing or wrong key gets a 401 with a JSON body naming the expected header.

Notion as MCP tools,running in production.