Notion 자체 호스팅 MCP 서버 소개

2024년 11월 Anthropic에서 발표한 MCP(Model Context Protocol)는 기술 기업과 사용자를 보편적인 언어로 연결해 도구를 쉽게 찾고 활용할 수 있도록 한다는, 단순하지만 강력한 비전이 담겨 있습니다.

MCP는 지난 수십 년간 웹 API의 기반이 되었던 REST 같은 기존 규약에서 더 진화된 접근 방식입니다. 이 프로토콜은 대규모 언어 모델(LLM)이 Notion, Figma, Stripe 같은 기업이 제공하는 다양한 툴을 언제 어떻게 사용할지 판단할 수 있도록 맥락, 즉 컨텍스트를 제공합니다. 사용자는 기술 문서를 하나하나 참고하며 구현하던 기존 API 통합 과정을 생략하고 AI 대화나 워크플로에서 자연어를 사용해 시스템과 상호작용할 수 있습니다.

Cursor와 Claude Code는 LLM ‘프론트엔드’로 불리우는 MCP 클라이언트로, 최종 사용자와 직접 소통하는 에이전트의 역할을 합니다. 에이전트는 사용자의 자연어 요청을 해석해 Notion, Stripe, Figma 등 다양한 서비스 제공자가 공개한 기능(‘툴’)을 실행하는 MCP 서버에 전달합니다.

Notion은 올해 초 MCP 서버를 만들어 달라는 요청을 받기 시작하면서 지식 업무와 제품 개발 프로세스에 AI 우선 워크플로를 도입한 대기업들의 사례를 직접 들었습니다. 또한 Notion으로 데이터를 쉽게 마이그레이션하고 Cursor, Claude Desktop처럼 익숙한 LLM 도구를 통해 워크스페이스와 쉽게 상호작용할 수 있는 솔루션을 원하는 빌더와 개발자, Notion 앰배서더 여러분의 의견을 경청했습니다.

개념 증명의 첫 단계는 Notion의 기존 API 기능을 AI에서 호출 가능한 액션으로 제공해 ‘툴’ 기반 모델이 에이전트 기반 워크플로의 생산성 개선에 미치는 영향을 확인하는 것이었습니다.

그 시작으로 4월 초에 다운로드 가능한 notion-mcp-server가 출시되었습니다. 이 서버는 Cursor나 Claude Desktop에 설치할 수 있었지만 전문적인 기술 지식을 요구했고, 설정 과정에서 새로운 Notion API를 통합하고 API 키를 MCP 헤더에 복사하거나 Docker 이미지를 직접 구축하는 작업이 필요했습니다. 서버 설정 후 사용자는 AI 에이전트 대화로 페이지 생성 같은 Notion 작업을 실행할 수 있었습니다.

백그라운드에서 라이브러리는 Notion의 공개 OpenAPI 사양을 구문 분석해 사용 가능한 API 엔드포인트와 인터페이스 정보를 읽고, 사용자가 설정한 API 키를 사용해 MCP 툴 호출을 Notion의 오픈 API에 대한 HTTP API 호출로 변환하여 해당 파일을 처리했습니다. 각 API 엔드포인트는 서버 내 MCP 툴과 1:1로 매핑되었고, MCP 클라이언트에서 MCP 서버로 수신된 요청은 사용자의 설정에 맞춘 API 호출로 변환되었습니다.

비록 설정이 복잡하고 기능도 제한적이었지만 최대한 빠르게 실사용이 가능한 버전을 제공하기 위한 결정이었습니다. 초기 사용자들의 피드백은 두 가지 중요한 문제점을 시사했습니다. 먼저 기술적 진입 장벽이 너무 높아 많은 사용자가 활용하기 어렵고, 1:1 API 매핑 방식이 AI 에이전트 환경에 적합하지 않다는 사실이었습니다. 그 예로 JSON 형식의 계층적 블록 데이터를 처리할 때 컨텍스트 토큰이 과도하게 소비된다는 문제가 있었습니다.

이러한 교훈은 다음 버전의 개발 방향성을 제공했고, 기존 도구와 새로운 기능의 강력한 조합을 누구나 사용할 수 있는 방식으로 제공하면서 커넥티드 워크스페이스로서 Notion의 가치를 살릴 수 있는 방법을 찾기 위한 노력이 이어졌습니다. Notion에 작성한 요구 사항 문서를 바탕으로 Cursor에서 실제로 동작하는 프로토타입을 만들고, 실시간으로 작업 상태를 업데이트하거나 프로젝트 관련자들에게 최신 정보를 전달하는 작업을 코드 편집기에서 모두 수행할 수 있다고 상상해 보세요.

더 쉽게 AI 에이전트 툴을 연결하고 활용할 수 있게 된 Notion 워크스페이스의 핵심 인사이트를 아래에 정리했습니다.

• 자체 MCP 서버 호스팅으로 기존 코드베이스와 내부 툴을 활용한 빠른 개발 사이클: 사용자가 업데이트 패키지를 다운로드하지 않아도 개선 사항이 즉시 Notion에 적용됩니다.

• API에 대한 HTTP 호출 대신 AI 에이전트에 최적화된 툴을 모아 제공하는 단일 중앙 통합 시스템: RESTful 웹 API 방식은 생략하고, LLM에 최적화된 설명과 함께 MCP 서버를 통해서만 접근 가능한 ‘비공개 기능 조각’을 제공함으로써 훨씬 더 매끄럽고 사용자 친화적인 에이전트 활용이 가능해졌습니다.

이제 모든 사용자는 ‘원클릭’ OAuth 인증을 통해 동일한 오픈 API 통합에 안전하게 연결할 수 있습니다. 워크스페이스에 직접 설치하고 공유할 페이지나 데이터베이스는 직접 선택합니다.

