Flexnote MCP: Cursor와 Codex에서 로컬 지식 베이스에 접근하기

Cursor나 Codex 에서 작업할 때, 로컬 노트——이전의 결정, 문헌 발췌, 보드 레이아웃——를 참조하고 싶어지는 일이 많습니다. 다른 채팅에 텍스트를 복사하거나, 앱을 전환하면, 지식 베이스와 지금의 워크플로가 끊어집니다.

Flexnote 데스크톱 앱에는 지금 MCP 서버(Model Context Protocol)가 포함됩니다. 서비스는 127.0.0.1 만 대기합니다. 프로토콜을 구현하는 클라이언트——Cursor, Claude Desktop, Codex 를 포함——는, 현재 라이브러리를 검색·읽기·쓸 수 있습니다. 데이터는 사용자 단말에 남고, 제3자 노트 클라우드로 업로드되지 않습니다.

1. MCP와 앱 안 Flexnote AI의 차이

MCP 는, 외부 AI 클라이언트가 부를 수 있는 도구를 선언하기 위한 오픈 프로토콜입니다. 클라이언트는 도구 목록을 얻고, 이름으로 호출하고, JSON 텍스트를 받습니다. 모델은 클라이언트 측에서 고르고, Flexnote 는 과금이나 프로바이더를 중개하지 않습니다.

앱 안의 Flexnote AI 는 사이드바에서 돌아갑니다: 설정에서 구성한 API 키를 쓰고, 답변에는 인용이 붙고, Agent 는 보드를 편집할 수 있습니다. MCP는 같은 라이브러리를 외부 개발 도구에 공개하므로, 에디터를 떠나지 않고 일기, 카드, ToDo, 화이트보드를 쓸 수 있습니다.

2. 스코프

현재 워크스페이스 안의 카드, 일기, 화이트보드, ToDo, 태그, 컬렉션을 조회할 수 있습니다. 쓰기 도구에는 읽기 전용 모드를 꺼야 합니다. Canvas 조작에는 화이트보드 ID 가 필요합니다. 보드가 열려 있지 않으면, Flexnote 는 그리로 이동하고 캔버스 준비가 될 때까지 기다리므로, 클라이언트의 요청이 타임아웃하지 않습니다.

3. 서버 활성화

MCP는 Pro 기능입니다. 유효한 멤버십으로 로그인이 필요하고, Flexnote 데스크톱 앱이 기동되어 있어야 합니다. 앱을 종료하면 로컬 포트는 닫히고, 클라이언트는 연결할 수 없습니다.

1. Flexnote → 설정 → MCP server를 연다.
2. 서비스를 활성화한다. 루프백만 바인드합니다. 기본 포트는 39125입니다.
3. 클라이언트용 설정을 복사한다: Cursor / Claude Desktop용 HTTP JSON.command 를 기동하는 클라이언트용 stdio 브리지. Codex CLI용 TOML.
4. 설정을 클라이언트에 더한다. 액세스 토큰은 로컬 인증 전용입니다. 공개 리포지토리에 커밋하거나 공유하지 마세요.

관련된 추가 옵션이 두 가지 있습니다: 읽기 전용 모드 는 조회 도구만 공개하고, 첫 연결 테스트에 맞습니다. 외부 모델에 넘기고 싶지 않은 도구는 개별적으로 비활성화할 수 있습니다.

4. Cursor, Claude Desktop, Codex의 연결

Cursor / Claude Desktop

설정에서 HTTP 구성을 씁니다. 필요한 필드는 로컬 URL과 Bearer 토큰입니다:

{
  "mcpServers": {
    "flexnote": {
      "url": "http://127.0.0.1:39125/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Codex CLI

Codex CLI는 보통 stdio 브리지를 씁니다: Node가 Flexnote 제공 스크립트를 실행하고, 표준 입력을 로컬 HTTP 엔드포인트로 전달합니다. 설정에서 TOML 구성을 복사하고, 스크립트 위치를 확인할 수 있습니다. 환경 변수에 FLEXNOTE_MCP_URL과 FLEXNOTE_MCP_TOKEN을 설정합니다.

5. 요청의 예

연결이 확립된 뒤, 도구 이름은 필요 없습니다. 자연어 요청으로 충분합니다. 다음 문장으로 연동을 확인할 수 있습니다:

• 「지금 열린 Flexnote 워크스페이스는 어느 것? 최근 화이트보드와 카드를 5 건 목록해. 데이터는 일절 변경하지 마.»
• 「이 결론을 오늘 일기에 추기해. 없으면 만들어. 보통 노트 카드로는 저장하지 마.»
• 「제목이 MCP trial 인 노트를 만들어. 본문은 Markdown 제목 1 로 시작해.»
• 「지정한 화이트보드(whiteboardId 를 넘김)에 스티커를 두 개 만들고, 잇고, 캔버스 레이아웃을 읽어.»
• 「ToDo를 목록하고, 하나를 완료로 해.»

쓰기가 성공하면, Flexnote 는 창에 알림을 표시합니다. 일치하는 엔티티가 있으면, 「표시」로 대응 페이지를 열고, 없으면 화면을 갱신할 수 있습니다. 알림은 닫을 때까지 남습니다.

6. 보안

서비스는 localhost 만 대기합니다. 같은 단말 위에서 액세스 토큰을 가진 다른 프로세스는, 같은 도구를 부를 수 있습니다. 토큰은 자격 정보로 다루세요. 설정에서 재생성하면, 이전 구성은 바로 무효가 됩니다.

쓰기 도구가 유효할 때, 외부 모델은 라이브러리를 변경할 수 있습니다. 첫 검증에서는 읽기 전용 모드를 켜거나, 만들기·삭제·화이트보드 도구를 끄세요. MCP 는 지금 열린 워크스페이스 에만 적용됩니다. 쓰기 전에 워크스페이스를 확인하세요.

7. 제한

• 데스크톱 앱 없는 브라우저만 이용에서는, 로컬 MCP 포트가 없습니다.
• 팀용 게이트웨이가 아니며, 공중망 액세스도 없습니다. 다른 사람과 라이브러리를 공유하는 용도가 아닙니다.
• Flexnote 는 실시간 다인 화이트보드가 아니며, MCP 도 그 능력을 더하지 않습니다. 제품의 범위는 Flexnote란 을 참조하세요.

8. 시작하기

MCP 를 포함한 빌드로 데스크톱 앱을 업데이트하고, Pro 계정으로 로그인하고, 설정에서 서버를 활성화하고, 설정을 Cursor 또는 Codex 에 더합니다. 쓰기를 켜기 전에, 읽기 전용 모드로 검색을 확인하세요. 클라이언트는 다운로드 페이지에서. Pro의 자세한 내용은 요금에 있습니다.

기존의 앱 안 지식 Agent 워크플로를 바꿀 필요는 없습니다. MCP 는 같은 로컬 라이브러리를 외부 개발 도구에 잇습니다.