Notion MCP가 연결하는 것#
기획 문서에서 요구사항과 미결정을 읽어 오는 작업과 문서 자체를 수정하는 작업을 나눕니다. 사내 위키를 연결하기 전에 외부로 전달해도 되는 범위를 먼저 정하세요.
이 절의 표는 Notion 공식 호스팅 서버에 관한 설명입니다. 실제 페이지의 공유 설정이나 Mirr Code와의 연결 결과를 보여 주는 기록은 아닙니다. 출처 확인: 2026-11-01.
| 항목 | 공식 문서의 내용과 확인할 점 |
|---|---|
| 기능 | 문서와 데이터베이스를 검색·조회하고 콘텐츠를 변경하는 도구를 제공합니다. 실제 노출 도구는 연결에 따라 다를 수 있습니다. (지원 도구) |
| 원격 주소 | 공식 호스팅 서버의 Streamable HTTP 주소는 https://mcp.notion.com/mcp입니다. (Notion MCP 연결) |
| 인증과 접근 | 호스팅 서버는 OAuth를 지원합니다. 인증 후 클라이언트는 선택한 워크스페이스에서 사용자가 접근할 수 있는 콘텐츠를 읽고 갱신할 수 있습니다. (Notion MCP 연결) |
| 최소 권한 | 연결 전 계정의 페이지 접근 범위와 워크스페이스 정책을 점검하세요. 읽기만 요청하는 것과 서버 차원의 읽기 전용 권한은 다릅니다. (Notion MCP 보안) |
| 위험 | 클라이언트가 Notion 밖으로 콘텐츠를 보낼 수 있고, 문서에 악성 지시가 포함될 수도 있습니다. 외부 공유와 수정은 사용자가 검토한 뒤 승인하세요. (Notion MCP 보안) |
권장 순서 — 실제 문서 작업 기록이 아닌 작업 계획입니다.
- 기획 문서의 접근 범위와 개인정보·사내 정보의 외부 처리 가능 여부를 먼저 확인합니다.
- Notion MCP 연결 안내에서 공식 호스팅 서버와 인증 방법을 확인하고, 연결 계정의 접근 권한을 검토합니다.
- Mirr Code MCP 연결 안내에 따라 등록과 인증을 시도하고
/mcp에서 제공 도구를 확인합니다. 이 조합의 호환성은 아직 검증되지 않았습니다. - 먼저 문서의 요구사항과 미결정을 요약하도록 요청합니다. Notion 페이지 수정이나 댓글 작성은 대상과 변경 내용을 사용자가 검토하고 승인한 경우에만 진행합니다.
- 작업 후 불필요한 연결 권한을 Notion에서도 철회합니다.
준비물과 권한#
사용 계정과 워크스페이스, 필요한 문서를 정하고 문서 소유자의 외부 처리 승인을 받으세요. 편집할 필요가 없다면 편집 도구와 실제 서비스 권한을 따로 제한할 수 있는지 확인합니다.
위 표는 공식 서버의 접근 원칙입니다. 특정 페이지의 공유 설정은 해당 워크스페이스에서 확인하세요.
설치와 연결#
환경별 설치 명령은 Mirr Code 설치 안내에서 확인하세요. Notion 서버와의 연결은 위 권장 순서를 참고하되, 실제 연결 결과는 아직 제공하지 않습니다.
실제 작업 예제#
기획 문서 조회와 수정은 위의 권장 순서입니다.
추가 검증 필요: Mirr Code와 Notion MCP의 실제 연결·인증 및 작업 실행 기록과 문서 변경 전후 증거는 아직 확보하지 않았습니다. 특정 페이지의 실제 공유 설정도 검증하지 않았습니다.
보안과 제한#
Notion에 보관되는 원문과 외부 클라이언트·모델이 처리하는 사본의 범위는 다릅니다. 원문에 있는 악성 지시가 다른 도구 호출로 이어지지 않도록 사용자가 승인한 작업 범위를 유지하세요.
위 표의 외부 전송과 프롬프트 인젝션 위험을 확인하세요. 실제 페이지의 공유 범위는 해당 워크스페이스에서 별도로 확인해야 합니다.
문제 해결과 자주 묻는 질문#
| 증상 | 확인할 항목 | 피할 대응 |
|---|---|---|
| OAuth 연결 실패 | 공식 서버 주소, 계정과 워크스페이스, 클라이언트 지원 | 인증 토큰을 문서나 공개 로그에 복사 |
| 문서를 찾지 못함 | 연결 계정으로 원문 접근 가능 여부, 페이지 위치와 검색 조건 | 위키 전체 공유 범위 확대 |
| 변경 도구가 보이지 않음 | 실제 노출 도구와 연결 상태 | 문서 요청만으로 편집 권한이 있다고 가정 |
| 수정 결과가 예상과 다름 | 대상 페이지와 변경 전후 내용, 동시 편집 여부 | 원문 확인 없이 전체 페이지 덮어쓰기 |
앞서 링크한 Notion 연결·보안 문서를 적용한 점검 순서입니다. 실제 페이지 공유 설정 화면, 도구 목록과 문서 변경 diff는 아직 필요합니다. 오류를 공유할 때는 문서 원문과 개인정보·토큰을 먼저 제거하세요.
문서를 연결하기 전에 공개 경계 정하기#
기획 문서를 코드 옆으로 가져올 때 먼저 질문할 것은 어떤 문서가 필요한가입니다. 워크스페이스 전체를 연결한 뒤 필요한 내용을 찾기보다 승인된 페이지와 목적을 좁히세요. 기능 수락 조건만 필요하다면 인사 정보, 고객 계약과 재무 자료는 읽을 이유가 없습니다. 연결 계정이 접근할 수 있는 범위와 이번 작업에서 읽기로 승인한 범위는 다를 수 있습니다. 계정의 접근 범위가 넓다면 클라이언트·서비스에서 더 제한할 수 있는지 검토해야 합니다.
Notion 안의 원문과 외부 클라이언트에 전달된 내용은 서로 다른 사본입니다. 원문 페이지의 공유 권한을 바꿔도 이미 모델에 보낸 내용의 보관이 자동으로 바뀌는 것은 아닙니다. 연결 전에 사용하는 클라이언트와 모델 제공자의 데이터 처리 조건을 확인하세요. 사내 문서가 공개 링크로 열리지 않는다고 외부 전송이 없는 것은 아닙니다. MCP 조회 결과가 대화 문맥과 로그에 어디까지 들어가는지도 검토해야 합니다.
| 정보 흐름 | 확인할 범위 | 피할 추정 |
|---|---|---|
| Notion 원문 | 계정·페이지·워크스페이스 접근 정책 | 원문이 비공개면 외부 처리도 없음 |
| MCP 응답 | 실제 조회 도구와 반환 내용 | 요약에 필요하니 모든 하위 페이지도 허용 |
| 클라이언트 문맥 | 대화·파일·로그에 남는 내용 | 연결을 지우면 전달된 사본도 삭제 |
| 모델 제공자 | 계약별 전송·보관·삭제 조건 | Notion의 보존 정책이 그대로 적용 |
| 후속 게시 | 코드 주석·PR·이슈로 옮길 정보 | 읽기 승인이 다른 서비스 공개 승인 |
이 표는 특정 조직의 정책을 확정하지 않습니다. 문서 소유자와 보안 담당자가 승인한 범위를 기록하는 데 사용하세요. 비식별 요약도 상세한 맥락으로 대상을 알아볼 수 있다면 민감할 수 있습니다. 원문을 전부 가져온 뒤 나중에 지우기보다 필요한 정보만 읽는 방식부터 검토하는 편이 좋습니다. 자료에 포함된 링크나 첨부 파일을 추가로 읽는 행동도 원래 범위를 넘는지 확인해야 합니다.
공식 호스팅 서버와 클라이언트 요구사항#
Notion의 공식 클라이언트 개발 안내는 Streamable HTTP와 SSE 주소, OAuth Authorization Code와 PKCE, 토큰 갱신과 안전한 자격 증명 저장을 설명합니다. 기본적으로 권장되는 HTTP 경로를 검토하되 해당 호스트가 필요한 인증 흐름을 실제로 지원하는지 확인해야 합니다. HTTP URL을 등록할 수 있다는 사실만으로 OAuth·갱신까지 동작한다고 판단하지 마세요. 이 글은 Mirr에서 그 경로를 실측하지 않았습니다.
다른 호스트의 설정 JSON과 로그인 화면은 그 호스트의 예시입니다. Mirr의 설정 형식과 비밀 저장 위치를 추정해 작성하지 않습니다. 공식 호스팅 서버와 별도의 오픈소스 서버도 구분하세요. 이름이 Notion MCP라고 같은 인증과 도구를 제공하는 것은 아닙니다. 서버를 바꾸면 운영 주체, 라이선스와 데이터 흐름도 다시 검토해야 합니다. 연결 오류를 해결하려고 출처를 확인하지 않은 대체 패키지를 설치하는 대응은 피합니다.
설치·인증 증거에는 호스트와 서버의 버전 또는 배포 정보를 가능한 범위에서 남깁니다. OAuth 화면에는 비밀값과 사용자 정보가 있을 수 있으므로 공유 전에 직접 가려야 합니다. 등록 성공, 인증 성공과 실제 도구 호출은 별도 단계입니다. 도구 목록이 보였더라도 선택한 페이지를 읽을 수 있는지는 실제 계정 권한과 문서 상태에 달려 있습니다. 반대로 페이지를 못 찾았다고 바로 위키 전체의 공유 범위를 넓히지 마세요.
기획 문서를 요구사항 표로 읽기#
첫 조회에서는 페이지 제목과 식별자, 대상 버전과 갱신 정보를 확인하고 사용자가 지정한 문서인지 대조합니다. 이름이 같은 페이지와 오래된 복사본이 있을 수 있습니다. 본문에서는 확정된 요구사항, 예시, 제안과 미결정을 나누세요. 표에 적힌 목표가 이미 구현됐다는 뜻은 아닙니다. 체크된 항목도 누가 어떤 기준으로 확인했는지 원문 맥락을 살펴야 합니다. 문서의 표현을 코드의 현재 동작으로 옮겨 적지 않습니다.
가상의 내보내기 기능 문서라면 허용 파일 형식, 대상 데이터, 권한, 빈 결과와 실패 표시를 수락 조건으로 추릴 수 있습니다. 숫자 제한과 날짜는 원문 그대로 보존하고 모호한 표현은 질문으로 남깁니다. 예를 들어 “빠르게”를 임의의 초 단위 성능 목표로 바꾸지 마세요. 문서에서 정하지 않은 기본값도 추측하지 않습니다. 요구사항 표의 각 항목에 근거 페이지와 위치를 연결하면 구현 검토자가 원문으로 돌아가기 쉽습니다.
코드 작업으로 넘길 때는 해당 요구사항이 현재 저장소의 어느 계약과 연결되는지 조사합니다. 문서와 코드가 다르면 어느 쪽이 정본인지 담당자에게 확인해야 합니다. 자동으로 문서를 코드에 맞추거나 코드를 문서에 맞추는 선택은 별도 결정입니다. 읽기 단계에서는 차이를 설명하고 미결정 질문을 남기는 것으로 충분할 수 있습니다. 문서를 연결했다는 사실이 파일 수정과 테스트 실행을 승인하지는 않습니다.
읽기 요청과 실제 읽기 전용 권한#
“요약만 해 줘”라는 문구는 도구 실행의 의도를 알려 주지만 편집 권한을 제거하지 않습니다. 노출된 수정 도구와 서비스 권한을 확인하고 필요한 경우 호스트의 승인 설정과 서비스의 접근 제한을 함께 검토하세요. 공식 보안 문서는 연결된 클라이언트가 사용자가 접근할 수 있는 콘텐츠를 다룰 수 있다고 설명합니다. 따라서 읽을 자료를 좁혀도 계정의 넓은 접근 권한이 자동으로 바뀌었다고 보고하면 안 됩니다.
도구 사용 가능 여부가 요금제나 연결 조건에 따라 달라지는 경우에는 실제 도구 목록과 공식 지원 도구 설명을 대조하세요. 문서에 나온 도구가 모든 계정에 보이거나 모든 인자를 사용할 수 있다고 가정하지 않습니다. 필요한 도구가 없으면 권한 부족, 연결 문제와 제공 범위를 나눠 조사합니다. 오류 메시지를 해결하려고 플랜 변경이나 유료 구매를 자동으로 진행하지 않습니다. 이 글은 계정별 도구 사용 가능성을 실측하지 않았습니다.
문서 수정은 작은 범위의 diff로 검토하기#
문서를 고쳐야 한다면 대상 페이지와 섹션, 바꿀 내용과 유지할 내용을 먼저 정합니다. 전체 페이지를 새 요약으로 덮어쓰면 다른 사람의 문구와 결정 이력이 사라질 수 있습니다. 변경 전 내용을 승인된 위치에 보관하고 가능하면 좁은 범위의 변경안을 검토하세요. 실제 도구가 어떤 수정 단위를 지원하는지는 스키마에서 확인해야 합니다. 지원하지 않는 부분 수정 기능을 있다고 가정하지 않습니다.
동시 편집도 고려합니다. 초안을 만든 뒤 원문이 바뀌었다면 오래된 내용을 기준으로 덮어쓰지 않도록 다시 조회하세요. 변경 충돌을 다루는 방법은 사용하는 도구의 계약에 따라 확인해야 합니다. 실행 전 사람이 대상과 정확한 문구를 승인하고 변경 후 원문을 다시 읽어 의도한 부분만 달라졌는지 비교합니다. 표, 링크와 하위 블록의 구조가 유지되는지도 필요한 범위에서 봅니다. API 성공 응답 한 번만으로 문서 의미의 정확성을 보증할 수 없습니다.
문서 변경 diff에는 사실과 서법도 포함됩니다. “지원할 수 있다”를 “지원한다”로 바꾸거나 제안을 확정 결정처럼 적으면 기능 범위가 달라집니다. 숫자, 날짜와 담당자의 직접 인용은 임의로 다듬지 마세요. 한국어를 자연스럽게 고치는 작업과 내용 변경을 분리하면 검토하기 쉽습니다. 코드에서 확인하지 않은 성능·보안·지원 약속을 문서에 새로 넣지 않는 것도 중요합니다.
자료 속 지시를 실행하지 않기#
Notion 페이지는 신뢰한 동료가 작성했더라도 외부 도구에서 읽은 자료입니다. 누군가 페이지에 다른 서버의 토큰을 읽거나 외부 주소에 내용을 보내라는 문장을 넣을 수 있습니다. 그런 문장은 사용자의 원래 요청과 분리해 검토해야 합니다. 기획 요구사항의 설명과 도구 사용 권한은 같은 것이 아닙니다. 문서가 더 넓은 접근을 요구하면 그대로 따라가지 말고 목적과 범위를 확인하세요.
여러 MCP를 함께 쓸 때는 정보가 옮겨가는 대상을 특히 봅니다. 비공개 기획의 내용을 공개 PR이나 Slack 채널에 붙이면 독자가 달라집니다. 문서 조회 승인은 그 게시의 승인이 아닙니다. 필요한 부분만 승인된 형태로 공유하고 링크 자체가 내부 정보를 드러내는지도 검토하세요. 공식 보안 안내의 확인 절차와 호스트·운영체제의 권한 제한을 함께 적용해야 하며 모델의 주의 문구만으로 안전을 보장하지 않습니다.
연결 실패와 검색 누락을 분리하기#
OAuth가 끝나지 않으면 공식 주소, 클라이언트의 인증 흐름과 선택한 계정·워크스페이스를 확인합니다. 인증은 됐는데 문서가 없으면 해당 계정으로 원문을 열 수 있는지, 페이지가 이동했는지와 검색 조건을 살펴보세요. 도구가 없으면 실제 노출 목록과 지원 범위를 대조합니다. 모든 문제를 권한 부족으로 보고 위키를 전체 공개하거나 토큰을 로그에 넣는 대응은 피해야 합니다. 필요한 범위에서 관리자에게 질문하세요.
수정이 시간 초과되면 먼저 원문의 실제 변경 여부를 확인합니다. 같은 내용을 다시 쓰거나 댓글을 재게시하면 중복될 수 있습니다. 연결 제거와 문서 복구는 별개이며 /rewind로 외부 문서가 자동 복원되지 않습니다. 작업 뒤에는 Notion의 연결 관리에서 불필요한 승인을 확인하고, 이미 외부로 전달한 사본의 보관·삭제는 해당 제공자의 조건을 검토해야 합니다. 권한 철회만으로 모든 사본이 지워졌다고 보장하지 않습니다.
실제 공유 설정과 읽기 결과를 준비할 때#
승인된 비식별 기획 페이지 하나를 정하고 실제 공유 설정, 인증, 도구 목록과 읽기 결과를 기록하는 과제를 검토할 수 있습니다. 수정까지 허용된다면 변경 전후의 같은 페이지를 비교하고 사람의 승인도 남겨야 합니다. 공개용 화면에서는 사용자 이름과 내부 문서 제목 등 불필요한 정보를 가립니다. 현재 이 글은 실제 페이지 공유 설정과 Mirr 연결·문서 변경을 수행한 증거를 갖추지 못했습니다. 문서 기반 설명을 완료된 연동 사례로 바꾸지 않습니다.
추가 근거: 공식 클라이언트 연결 요구사항, 보안과 관리자 통제, 지원 도구. 공식 호스팅 서버 설명이며 계정별 권한이나 Mirr 실행 결과의 근거는 아닙니다.
원문 근거를 코드 작업에 인계하는 기준#
요구사항을 코드 작업으로 넘길 때는 문장마다 무엇을 확인했는지 연결할 수 있어야 합니다. 페이지의 제목과 대상 버전, 관련 섹션과 수락 조건을 적되 불필요한 원문을 복사하지 않습니다. 문서가 바뀌면 구현 계획의 전제가 달라졌는지 검토하세요. 오래된 요약을 그대로 정본으로 쓰지 않는 것이 중요합니다. 코드 담당자가 원문에 접근할 수 없다면 승인된 요약의 범위와 미결정을 함께 전달해야 합니다. 접근할 수 없는 페이지의 내용을 추측해 채우지 않습니다.
인계받은 사람이 구현을 끝냈다고 문서의 모든 체크를 자동으로 바꾸지는 마세요. 수락 조건마다 실제 검사 자료와 연결하고 미실행 검사는 남겨야 합니다. 문서 수정, 댓글과 다른 서비스의 게시 중 어떤 작업을 승인했는지도 구분합니다. 이슈나 PR에 기획 내용을 옮길 때 독자가 달라지는지 확인하세요. 원문에서 읽기 승인을 받았다는 사실은 공개 저장소에 게시할 승인이 아닙니다. 이 경계를 지켜야 코드와 문서를 함께 쓰면서도 필요한 정보만 전달할 수 있습니다.
실제 변경 자료에는 읽은 페이지와 바꾼 페이지가 같은지 확인할 식별 정보가 필요합니다. 개인정보를 가린 화면에서도 대상과 범위를 알 수 있도록 준비하세요. 현재 이 글에는 실제 공유 설정 화면, 인증 결과와 문서 diff가 없으며 설명용 표로 그 빈 자리를 채우지 않습니다. 실제 자료가 생기면 해당 단계의 좁은 관찰로만 반영해야 합니다.
기획 문서의 첨부 이미지와 표도 별도 정보입니다. 본문만 읽었다면 이미지 안의 조건까지 확인했다고 보고하지 말고 필요한 검토 범위를 남기세요.
공식 엔드포인트와 프롬프트 주입 위험#
Notion 보안 안내는 공식 엔드포인트로 Streamable HTTP용 https://mcp.notion.com/mcp(권장)와 SSE용 https://mcp.notion.com/sse를 제시합니다(Notion MCP 보안 안내). 같은 문서는 연결된 클라이언트가 사용자가 접근할 수 있는 내용에 접근할 수 있다고 설명합니다. 또 신뢰할 수 없는 콘텐츠에 들어 있는 지시가 클라이언트의 동작을 바꾸려 하는 것을 프롬프트 주입으로 부릅니다.
요청문과 읽어 온 콘텐츠는 작업 기록에서 나눠 적으세요.
프롬프트 주입 위험은 콘텐츠를 명령으로 따르지 않는 설계로 줄이고, 그 효과는 실제 실행 결과로 확인하세요.
다음에 연결할 것#
문서 요약을 코드 작업으로 넘길 때는 원문 요구사항과 확인되지 않은 가정을 구분하세요.
문서를 작업에 활용할 때의 연결 구조는 MCP 외부 도구 연결 안내에서 더 확인할 수 있습니다.
관련#
편집 메모 (2026-11-02): 문서 접근·수정·권한 철회 FAQ와 진단표를 보충했습니다. 실제 설치·인증·공유 권한 화면, 도구 출력과 문서 diff는 확보하지 않았습니다.