성공적으로 연결되면 사용 중이던 툴(예: Cursor)로 다시 리디렉션되어 작업을 계속할 수 있습니다. Notion MCP 서버는 세션을 관리하고 OAuth 교환을 통해 받은 API 토큰을 안전하게 저장하여 툴 호출 시 Notion 오픈 API로 인증을 진행합니다.

특히 Cursor의 엔지니어링팀과 긴밀히 협력하여 스트리밍 가능한 HTTP를 활용해 사용자 친화적인 OAuth 연결 경험을 제공하고자 했습니다. 그리고 더 다양한 클라이언트와 호환될 수 있도록 MCP 사용에 권장되는 또 다른 주요 전송 프로토콜인 SSE(서버 전송 이벤트)도 지원합니다.

기술 스택과 호스팅 외에 어떤 AI 툴을 제공할지 결정하는 것도 중요했습니다. Notion은 인앱 Notion 에이전트 개발팀과 협력하여 기존 /v1/ API 엔드포인트보다 AI 중심 툴을 우선적으로 노출하는 방식을 선택했습니다.

MCP 툴 세트는 다음 두 가지 유형을 결합했습니다.

• Notion 에이전트 전용 툴: 기존의 Create & Update Page API를 create-pages와 update-page로 완전히 새롭게 재작성하는 등 유연성이 부족한 기존 웹 API보다 AI 에이전트 대화에서 더 자연스러운 인터페이스를 제공합니다.

  • 이러한 툴들은 Notion 마크다운 사용을 염두에 두고 제작되었으며, 백엔드 통합용으로 사용하는 결정론적이고 구조화된 JSON 대신, 에이전트 워크플로에 최적화된 툴 설명과 응답을 제공합니다.

  • 마크다운은 더 적은 LLM 토큰으로도 효율적으로 콘텐츠를 표현할 수 있어 일반적으로 오픈소스 MCP 서버보다 툴 호출이 적고 비용도 덜 듭니다.

  • search 툴도 여기에 해당합니다. 기존의 v1 search API는 간단한 작업이나 Notion AI 기능을 사용하지 않는 계정을 위해 계속 제공되지만, 그 외에는 질문 형식의 의미 검색을 지원하는 search 툴이 사용되며 Notion 워크스페이스는 물론 10개 이상의 서드파티 연결 앱을 검색해 관련 페이지를 찾아줍니다.

• 기존 API 툴: 오픈소스 MCP 서버의 성공 경험을 바탕으로, v1 API를 래핑하는 MCP 도구를 추가하여 기능 공백을 보완했습니다.

  • 예를 들어 create-comment 툴은 v1 API 기능을 기반으로 하되, 오픈소스 패키지의 불완전한 부분을 극복하기 위해 AI 친화적인 툴 설명을 추가했습니다.

  • 이 프롬프트는 MCP 클라이언트가 어떤 도구를 언제 어떻게 사용할지 알 수 있는 맥락을 제공합니다.

이 전략은 광범위한 기능을 제공하는 동시에 채팅창에서 툴 호출 시 Notion URL이나 ID와 같은 정보를 더 매끄럽게 처리할 수 있게 해줍니다.

Notion MCP 베타는 AI 에이전트를 사용한 페이지 콘텐츠 생성과 편집, 확인에 최적화된 새로운 작성 방식을 시험해 볼 기회를 제공합니다. Notion은 다양한 Notion 블록 구조를 지원하는 ‘Notion 마크다운’ 규격을 새롭게 정의했습니다.

Notion API 구축을 소개한 2022년 블로그 게시물을 보셨던 분들이라면 기억하시겠지만, 당시 Notion은 리치 텍스트 색상, 데이터베이스 등 CommonMark 마크다운으로는 구현할 수 없는 Notion 고유의 편집 기능을 지원하기 위해 마크다운을 거부하고 JSON을 선택했습니다.

3년이 지난 지금, 계층적 JSON 구조에서 블록 하위 요소를 다루기 위해 과도한 API 요청이 필요하다는 피드백이 있었고, 이는 Notion의 주요 과제로 부상했습니다. 이에 따라 Notion 블록과 동일한 수준의 기능을 구현하기 위해 다시 마크다운을 도입해 현재 원격 MCP 서버에서 이 방식을 시험 중입니다.

Notion 마크다운 규격 중 몇 가지를 먼저 소개합니다.

콜아웃

열

페이지

데이터베이스

자세한 내용은 MCP 서버를 통해 공개된 툴 설명에서 확인할 수 있습니다. 또는 채팅창에서 AI 에이전트에게 “Notion 마크다운 요약해 줘”라고 요청해 정리된 내용을 바로 확인할 수 있습니다. 세부적인 구현에 신경쓸 필요 없이 페이지에 추가하거나 편집하고 싶은 내용을 자연어로 설명하고 나머지는 LLM에게 맡기세요.

이번 출시는 Notion을 AI 기반 지식 작업의 진정한 허브로 만드는 여정의 첫걸음입니다. 누구나 쉽게 쓸 수 있는 강력한 도구를 만든다는 Notion의 목표는 MCP를 확장해 나가는 과정에서도 변함없이 가장 중요한 핵심이 될 것입니다.

우리는 Cursor를 비롯한 다양한 외부 팀과 지속적으로 협력하면서 신뢰할 수 있는 MCP 서버·클라이언트 마켓플레이스와 서버 디스커버리 프로토콜 등 더 쉬운 자동 검색과 강화된 보안, 안정성을 지원하는 새로운 MCP 표준을 만들어가고 있습니다.

Notion MCP와 함께 여러분이 만들어 갈 미래가 정말 기대됩니다. 소셜 미디어로 @NotionHQ에 공유해 주세요.