AI 도구 연결 및 자동 기록 (MCP)

MashNote에 AI 도구를 연결한다는 것은 해당 도구에 MashNote를 플러그인, MCP 커넥터 또는 MCP 서버로 추가하고 로그인하는 것을 뜻합니다. 연결하면 AI가 끝낸 작업의 요약을 MashNote 활동으로 기록합니다. 원문 대화는 보내지 않고 작업 요약만 보냅니다.

MCP(Model Context Protocol)는 AI 도구가 외부 서비스의 기능을 사용할 수 있게 연결하는 표준입니다. 이 문서에서는 이후 MCP로 표기합니다.

MashNote의 MCP 도구로 활동을 기록할 수 있습니다. ChatGPT 데스크톱 앱·Codex CLI의 MashNote 플러그인은 OAuth에서 노트 읽기와 워크스페이스 접근을 승인하면 승인한 워크스페이스의 노트를 읽을 수도 있습니다.

도구	하는 일
`log_activity`	활동 한 건을 기록합니다.
`list_workspaces`	기록 위치를 정할 때 내가 속한 워크스페이스의 이름과 ID를 확인합니다.
`list_recent_activity`	같은 내용을 두 번 기록하지 않도록 내가 최근 기록한 활동을 확인합니다.
:::

시작하기 전에

연결 방법과 프롬프트는 MashNote의 AI 도구 연결 (MCP) 카드에서 만들 수 있습니다.

내비게이션 레일 아래쪽의 아바타(계정 메뉴)를 열고 설정을 선택합니다.
개인 설정에서 연동 탭을 엽니다.
AI 도구 연결 (MCP) 카드를 펼칩니다.

카드는 다음 순서로 구성되어 있습니다.

카드 영역	내용
1. 사용할 AI 도구	ChatGPT, Claude, Cursor, Antigravity, 기타 중 하나를 고릅니다. ChatGPT는 chatgpt.com / 데스크톱 앱, Claude는 웹·데스크톱 앱 / Claude Code (CLI) 중 사용 환경도 고릅니다.
2. 제품별 연결 방법 (제목은 고른 제품에 따라 바뀜)	복사할 MashNote MCP 주소 또는 명령어와 설치 단계가 표시됩니다. 설정 화면과 CLI를 모두 지원하는 제품은 설정 화면 / CLI로 설정 중에서 고를 수 있습니다. 자세한 연결 가이드를 누르면 이 문서의 해당 제품 항목이 열립니다.
3. 도구 활성화 확인	연결 뒤 새 대화에서 확인할 항목입니다. 문제가 있으면 연결됐는데 도구가 안 보이나요? 문제 해결을 누르세요.
4. 자동 기록 프롬프트	기록 목적지를 고르면 영어 프롬프트가 만들어집니다.
고급 설정 · 직접 연결	커넥터 주소, 접근 토큰 발급, 연결된 클라이언트와 발급된 토큰 해제

카드 위쪽에는 연결 상태가 표시됩니다. 연결한 뒤 아직 기록이 없으면 설정됨 · 기록 미확인, 기록이 한 건이라도 들어오면 자동 기록 확인 · {date}로 바뀝니다.

모든 AI 도구의 공통 연결 흐름

제품마다 메뉴 이름은 다르지만 연결 과정은 같습니다.

AI 도구 연결 (MCP) 카드에서 사용하는 AI 도구의 설치 안내를 확인합니다.
AI 도구에 MashNote 플러그인, MCP 커넥터 또는 서버를 추가합니다. ChatGPT 데스크톱 앱·Codex CLI에서는 아래의 마켓플레이스 설치 안내를 따릅니다.
브라우저에 열리는 MashNote 연결 승인 페이지에서 허용을 누릅니다. 자세한 내용은 연결 승인 페이지를 참고하세요.
새 대화나 새 작업을 열고 MashNote 도구를 활성화합니다. log_activity, list_workspaces, list_recent_activity가 보이는지 확인하세요.
카드에서 만든 자동 기록 프롬프트를 AI 도구의 지침에 붙여넣습니다.

