노션에 AI 에이전트 연결하는 방법과 실수

메신저 연동 시리즈를 다녀오고 이번에는 생산성 쪽으로 넘어온다. 첫 편은 노션이다. 에이전트에게 노션을 붙이면 "이 문서 요약해줘" 같은 요청을 브라우저를 열지 않고 바로 처리할 수 있다. 붙이는 데 10분이면 되는데, 안 붙어지는 이유를 알면 금방 고친다. (운영자 환경 확인 기준)

1. 내부 연결 만들기

Notion 워크스페이스 설정 → 연결(Connections) 탭 → 새 연결 → 이름 지정 → 연관 워크스페이스 선택.

ntn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

발급되는 게 이 토큰이다. ntn_으로 시작한다. 토큰은 연결 설정의 Configuration 탭에서 ••• 메뉴로 다시 볼 수 있다.

주의점 1: 연결은 워크스페이스에 종속된다

토큰을 만들 때 '연관 워크스페이스'를 고르는 단계가 있다. 여기서 고른 워크스페이스가 바뀌면 그 토큰은 그대로 쓸 수 없다. 나중에 워크스페이스를 옮기거나 테스트용으로 새로 만든 워크스페이스로 바꾸면서, 왜 토큰이 갑자기 401이 되는지 한참을 들었다. 연결 자체를 새로 만들어야 한다.

2. 페이지 공유 (이거 빠지면 전부 실패한다)

토큰만 만들면 에이전트는 아무것도 못 읽는다. 새로 만든 연결은 접근 권한이 하나도 없는 상태로 시작한다. 반드시 페이지 단위로 공유해야 한다.

노션에서 붙이려는 페이지를 열고 우측 상단 ··· → 연결 → + 연결 추가 → 방금 만든 연결 선택.

또는 연결 설정의 Access 탭에서 페이지들을 한 번에 지정할 수도 있다. 여러 페이지에 반복해서 붙일 거면 Access 탭을 쓴다.

주의점 2: 권한 0 상태로 API를 때리면 에러 메시지가 모호하다

토큰이 유효한데 아무것도 안 보인다. 원인은 토큰이 아니라 공유가 빠진 것이었다. 처음 연결하면 "에이전트가 노션을 쓸 수 있게 됐어요" 같은 안내가 안 나오기 때문에, 테스트를 해봐야 이 걸림돌을 알 수 있다.

3. 에이전트에 MCP로 붙이기

공식 MCP 서버를 그대로 쓴다.

npx @notionhq/notion-mcp-server

MCP 설정 파일에 등록한다.

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_xxxx"
      }
    }
  }
}

Hermes에서는 게이트웨이에 MCP 서버를 물려주는 형태로 넣는다. 등록 후 에이전트가 노션 도구를 실제로 쓸 수 있는지 확인하려면 한 마디 던져보면 된다.

노션에서 [페이지 이름] 읽고 요약해줘

주의점 3: MCP 서버는 최초 실행 때 패키지를 받으므로 첫 응답이 느리다

npx -y로 처음 실행하면 패키지 다운로드가 같이 걸린다. 첫 요청이 10초 이상 걸린다고 서버가 죽은 줄 알고 재시작하는 실수를 했다. 두 번째부터는 캐시되어 바로 뜬다.

주의점 4: 노션 공식 호스티드 MCP도 있다

https://mcp.notion.com/mcp

이건 토큰을 직접 넣는 대신 OAuth 2.0 + PKCE로 인증하는 방식이다. 클라이언트가 PKCE를 구현해야 해서 조금 번거롭다. 토큰 하나만 넣으면 되는 로컬 MCP 서버가 훨씬 편했다. 여러 사람이 각자 노션을 붙여 쓰는 환경이면 호스티드 쪽이 낫다.

4. 직접 API를 쓰는 경우

MCP 없이 스크립트로 직접 부를 때도 있다. 이때는 헤더가 필수다.

curl 'https://api.notion.com/v1/pages/{page_id}' \
  -H 'Authorization: Bearer ntn_xxxx' \
  -H 'Notion-Version: 2026-03-11'

주의점 5: Notion-Version 헤더를 빼먹으면 조용히 옛날 동작을 한다

버전 헤더가 없으면 API가 기본 버전을 쓴다. 2025-09-03 이후 API는 데이터베이스가 '데이터 소스' 단위로 쪼개져서, ID를 잘못 잡으면 "찾을 수 없다"가 아니라 엉뚱한 결과가 나온다. 헤더 스킵은 항상 붙이는 게 안전하다.

5. 주의점 나머지

주의점 6: 페이지 URL에서 ID를 잘못 복사한다

URL 끝의 32자리 ID만 그대로 긁어야 한다. 쿼리 파라미터까지 복사하거나 중간에서 끊으면 404가 난다. 데이터베이스는 페이지와 URL 구조가 달라서 더 헷갈린다.

주의점 7: 읽기 전용으로 만들어 놓으면 쓰기가 안 된다

연결 설정의 Capabilities에서 읽기 전용(Read content)만 체크하면 조회는 되는데 쓰기가 조용히 실패한다. 에이전트가 노션에 정리해 주기를 바란다면 권한을 처음부터 넉넉하게 잡는 편이 낫다.

주의점 8: 토큰은 마크다운에 그대로 쓰면 안 된다

몇몇 MCP 설정 문서에 토큰을 예시로 적어두는데, 그대로 복사해서 커밋하면 워크스페이스가 노출된다. 환경 변수로 넣고, 유출되면 Configuration 탭에서 즉시 재발급한다.

정리

1. 설정 → 연결 → 새 연결, ntn_ 토큰 발급 (워크스페이스 종속)
2. 접근할 페이지를 반드시 연결에 추가 (이게 없으면 전부 실패)
3. MCP 서버를 npx @notionhq/notion-mcp-server + NOTION_TOKEN으로 등록
4. 첫 실행은 패키지 다운로드로 느린 게 정상, 두 번째부터 빠르다
5. 직접 API 호출 시 Notion-Version: 2026-03-11 헤더 필수

노션은 메신저와 달리 인증이 쉬운 대신 권한 설계가 필요한 쪽이다. 붙이고 나서 무엇을 시킬지 결정하고 권한을 주는 순서가 빠르다. 에이전트에게 노션 쓰기를 맡기려면 어차피 워크스페이스 안에서만 움직이게 하고, 위험한 페이지부터 권한을 좁혀 나가는 게 안전하다.