# Notion MCP Server Comparison

## Overview

[Notion's official MCP server](https://github.com/makenotion/notion-mcp-server) (4K stars, TypeScript) exposes Notion workspace operations (pages, databases, blocks, search, comments) as MCP tools. It is Notion's first-party MCP integration, designed for direct API access.

---

## How Notion MCP works

1. **In-process Notion SDK**: Tools execute Notion API calls directly via the Notion JS SDK. No HTTP proxy — the MCP server imports `@notionhq/client` and calls methods like `notion.pages.create()`.

2. **API token auth**: Uses a Notion integration token (internal or public). The token is passed as an environment variable and used for all API calls.

3. **Markdown conversion**: Tool results convert Notion block content to Markdown for LLM consumption. This is domain-specific preprocessing that reduces token usage and improves LLM comprehension.

4. **Simple architecture**: A straightforward mapping of Notion API endpoints to MCP tools. No complex orchestration, concurrency control, or observability layers.

---

## How our system differs

| Aspect                  | Notion MCP               | Coda MCP Server                        |
| ----------------------- | ------------------------ | -------------------------------------- |
| **Execution**           | In-process SDK           | HTTP proxy to Express API              |
| **Auth**                | Notion integration token | Bearer token forwarded                 |
| **Response format**     | Markdown-converted       | Raw JSON                               |
| **Concurrency control** | None                     | Semaphore(5)                           |
| **Error handling**      | SDK error propagation    | `ToolCallOutcome` tagged union + hints |
| **Observability**       | None                     | OTel tracing + metrics + MCP logging   |
| **Response truncation** | None                     | 100K structural array truncation       |
| **Testing**             | Basic                    | 228 tests across 18 files              |

---

## What we are NOT adopting and why

1. **Markdown conversion**: Our tool results are structured JSON (accounts, contracts, revenue), not document content. Markdown conversion is appropriate for Notion blocks but not for tabular financial data.

2. **Direct SDK integration**: We already exclude Notion tools from MCP because they require per-user OAuth tokens that the MCP server cannot provide. Our existing web UI handles Notion integration with proper per-user auth.

---

## What we are adopting

### 1. Response format optimization (future consideration)

Notion's Markdown conversion reduces response size and improves LLM comprehension. While we don't need Markdown, we could consider a similar "LLM-optimized" response format for certain tools — for example, condensing large account detail responses into summary format before sending to the MCP client. Our `serializeResponse()` handles size limits but not semantic summarization.

---

## Key insight: simplicity vs. enterprise features

Notion MCP is intentionally simple — no concurrency control, no OTel, no structured errors, no response truncation. This works for a Notion integration where API calls are fast and responses are small. Our enterprise features (semaphore, OTel, structured errors, truncation) are necessary because our tools query complex financial systems that can return large datasets and experience latency under load.

---

## References

- [makenotion/notion-mcp-server](https://github.com/makenotion/notion-mcp-server) (GitHub)

---

_Comparison conducted 2026-05-10._