MCP 연동

AFFiNE MCP 서버: AI 도구를 지식 베이스에 연결하기

AFFiNE 워크스페이스 MCP는 호환되는 AI 클라이언트가 노트와 화이트보드 텍스트를 검색하고 문서를 읽게 합니다. Streamable HTTP와 Bearer 헤더를 지원하면 직접 연결하며, 로컬 stdio를 지원하는 클라이언트는 브리지를 사용할 수 있습니다.

  • 워크스페이스 단위, 폐기 가능한 자격 증명
  • Streamable HTTP + Bearer
  • GitHub 스타 70K+

호환되는 AI 클라이언트로 지식 베이스 연결하기

MCP는 AI 도우미와 외부 도구·데이터를 연결하는 공개 표준입니다. 지원되는 AFFiNE Cloud 및 셀프호스팅 환경에는 워크스페이스 엔드포인트가 있습니다. 직접 연결에는 Streamable HTTP와 Authorization 헤더가 필요하며, stdio 전용 클라이언트에는 mcp-remote 같은 로컬 브리지가 필요합니다.

연결하면 어시스턴트가 화이트보드를 포함한 지식 베이스 전체에서 키워드·시맨틱 검색을 실행하고 문서 전문을 읽을 수 있습니다. 권한은 정확히 당신이 허용한 만큼만. 클라이언트마다 별도의 자격 증명을 발급하고 각각 독립적으로 교체·폐기할 수 있어, "AI가 내 노트를 본다"가 "전부를, 영원히"가 되지 않습니다.

AFFiNE MCP 서버 한눈에 보기

무엇인가AFFiNE Cloud와 셀프호스팅 인스턴스에 내장된 공식 Model Context Protocol 엔드포인트
엔드포인트POST /api/workspaces/{workspace-id}/mcp
전송 방식Streamable HTTP(무상태)
인증Bearer 자격 증명(aff_mcp_v1. 접두사), 워크스페이스 설정에서 클라이언트별 발급
도구doc_search / read_document; READ_WRITE: development / canary
범위자격 증명 하나당 워크스페이스 하나, 문서 권한 준수
가격AFFiNE Cloud와 AI 기능을 켠 셀프호스팅 인스턴스에서 무료

워크스페이스 연결과 공개 콘텐츠 데모

내 워크스페이스

AFFiNE Cloud 또는 지원되는 자체 환경에 연결합니다. 워크스페이스 Bearer 인증 정보가 필요하며 문서 권한을 따릅니다. 아래 도구는 읽기 전용 기본값이며 배포 환경에 따라 다릅니다.

https://app.affine.pro/api/workspaces/{workspace-id}/mcp
  • doc_search
  • read_document

공개 웹사이트 콘텐츠

게시된 블로그와 템플릿만 읽는 별도 서비스입니다. 계정이나 인증 정보가 필요하지 않습니다. 내 워크스페이스를 읽거나 문서를 쓸 수 없습니다. 이 주소에 워크스페이스 인증 정보를 보내지 마세요.

https://affine.pro/api/public/mcp
  • search_public_content
  • read_public_content
Public content API (English)

호환되는 MCP 클라이언트 연결

AFFiNE에서 워크스페이스 인증 정보를 만든 다음 클라이언트에 맞는 형식으로 설정하세요.

  1. 워크스페이스의 MCP 설정 열기

    AFFiNE에서 설정 → Integrations → MCP Server로 이동합니다. AFFiNE Cloud와 AI 기능을 켠 셀프호스팅 인스턴스에서 사용할 수 있습니다.

  2. 자격 증명 만들기

    'Create credential'을 클릭하고 라벨을 붙입니다(클라이언트당 하나, 예: 'Claude Code', 'Cursor'). 접근 모드와 만료일을 선택하세요. 기본값은 읽기 전용입니다.

  3. 구성을 클라이언트에 붙여넣기

    AFFiNE에서 엔드포인트와 인증 정보를 복사하세요. 토큰은 한 번만 표시됩니다. 모든 클라이언트가 같은 JSON을 받는 것은 아니므로 아래의 해당 예제를 사용하세요.

{
"mcpServers": {
"affine_workspace_<workspace-id>": {
"type": "streamable-http",
"url": "https://app.affine.pro/api/workspaces/<workspace-id>/mcp",
"headers": { "Authorization": "Bearer aff_mcp_v1...." }
}
}
}

AFFiNE가 생성하는 연결 형식입니다. 클라이언트에 맞게 조정하세요. 셀프호스팅에서는 자신의 서버 주소를 사용합니다.

클라이언트별 연결 방법