연결 승인 페이지

AI 도구에서 MashNote 로그인을 시작하면 브라우저에 MashNote의 연결 승인 페이지가 열립니다. MashNote에 로그인되어 있지 않으면 먼저 로그인 화면이 나오고, 로그인 후 이 페이지로 돌아옵니다.

제목에 {clientName} 연결처럼 연결하려는 앱 이름이 표시됩니다.
요청 권한에서 활동 기록 등 연결하려는 도구가 요청하는 권한을 확인합니다. ChatGPT 데스크톱 앱·Codex CLI의 MashNote 플러그인을 설치할 때는 노트 읽기 권한과 접근할 워크스페이스도 승인합니다.
허용을 누르면 연결이 완료되고 AI 도구로 돌아갑니다. 거부를 누르면 연결이 취소됩니다.
확인되지 않은 앱 경고가 보이면, 앱 이름을 개발자가 직접 등록했고 MashNote가 확인하지 않았다는 뜻입니다. 방금 직접 연결을 시작한 앱이 맞는지 확인한 뒤 허용하세요.

제품별 연결 방법

ChatGPT

카드에서 ChatGPT를 고른 뒤 사용 환경으로 chatgpt.com 또는 데스크톱 앱을 선택합니다.

chatgpt.com

ChatGPT의 사용자 설정 → Apps → Advanced Settings에서 Developer mode를 켭니다.
Apps → Create에서 사용자 지정 앱을 만들고 MashNote MCP 주소를 입력합니다.
Scan Tools와 OAuth 로그인(MashNote 연결 승인)을 마친 뒤 Create를 눌러 앱을 추가합니다.
새 대화를 열고 도구 메뉴에서 MashNote 앱을 선택합니다.
log_activity, list_workspaces, list_recent_activity가 보이는지 확인합니다. 도구가 없으면 Apps 설정에서 MashNote를 새로고침한 뒤 새 대화를 다시 엽니다.

특정 업무를 계속 기록한다면 ChatGPT Project의 지시사항에 프롬프트를 넣는 방식을 권장합니다.

ChatGPT 데스크톱 앱 · Codex CLI

마켓플레이스를 추가한 뒤 MashNote 플러그인을 설치합니다.

데스크톱 앱 또는 Codex CLI의 플러그인 관리에서 마켓플레이스 추가를 선택합니다.
다음 마켓플레이스 주소를 입력합니다.
```
https://github.com/lymeric-ai/mashnote-plugin.git
```
추가한 마켓플레이스에서 MashNote 플러그인을 설치합니다.
설치한 플러그인의 OAuth 로그인을 시작합니다.
브라우저에서 MashNote에 로그인합니다.
연결 승인 화면에서 노트 읽기 권한과 접근할 워크스페이스를 승인합니다.
데스크톱 앱을 다시 시작합니다. Codex CLI를 사용한다면 종료한 뒤 새 세션을 시작합니다.
새 대화를 열고 @MashNote를 선택합니다.
log_activity 등 MashNote 도구가 보이는지 확인한 뒤 자동 기록 프롬프트를 적용합니다.

이미 설치한 경우에는 데스크톱 앱에서 마켓플레이스를 갱신한 뒤 MashNote 플러그인을 업데이트하거나 재설치하세요. OAuth 로그인과 노트 읽기·워크스페이스 승인을 완료하고, 앱을 재시작한 뒤 새 대화에서 @MashNote를 선택합니다.

프롬프트는 Codex의 전역 지침이나 프로젝트의 AGENTS.md에 넣을 수 있습니다.

Claude (웹·데스크톱 앱)

카드에서 Claude → 웹·데스크톱 앱을 고릅니다. 한 번 추가한 원격 MCP 커넥터는 Claude 웹과 데스크톱 앱에서 함께 사용할 수 있습니다.

