---
title: "Notion’s hosted MCP server: an inside look"
description: "Notion’s hosted Model Context Protocol (MCP) server describes its move from a downloadable MCP server to an all-in-one hosted service that lets AI clients such as Cursor and Claude Desktop interact with workspaces. The initial proof of concept generated MCP tools from Notion’s OpenAPI schema, mapping endpoints one-to-one to API calls, but setup required API keys or Docker and the approach consumed substantial context when handling hierarchical block JSON. The hosted version uses a code-generation pipeline that converts OpenAPI schemas to Zod, combines rewritten AI-oriented tools with wrappers for existing v1 APIs, and exposes them through a central integration. Users connect through one-click OAuth; the server manages sessions and tokens, with streamable HTTP and SSE supported for client compatibility. A design change is Notion-flavoured Markdown, which represents blocks including callouts, columns, pages, and databases more efficiently for agent conversations, while semantic search can span Notion and over ten third-party apps."
---

# Notion’s hosted MCP server: an inside look

[Notion](https://yomu.fyi/company/notion) · Kenneth Sinder · Jul 15, 2025

**Type:** Explainer

## Summary

Notion’s hosted Model Context Protocol (MCP) server describes its move from a downloadable MCP server to an all-in-one hosted service that lets AI clients such as Cursor and Claude Desktop interact with workspaces. The initial proof of concept generated MCP tools from Notion’s OpenAPI schema, mapping endpoints one-to-one to API calls, but setup required API keys or Docker and the approach consumed substantial context when handling hierarchical block JSON. The hosted version uses a code-generation pipeline that converts OpenAPI schemas to Zod, combines rewritten AI-oriented tools with wrappers for existing v1 APIs, and exposes them through a central integration. Users connect through one-click OAuth; the server manages sessions and tokens, with streamable HTTP and SSE supported for client compatibility. A design change is Notion-flavoured Markdown, which represents blocks including callouts, columns, pages, and databases more efficiently for agent conversations, while semantic search can span Notion and over ten third-party apps.

## Context

Notion received requests for an MCP server from enterprises, individual toolmakers, developers, and Notion Ambassadors seeking easier workspace access from familiar LLM tools. Early feedback showed that the downloadable server’s technical setup was too difficult for widespread adoption and that its one-to-one API mapping produced suboptimal agent experiences, including high context consumption with hierarchical block data.

## Approach / What changed

Notion hosts a remote MCP server backed by a code-generation pipeline that converts generated OpenAPI schemas to Zod. It provides a central OAuth-connected integration with AI-oriented tools, wrappers for existing v1 APIs, streamable HTTP and SSE transports, and Notion-flavoured Markdown for page content.

## Takeaways

- The initial downloadable server mapped each Notion API endpoint one-to-one to an MCP tool and required users to configure an API key or build a Docker image.
- The hosted server uses one-click OAuth, stores the API token from the OAuth exchange, manages sessions, and supports streamable HTTP plus SSE transports.
- Notion-flavoured Markdown models blocks such as callouts, columns, pages, and databases while requiring fewer tool interactions and less cost than the open-source server for common use cases.

**Tags:** [Markdown](https://yomu.fyi/topic/markdown), [MCP](https://yomu.fyi/topic/mcp), [Notion](https://yomu.fyi/topic/notion), [OAuth2](https://yomu.fyi/topic/oauth2)

- Source: [Notion](https://www.notion.com/en-gb/blog/notions-hosted-mcp-server-an-inside-look)
- Source URL: https://www.notion.com/en-gb/blog/notions-hosted-mcp-server-an-inside-look
- Ingested by Yomu: 2026-09-09T05:20:37.197Z

[Read original post](https://www.notion.com/en-gb/blog/notions-hosted-mcp-server-an-inside-look)