전송 방식과 인증 방식을 모두 확인하세요. Claude Code, Cursor, Cline은 HTTP와 Bearer 헤더를 지원합니다. OAuth 로그인만 받는 연결 화면에서는 수동 발급 인증 정보를 사용할 수 없습니다. 로컬 프로세스를 실행할 수 있는 클라이언트만 stdio 브리지를 사용할 수 있습니다.

Claude Code

CLI 명령 하나로 AFFiNE을 추가하고, 어느 세션에서든 Claude에게 워크스페이스 검색과 읽기를 맡기세요.

claude mcp add --transport http affine \
"https://app.affine.pro/api/workspaces/<workspace-id>/mcp" \
--header "Authorization: Bearer <your-credential>"

Cursor

아래 URL과 headers를 ~/.cursor/mcp.json에 추가하세요. 자신의 워크스페이스에서 복사한 주소와 인증 정보를 사용합니다. 클라이언트마다 JSON 형식이 다릅니다.

{
"mcpServers": {
"affine": {
"url": "https://app.affine.pro/api/workspaces/<id>/mcp",
"headers": {
"Authorization": "Bearer <your-credential>"
}
}
}
}

Cline

Cline의 MCP 설정을 열고 AFFiNE을 원격 Streamable HTTP 서버로 추가합니다.

{
"mcpServers": {
"affine": {
"type": "streamableHttp",
"url": "https://app.affine.pro/api/workspaces/<id>/mcp",
"headers": {
"Authorization": "Bearer <your-credential>"
}
}
}
}

Claude Desktop 등 로컬 stdio 클라이언트

로컬 stdio 프로세스를 실행할 수 있는 클라이언트용 설정입니다. 서드파티 mcp-remote와 지원되는 Node.js가 필요합니다. Claude 웹 OAuth 커넥터가 아닙니다.

{
"mcpServers": {
"affine": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.affine.pro/api/workspaces/<workspace-id>/mcp",
"--header",
"Authorization:${AFFINE_MCP_AUTH}"
],
"env": {
"AFFINE_MCP_AUTH": "Bearer <your-credential>"
}
}
}
}

연결된 어시스턴트가 할 수 있는 일

기본값은 읽기 전용입니다. 2026년 10월 26일 확인한 구현에서 읽기·쓰기 인증 정보 생성과 쓰기 도구는 개발 또는 canary 환경으로 제한됩니다. 안정 버전 Cloud 제공을 입증하지는 않습니다. 현재 환경의 접근 모드와 tools/list로 사용 가능한 도구를 확인하세요.

읽기 전용

기본값
doc_search
문서 검색

워크스페이스 문서 전반의 키워드·시맨틱 검색. 페이지 또는 캔버스 위치 정보와 함께 범위가 제한된 발췌를 반환합니다. 파일, 블롭, 웹에는 접근하지 않습니다.

read_document
문서 읽기

ID로 문서 전문을 가져옵니다. 현재 워크스페이스 권한을 준수합니다.

읽기·쓰기

Development / canary
create_document
문서 생성

활성화된 환경에서 제목과 Markdown 본문으로 문서를 만듭니다. 데이터베이스 블록과 이미지 삽입은 지원하지 않습니다.

update_document
문서 수정

활성화된 환경에서 구조 차이를 적용해 Markdown 본문을 수정합니다. 제목, 데이터베이스 블록, 이미지는 수정하지 않습니다.

update_document_meta
메타데이터 수정

활성화된 환경에서 문서 제목을 수정합니다. 확인한 도구에는 다른 메타데이터 필드가 없습니다.

워크스페이스 단위

자격 증명 하나가 닿는 범위는 워크스페이스 하나, 당신의 권한 안에서만.

클라이언트당 하나

다른 클라이언트에 영향 없이 특정 클라이언트의 접근만 폐기할 수 있습니다.

만료일 기본 내장

모든 자격 증명에 생성 시점에 만료일을 설정합니다.

토큰 교체

기존 토큰은 최대 24시간 또는 기존 만료 시각 중 더 이른 시점까지 유효합니다. 폐기하면 접근이 더 일찍 끝날 수 있습니다.

AFFiNE MCP 서버 비교

이제 MCP를 지원하는 노트 도구는 많습니다. 차이는 서버가 닿는 범위, 실행되는 곳, 통제하는 주체에서 갈립니다. 가장 많이 비교되는 두 구성과 견줘 봤습니다.