Claude의 Settings → Connectors에서 Add custom connector를 선택합니다.
이름을 MashNote로 정하고 MashNote MCP 주소를 입력합니다.
Connect를 눌러 로그인(MashNote 연결 승인)한 뒤 연결 상태가 active인지 확인합니다.
새 대화를 열고 Search and tools에서 MashNote를 켭니다.
log_activity, list_workspaces, list_recent_activity가 보이는지 확인합니다. 권한은 켜져 있는데 도구가 없으면 Connectors에서 MashNote를 재연결한 뒤 새 대화를 엽니다.

active 표시는 계정 연결 상태입니다. 새 대화에서 MashNote를 켜고 실제 도구 목록을 확인해야 자동 기록 준비가 끝납니다.

특정 업무를 계속 기록한다면 Claude Project의 지시사항에 프롬프트를 넣는 방식을 권장합니다.

Claude Code (CLI)

카드에서 Claude → **Claude Code (CLI)**를 고르면 내 MashNote MCP 주소가 들어간 Claude Code 명령어가 표시됩니다. 사용자 범위로 등록하므로 모든 프로젝트에서 같은 연결을 사용합니다.

claude mcp add --transport http --scope user mashnote '<MASHNOTE_MCP_URL>'

위 명령어를 터미널에 붙여넣어 사용자 범위 MCP 서버를 추가합니다.
Claude Code를 열고 /mcp에서 MashNote 인증을 시작합니다.
브라우저에서 MashNote 로그인과 연결 승인을 마친 뒤 Claude Code로 돌아옵니다.
/mcp에서 MashNote가 connected인지 확인합니다. 연결 중이던 세션이라면 Claude Code를 다시 시작해 도구를 새로 불러옵니다.
새 작업에서 log_activity와 list_workspaces가 보이는지 확인합니다.

프롬프트는 사용자 CLAUDE.md(모든 프로젝트) 또는 프로젝트의 CLAUDE.md에 넣습니다.

Cursor

Cursor IDE와 Cursor CLI는 같은 MCP 설정을 읽습니다. 카드에서 설정 화면 또는 CLI로 설정을 고를 수 있습니다.

설정 화면에서 추가

Cursor Settings에서 Tools & MCP를 열고 새 MCP 서버를 추가합니다.
서버 이름은 MashNote, 유형은 Streamable HTTP로 정한 뒤 MashNote MCP 주소를 입력합니다.
OAuth 로그인(MashNote 연결 승인)을 마치고 Available Tools를 새로고침합니다.
Tools & MCP의 Available Tools에서 MashNote를 켭니다.
새 Agent 작업에서 log_activity가 보이는지 확인합니다.

`mcp.json`과 CLI로 추가

다음 설정을 전역 ~/.cursor/mcp.json 또는 프로젝트의 .cursor/mcp.json에 추가합니다.

{
  "mcpServers": {
    "mashnote": {
      "url": "<MASHNOTE_MCP_URL>"
    }
  }
}

Cursor CLI에서 agent mcp login mashnote를 실행해 로그인합니다.
agent mcp list-tools mashnote로 MashNote 도구가 보이는지 확인합니다.
agent mcp list로 MashNote가 connected인지 확인합니다.

프롬프트는 Cursor의 사용자 Rules 또는 프로젝트 Rules에 넣습니다.

Antigravity

Antigravity 데스크톱과 CLI는 같은 MCP 설정을 읽습니다. 카드에서 설정 화면 또는 CLI로 설정을 고를 수 있습니다.

설정 화면에서 추가

Settings → Customizations → Installed MCP Servers를 엽니다.
Add MCP를 누르고 사용자 지정 서버에 MashNote MCP 주소를 serverUrl로 입력합니다.
추가된 MashNote에서 Authenticate를 눌러 브라우저 로그인(MashNote 연결 승인)을 완료합니다.
Installed MCP Servers에서 MashNote를 활성화하고 Refresh를 누릅니다.
새 작업에서 log_activity가 보이는지 확인합니다.

설정 파일과 CLI로 추가

다음 설정을 전역 ~/.gemini/config/mcp_config.json 또는 프로젝트의 .agents/mcp_config.json에 추가합니다.

{
  "mcpServers": {
    "mashnote": {
      "serverUrl": "<MASHNOTE_MCP_URL>"
    }
  }
}

Antigravity CLI를 열고 /mcp에서 구성을 Reload합니다.
MashNote를 선택해 인증을 마친 뒤 연결 상태를 확인합니다.
/mcp에서 MashNote 상태와 도구 목록을 확인합니다.

프롬프트는 Antigravity의 전역 지침이나 프로젝트의 AGENTS.md에 넣을 수 있습니다.

기타 MCP 지원 도구

카드에서 기타를 고릅니다. 사용 중인 AI 도구가 다음을 지원하는지 먼저 확인하세요.

원격 Streamable HTTP MCP 서버
OAuth 로그인 (지원하지 않으면 접근 토큰으로 연결)
MCP 도구 목록 새로고침

지원한다면 다음 순서로 연결합니다.

앱의 MCP, Tools 또는 Connectors 설정을 엽니다.
MashNote를 원격 Streamable HTTP 서버로 추가하고 MashNote MCP 주소를 입력합니다.
OAuth 로그인(MashNote 연결 승인)을 완료한 뒤 도구 목록을 새로고침합니다.
앱의 도구 목록에서 MashNote를 활성화하고, log_activity와 list_workspaces가 보이는지 확인합니다.
도구가 없다면 서버를 다시 불러오거나 새 대화를 엽니다.

사용 중인 앱이 사용자 지침이나 프로젝트 지침을 지원한다면 자동 기록 프롬프트를 해당 위치에 붙여넣으세요.

도구 활성화 확인

Connected나 active 표시만으로는 자동 기록 준비가 끝난 것이 아닙니다. 새 대화나 새 작업에서 MashNote 도구가 실제로 보이는지 확인하세요.

새 대화 또는 새 작업을 엽니다.
MashNote 도구를 직접 활성화합니다.
도구 목록을 새로고침합니다.
다음 세 도구가 표시되는지 확인합니다.
- log_activity
- list_workspaces
- list_recent_activity
AI에게 “MashNote에 테스트 활동 한 건을 기록해 줘”라고 요청합니다.
MashNote의 내 매시에 테스트 활동이 나타나는지 확인합니다. AI 도구 연결 (MCP) 카드의 상태도 자동 기록 확인 · {date}로 바뀝니다.

자동 기록 프롬프트

AI가 작업을 마칠 때마다 스스로 기록하게 하려면, 카드의 4. 자동 기록 프롬프트에서 만든 프롬프트를 AI 도구의 지침에 붙여넣습니다. 프롬프트는 영어로 만들어집니다.

기록 목적지를 고릅니다. 기본값은 **나에게만 기록 (기본)**이며, 내가 속한 워크스페이스를 고를 수도 있습니다.
프롬프트 적용 위치를 고릅니다. 고른 제품에 맞게 전역(개인) 지침과 프로젝트 지침 중에서 선택합니다. 기타에서는 이 칸 대신 붙여넣을 위치 안내가 표시됩니다.
필요하면 도구가 없을 때 복사용 기록도 표시를 켭니다.
미리보기를 확인하고 프롬프트 복사를 누릅니다.
고른 위치에 붙여넣습니다.

프롬프트 본문은 제품에 따라 두 종류 중 하나로 자동 선택되고, 끝에 기록 목적지 부분이 붙습니다.

프롬프트	사용하는 제품
대화형 AI용	chatgpt.com, Claude 웹·데스크톱 앱
코딩 도구용	ChatGPT 데스크톱 앱·Codex CLI, Claude Code, Cursor, Antigravity, 기타

아래는 **나에게만 기록 (기본)**을 골랐을 때 만들어지는 프롬프트입니다. 카드에서 복사하는 것을 권장하지만, 아래 내용을 그대로 써도 같습니다.

대화형 AI용 프롬프트

MashNote is an append-only activity ledger exposed through the `log_activity`,
`list_workspaces`, and `list_recent_activity` connector tools.

## When to log
Proactively append one entry after a completed, meaningful work unit: a decision,
deliverable, agreement, or review with a conclusion. Do not log every turn, pure
exploration, trivial one-offs, or casual chat.