AFFiNENotion MCPObsidian
퍼스트파티 내장예앱에 내장된 퍼스트파티 서버, 자격 증명은 워크스페이스 설정에서 발급예Notion이 호스팅하는 공식 원격 서버아니요커뮤니티 플러그인 또는 서드파티 서버
셀프호스팅 가능예동일한 공식 엔드포인트, 자신의 인스턴스에서 AI 기능 활성화아니요현행 서버는 호스팅 전용, 구 오픈소스 서버는 지원 중단조건부기본은 로컬, 원격화는 직접 구축
화이트보드 검색예Edgeless 캔버스 텍스트를 색인하고 요소·프레임 위치 정보를 반환아니요Notion에는 네이티브 화이트보드가 없음아니요.canvas 파일은 원시 JSON으로만 읽힘, 검색하는 주류 서버 없음
배포 형태Cloud/셀프호스팅AFFiNE 내장 공식 엔드포인트, 셀프호스팅은 AI 기능 활성화 필요호스팅 전용현행 공식 서버는 Notion이 호스팅로컬커뮤니티 서버가 데스크톱 Vault 옆에서 실행
가격무료Cloud에서도 AI 기능을 켠 셀프호스팅에서도 무료코어 무료연결 앱 검색과 회의록은 Notion AI 플랜 필요무료앱도 커뮤니티 서버도 무료

비교는 2026년 8월 기준 공개 문서를 근거로 합니다.

Obsidian의 REST API 기반 MCP 서버는 데스크톱 앱이 켜져 있어야 합니다. Obsidian 공식 CLI(2026)는 공식 자동화 수단이지만 MCP가 아닙니다.

자주 묻는 질문

AFFiNE MCP 서버란 무엇인가요?

AFFiNE에 내장된 공식 Model Context Protocol 엔드포인트입니다. Claude, Cursor, Cline 같은 AI 어시스턴트가 표준 인증 HTTP 연결로 워크스페이스 문서를 검색하고 읽을 수 있게 해 줍니다. 자격 증명은 워크스페이스 설정에서 직접 만들고 관리합니다.

무료로 쓸 수 있나요?

네. AFFiNE Cloud에서도, AI 기능을 켠 셀프호스팅 인스턴스에서도 무료입니다. 연결 자체에 추가 요금은 없습니다.

AI가 화이트보드도 검색할 수 있나요?

네. doc_search는 페이지 문서와 Edgeless 화이트보드를 함께 다룹니다. 캔버스 위 텍스트가 색인되고 결과에 블록·요소·프레임 위치 정보가 붙어, 화이트보드 어디에 답이 있는지까지 짚어 줍니다. 전문 읽기는 페이지 본문을 반환하고, 화이트보드 내용은 검색으로 드러납니다. 텍스트 전용 MCP 서버와의 결정적 차이입니다.

셀프호스팅 AFFiNE에서도 작동하나요?

네. 공식 MCP 엔드포인트는 셀프호스팅 인스턴스에서도 동일하게 제공됩니다. 엔드포인트가 자신의 서버 주소에 놓일 뿐 설정 절차는 같습니다(설정 → Integrations → MCP Server). 인스턴스에서 AI 기능을 켜야 합니다.

읽기 전용으로 둘 수 있나요?

기본값은 읽기 전용입니다. 2026년 10월 26일 확인한 구현에서 읽기·쓰기 인증 정보 생성과 쓰기 도구는 개발 또는 canary 환경으로 제한됩니다. 안정 버전 Cloud 제공을 입증하지는 않습니다. 현재 환경의 접근 모드와 tools/list로 사용 가능한 도구를 확인하세요.

어떤 AI 도구를 연결할 수 있나요?

전송 방식과 인증 방식을 모두 확인하세요. Claude Code, Cursor, Cline은 HTTP와 Bearer 헤더를 지원합니다. OAuth 로그인만 받는 연결 화면에서는 수동 발급 인증 정보를 사용할 수 없습니다. 로컬 프로세스를 실행할 수 있는 클라이언트만 stdio 브리지를 사용할 수 있습니다.

접근은 어떻게 보호되나요?

자격 증명 하나가 닿는 범위는 워크스페이스 하나, 당신의 권한 안에서만. 다른 클라이언트에 영향 없이 특정 클라이언트의 접근만 폐기할 수 있습니다. 모든 자격 증명에 생성 시점에 만료일을 설정합니다. 기존 토큰은 최대 24시간 또는 기존 만료 시각 중 더 이른 시점까지 유효합니다. 폐기하면 접근이 더 일찍 끝날 수 있습니다.

지식 베이스를 일하게 만드세요

워크스페이스 설정에서 자격 증명을 만들면, AI 도구가 오늘부터 당신의 노트로 답하기 시작합니다.

최종 수정: 2026년 10월 26일