## What to write
- Capture the outcome and useful rationale, not the raw conversation.
- Use a short title, a concise summary, and optional points or markdown detail.
- Choose one to three short tags for the current line of work. Reuse the same tags
  on later entries while this thread continues that work; change them when the topic changes.
- Use one stable `idempotencyKey` per completed work unit.
- Never include secrets, credentials, card numbers, or national ID numbers.

## Tool behavior
- Actually call `log_activity` when it is available.
- Never claim a write succeeded unless the tool result confirms it.
- If the tool is unavailable, say so briefly. Only print a manual ledger entry if
  I explicitly ask for one.
- The ledger is append-only. Do not rewrite or organize earlier entries.

## Destination
Use the personal/default route and omit `workspaceId` when calling
`log_activity`. The server may apply a workspace connection I have already saved.
Do not call `list_workspaces` and do not ask me to choose a destination. Only pass an
explicit workspaceId when I request one in the current conversation.

코딩 도구용 프롬프트

## MashNote activity ledger

Use the MashNote `log_activity` tool to append concise records of completed
coding work. Log meaningful milestones, not every agent turn.

Log after a milestone such as:
- `decision`: an architectural or product choice with rationale
- `implementation`: a coherent change is complete
- `verification`: tests or review reached a useful conclusion
- `delivery`: a commit, pull request, or handoff is ready

Keep GitHub as the source of truth for code, diffs, commits, and pull requests.
MashNote should capture the background, tradeoffs, rationale, and outcome. Avoid
repeating long file lists or diff summaries already available in GitHub. If useful,
include `context.workUnitId`, `context.milestone`, and artifact references.

Choose one to three short tags for the current line of work and reuse them on later
entries in this thread. Change the tags only when the thread moves to different work.

Use a stable `idempotencyKey` per completed work unit. Send only summaries, never
raw transcripts or secrets. Never claim a write succeeded unless the tool confirms
it. If the tool is unavailable, say so briefly; only print a manual entry when I ask.

## Destination
Use the personal/default route and omit `workspaceId` when calling
`log_activity`. The server may apply a workspace connection I have already saved.
Do not call `list_workspaces` and do not ask me to choose a destination. Only pass an
explicit workspaceId when I request one in the current conversation.

특정 워크스페이스에 기록

기록 목적지에서 워크스페이스를 고르면, 프롬프트 끝의 ## Destination 부분이 그 워크스페이스의 정확한 이름과 ID로 바뀝니다. 워크스페이스 ID가 들어가므로 이 프롬프트는 카드에서 복사하세요. 형식은 다음과 같습니다.

## Destination
For this project, log MashNote activity to this exact workspace:
- Name: <워크스페이스 이름>
- workspaceId: <워크스페이스 ID>

Pass this `workspaceId` directly to `log_activity`. Do not call
`list_workspaces` merely to confirm it, and do not ask me to choose a destination.
Only resolve it again if `log_activity` reports that the id is inaccessible, or if
I explicitly override the destination in the current conversation.

전역(개인) 지침에 워크스페이스용 프롬프트를 넣으면 카드에 전역 지침에 넣으면 다른 대화도 이 워크스페이스로 기록될 수 있어요.라는 경고가 표시됩니다. 특정 프로젝트만 워크스페이스로 기록하려면 다음과 같은 프로젝트 지침에 넣으세요.

ChatGPT Project의 지시사항
Claude Project의 지시사항
Codex·Antigravity 프로젝트의 AGENTS.md
Claude Code 프로젝트의 CLAUDE.md
Cursor 프로젝트 Rules

도구가 없을 때 복사용 기록도 표시를 켜면 프롬프트 끝에 다음 문장이 추가됩니다. log_activity를 쓸 수 없을 때 AI가 기록 대신 내가 복사해 둘 수 있는 기록 내용을 보여 줍니다.

If `log_activity` is unavailable, print a concise manual ledger entry for me to copy.

기록 위치와 공개 범위

MCP로 들어온 활동은 기본적으로 나에게만 기록됩니다. 워크스페이스 없이 내 매시에만 쌓이며, 팀의 활동 피드에는 나타나지 않습니다.

워크스페이스로 보내는 방법은 세 가지입니다.

워크스페이스 연결 규칙: 내 매시의 공개 범위 & 워크스페이스 연결에서 소스(예: Claude Code, ChatGPT)별로 기본 연결 워크스페이스와 공개 범위를 정합니다. 규칙을 정한 뒤 그 소스에서 기록되는 활동은 정한 워크스페이스로 연결됩니다.
항목별 연결: 내 매시에서 이미 기록된 활동을 하나씩 또는 여러 개 골라 워크스페이스에 연결하거나 나에게만 기록으로 되돌립니다.
워크스페이스용 프롬프트: 특정 워크스페이스에 기록 프롬프트를 쓰면 AI가 처음부터 그 워크스페이스로 기록합니다.

공개 범위와 일괄 정리 방법은 활동과 내 매시를 참고하세요.

고급 설정 · 직접 연결

카드 아래쪽의 고급 설정 · 직접 연결을 펼치면 다음을 사용할 수 있습니다.

커넥터 주소: MashNote MCP 주소입니다. 설정 파일을 직접 편집할 때 사용합니다.
접근 토큰: OAuth 로그인을 지원하지 않는 앱이나 CI에서 쓰는 개인 접근 토큰입니다.
연결된 클라이언트: OAuth로 연결된 AI 앱 목록입니다.
발급된 토큰: 지금까지 발급한 접근 토큰 목록입니다.

접근 토큰

토큰 이름을 입력합니다. 비워 두면 mashnote-pat가 사용됩니다. 클라이언트마다 다른 이름을 쓰면 나중에 구분하기 쉽습니다.
토큰 발급을 누릅니다.
표시된 토큰을 복사해 안전한 곳에 보관합니다.
앱의 MCP 서버 설정에 MashNote MCP 주소를 넣고, 토큰을 Authorization: Bearer <토큰> 형식의 인증 헤더로 지정합니다.

발급된 토큰에는 각 토큰의 이름, 앞부분, 만료일, 마지막 사용일이 표시됩니다. 오래 사용하지 않은 토큰은 만료됩니다. 더 이상 쓰지 않는 토큰은 해제를 눌러 즉시 무효화하세요.

연결 해제

연결된 클라이언트에는 OAuth로 연결된 각 앱의 식별자(주소 형태)와 연결 날짜가 표시됩니다. 앱 옆의 해제를 누르면 연결이 끊어지고, 그 앱은 잠시 후부터 다시 로그인해야 MashNote에 기록할 수 있습니다.

연결은 AI 계정이 아니라 앱(클라이언트) 단위로 관리됩니다. 같은 앱에 여러 계정으로 로그인했다면 해제할 때 모두 함께 끊어집니다.
이미 기록된 활동은 연결을 해제해도 삭제되지 않습니다.

연결이나 도구 활성화에 문제가 있으면 연결 문제 해결을 확인하세요.

개발자이신가요?

MCP 설정 파일을 직접 편집하거나 기술적인 구성과 예제를 확인하려면 MashNote MCP GitHub 저장소를 참고하세요.

AI 도구 연결 및 자동 기록 (MCP)

시작하기 전에

모든 AI 도구의 공통 연결 흐름

연결 승인 페이지

제품별 연결 방법

ChatGPT

chatgpt.com

ChatGPT 데스크톱 앱 · Codex CLI

Claude (웹·데스크톱 앱)

Claude Code (CLI)

Cursor

설정 화면에서 추가

mcp.json과 CLI로 추가

Antigravity

설정 화면에서 추가

설정 파일과 CLI로 추가

기타 MCP 지원 도구

도구 활성화 확인

자동 기록 프롬프트

대화형 AI용 프롬프트

코딩 도구용 프롬프트

특정 워크스페이스에 기록

기록 위치와 공개 범위

고급 설정 · 직접 연결

접근 토큰

연결 해제

개발자이신가요?

`mcp.json`과 CLI로 추가