도움말:S3 연구 메모리/MCP 클라이언트 - 편집 역사

S3Admin: S3 연구 메모리 저장소 문서 동기화

2026-07-16T14:32:08Z

S3 연구 메모리 저장소 문서 동기화

← 이전 판		2026년 7월 16일 (목) 23:32 판
224번째 줄:		224번째 줄:
	* <code><nowiki>attach_evidence(lesson_id, evidence)</nowiki></code>는 <code><nowiki>citation</nowiki></code>과 <code><nowiki>kind</nowiki></code>가 필수입니다. <code><nowiki>kind</nowiki></code>는 <code><nowiki>paper</nowiki></code>, <code><nowiki>code</nowiki></code>, <code><nowiki>dataset</nowiki></code>, <code><nowiki>log</nowiki></code>, <code><nowiki>benchmark</nowiki></code>, <code><nowiki>other</nowiki></code> 중 하나이고 <code><nowiki>url</nowiki></code>, <code><nowiki>note</nowiki></code>, <code><nowiki>evidence_id</nowiki></code>는 선택입니다. <code><nowiki>added_by</nowiki></code>와 <code><nowiki>added_at</nowiki></code>은 서버가 넣습니다.		* <code><nowiki>attach_evidence(lesson_id, evidence)</nowiki></code>는 <code><nowiki>citation</nowiki></code>과 <code><nowiki>kind</nowiki></code>가 필수입니다. <code><nowiki>kind</nowiki></code>는 <code><nowiki>paper</nowiki></code>, <code><nowiki>code</nowiki></code>, <code><nowiki>dataset</nowiki></code>, <code><nowiki>log</nowiki></code>, <code><nowiki>benchmark</nowiki></code>, <code><nowiki>other</nowiki></code> 중 하나이고 <code><nowiki>url</nowiki></code>, <code><nowiki>note</nowiki></code>, <code><nowiki>evidence_id</nowiki></code>는 선택입니다. <code><nowiki>added_by</nowiki></code>와 <code><nowiki>added_at</nowiki></code>은 서버가 넣습니다.
	목록 응답에는 <code><nowiki>items</nowiki></code>, <code><nowiki>returned</nowiki></code>, <code><nowiki>has_more</nowiki></code>, <code><nowiki>next_cursor</nowiki></code>, <code><nowiki>partial</nowiki></code>, <code><nowiki>scanned</nowiki></code>, <code><nowiki>scan_limit</nowiki></code>이 들어갑니다. <code><nowiki>partial=true</nowiki></code>는 후보 탐색 한도에 닿았다는 뜻입니다. <code><nowiki>page_limited_by_output</nowiki></code>은 byte 한도 때문에 해당 페이지가 짧아졌다는 뜻이고, 긴 문자열이 잘리면 <code><nowiki>output_truncated</nowiki></code>가 표시됩니다. cursor는 다른 요청 인자에 묶여 있으므로 그대로 이어 쓰거나 처음부터 새 검색을 시작합니다.		목록 응답에는 <code><nowiki>items</nowiki></code>, <code><nowiki>returned</nowiki></code>, <code><nowiki>has_more</nowiki></code>, <code><nowiki>next_cursor</nowiki></code>, <code><nowiki>partial</nowiki></code>, <code><nowiki>scanned</nowiki></code>, <code><nowiki>scan_limit</nowiki></code>이 들어갑니다. <code><nowiki>partial=true</nowiki></code>는 후보 탐색 한도에 닿았다는 뜻입니다. <code><nowiki>page_limited_by_output</nowiki></code>은 byte 한도 때문에 해당 페이지가 짧아졌다는 뜻이고, 긴 문자열이 잘리면 <code><nowiki>output_truncated</nowiki></code>가 표시됩니다. cursor는 다른 요청 인자에 묶여 있으므로 그대로 이어 쓰거나 처음부터 새 검색을 시작합니다.

			각 도구는 닫힌 <code><nowiki>outputSchema</nowiki></code>를 공개합니다. 성공 결과는 <code><nowiki>structuredContent</nowiki></code>에 들어가며, 기존 클라이언트용 compact JSON text도 같은 내용으로 유지합니다.

	=== 적은 token으로 찾는 순서 ===		=== 적은 token으로 찾는 순서 ===
234번째 줄:		236번째 줄:
	# 후보를 고른 뒤에만 <code><nowiki>get_lesson</nowiki></code>을 호출합니다.		# 후보를 고른 뒤에만 <code><nowiki>get_lesson</nowiki></code>을 호출합니다.
	# 답변에 메모를 썼다면 반환된 근거 인용도 함께 보존합니다.		# 답변에 메모를 썼다면 반환된 근거 인용도 함께 보존합니다.
	도구 결과의 기본 직렬화 한도는 32 KiB(<code><nowiki>S3RM_MAX_OUTPUT_BYTES=32768</nowiki></code>), 절대 상한은 64 KiB입니다. JSON-RPC 포장과 검증 오류까지 포함한 HTTP 응답 본문도 ~~147~~,~~456~~ bytes를 넘지 않습니다. 응답이 잘렸다면 한도를 우회하려 하지 말고 결과 수나 필드를 줄입니다.		도구 결과의 기본 직렬화 한도는 32 KiB(<code><nowiki>S3RM_MAX_OUTPUT_BYTES=32768</nowiki></code>), 절대 상한은 64 KiB입니다. JSON-RPC 포장과 검증 오류까지 포함한 HTTP 응답 본문도 212,992 bytes를 넘지 않습니다. 응답이 잘렸다면 한도를 우회하려 하지 말고 결과 수나 필드를 줄입니다.

	<pre><nowiki>		<pre><nowiki>

S3Admin: S3 연구 메모리 저장소 문서 동기화

2026-07-16T13:12:14Z

S3 연구 메모리 저장소 문서 동기화

← 이전 판		2026년 7월 16일 (목) 22:12 판
52번째 줄:		52번째 줄:
	# 공개 읽기 도구를 확인합니다. 서버가 <code><nowiki>open</nowiki></code> 모드라면 쓰기 세 개도 인증 없이 동작하고, <code><nowiki>token</nowiki></code> 모드라면 거부됩니다.		# 공개 읽기 도구를 확인합니다. 서버가 <code><nowiki>open</nowiki></code> 모드라면 쓰기 세 개도 인증 없이 동작하고, <code><nowiki>token</nowiki></code> 모드라면 거부됩니다.
	공개 읽기는 OAuth 없이 됩니다. full MCP 쓰기는 Business, Enterprise, Edu에서만 지원됩니다. 서버가 <code><nowiki>open</nowiki></code> 모드면 OAuth 없이도 세 변경 도구를 쓸 수 있습니다. <code><nowiki>token</nowiki></code> 모드에서 웹 쓰기를 열려면 OAuth를 추가해야 합니다. Pro는 read/fetch만 쓸 수 있습니다. Agent mode는 사용자 정의 앱을 사용하지 않고 Deep Research도 read/fetch만 사용합니다.		공개 읽기는 OAuth 없이 됩니다. full MCP 쓰기는 Business, Enterprise, Edu에서만 지원됩니다. 서버가 <code><nowiki>open</nowiki></code> 모드면 OAuth 없이도 세 변경 도구를 쓸 수 있습니다. <code><nowiki>token</nowiki></code> 모드에서 웹 쓰기를 열려면 OAuth를 추가해야 합니다. Pro는 read/fetch만 쓸 수 있습니다. Agent mode는 사용자 정의 앱을 사용하지 않고 Deep Research도 read/fetch만 사용합니다.

			서버가 <code><nowiki>github</nowiki></code> 모드라면 앱 인증 방식으로 OAuth를 선택합니다. ChatGPT는 MCP의 discovery 문서를 읽고 GitHub 로그인으로 이동합니다. GitHub OAuth App callback은 <code><nowiki>https://s3wiki.yonsei.ac.kr/oauth/github/callback</nowiki></code>이어야 합니다. 이 모드에서는 검색을 포함한 MCP 연결 전체가 로그인 대상입니다.

	==== 개인 개발자 모드에서 시험 ====		==== 개인 개발자 모드에서 시험 ====
119번째 줄:		121번째 줄:
	# Claude 웹에서 <code><nowiki>Organization settings → Connectors → Add → Custom → Web</nowiki></code>을 엽니다.		# Claude 웹에서 <code><nowiki>Organization settings → Connectors → Add → Custom → Web</nowiki></code>을 엽니다.
	# 이름을 <code><nowiki>S3 Research Memory</nowiki></code>, URL을 <code><nowiki>https://s3wiki.yonsei.ac.kr/mcp</nowiki></code>로 입력합니다.		# 이름을 <code><nowiki>S3 Research Memory</nowiki></code>, URL을 <code><nowiki>https://s3wiki.yonsei.ac.kr/mcp</nowiki></code>로 입력합니다.
	# ~~공개 읽기만 쓸 때는~~ 인증을 추가하지 않습니다. ~~웹에서도 메모 쓰기가 필요할 때만~~ OAuth를 ~~연결합니다~~.		# <code><nowiki>open</nowiki></code> 모드는 인증을 추가하지 않습니다. <code><nowiki>github</nowiki></code> 모드는 OAuth를 선택해 GitHub로 로그인합니다. <code><nowiki>token</nowiki></code> 모드는 웹 커넥터 쓰기에 사용하지 않습니다.
	# 사용할 수 있는 계정 범위를 정합니다.		# 사용할 수 있는 계정 범위를 정합니다.
	웹과 Desktop의 사용자 정의 커넥터에는 임의의 공용 Bearer header를 넣을 수 있다고 가정하지 않습니다. ~~현재는 공개 읽기로 연결하고 쓰기는 OAuth를 추가한 뒤 엽니다~~.		웹과 Desktop의 사용자 정의 커넥터에는 임의의 공용 Bearer header를 넣을 수 있다고 가정하지 않습니다. <code><nowiki>open</nowiki></code> 또는 <code><nowiki>github</nowiki></code> 모드를 사용하세요.

	==== 사용자 설정 ====		==== 사용자 설정 ====

S3Admin: S3 연구 메모리 저장소 문서 게시

2026-07-16T13:03:04Z

S3 연구 메모리 저장소 문서 게시

새 문서

''이 페이지는 저장소 문서에서 자동으로 동기화됩니다. 위키에서 직접 편집하지 마세요.''

연구실에서 운영하는 MCP 서버는 하나입니다. 모든 플랫폼은 서버 담당자가 알려 준 동일한 중앙 <code><nowiki>/mcp</nowiki></code> 주소를 사용하며, 그 뒤에는 하나의 Semantic MediaWiki가 있습니다. 클라이언트 설정은 중앙 주소를 기억시키는 용도일 뿐 서버나 데이터 저장소를 새로 만들지 않습니다.

=== 먼저 운영체제별 연결 ===

공용 쓰기 토큰을 받은 뒤 운영체제에 맞는 문서에서 토큰 저장과 기본 연결을 마치세요.

* [[Help:S3 연구 메모리/Linux 연결|Linux에서 연결]]
* [[Help:S3 연구 메모리/macOS 연결|macOS에서 연결]]
* [[Help:S3 연구 메모리/Windows 연결|Windows에서 연결]]
각 문서는 토큰 입력, 에이전트에게 연결 맡기기, 직접 연결과 확인 순서로 되어 있습니다. 이 문서는 웹 커넥터와 제품별 제약을 확인할 때 사용합니다.

각 PC에는 이 저장소, Docker, 위키 비밀번호가 필요하지 않습니다. 사용자용 연결 주소로 <code><nowiki>localhost</nowiki></code>, <code><nowiki>127.0.0.1</nowiki></code>, SSH port forwarding, generic MediaWiki <code><nowiki>api.php</nowiki></code>를 사용하지 않습니다.

=== 지원 상태 ===

{| class="wikitable"
! 플랫폼 !! 중앙 연결 방식 !! 공개 읽기 !! 현재 메모 쓰기
|-
| ChatGPT 웹 || 조직 앱 게시 또는 개인 개발자 모드 || 가능 || <code><nowiki>open</nowiki></code> 모드의 Business/Enterprise/Edu에서 가능
|-
| ChatGPT desktop app의 Codex (macOS/Windows) || Codex 공용 MCP 설정 || 가능 || Bearer 환경변수
|-
| Codex CLI || Codex 공용 MCP 설정 || 가능 || Bearer 환경변수
|-
| VS Code Codex 확장 || 같은 Codex 설정 || 가능 || Bearer 환경변수
|-
| Claude 웹 || 중앙 HTTPS 커넥터 || 가능 || OAuth 추가 뒤 가능
|-
| Claude Desktop || 같은 Claude 계정 커넥터 || 가능 || OAuth 추가 뒤 가능
|-
| Claude CLI / Claude Code || 중앙 HTTPS URL 직접 등록 || 가능 || 공용 Bearer 헤더
|-
| VS Code Claude 확장 || 같은 Claude Code 설정 || 가능 || 공용 Bearer 헤더
|-
| Cursor || 사용자 전역 원격 MCP 설정 || 가능 || Bearer 환경변수 헤더
|}

=== ChatGPT 웹 ===

조직에서 함께 쓸 때는 워크스페이스 관리자가 중앙 MCP를 앱으로 등록하고 게시합니다. 개인 개발자 모드에서는 같은 URL을 먼저 시험할 수 있습니다. ChatGPT는 각 PC의 Codex 설정을 읽지 않습니다.

==== 워크스페이스 관리자가 한 번만 설정 ====

# 사용자 계정에서 developer mode를 사용할 수 있는지 확인한 뒤 <code><nowiki>Workspace settings → Apps → Create</nowiki></code>를 엽니다.
# 이름은 <code><nowiki>S3 Research Memory</nowiki></code>, MCP URL은 <code><nowiki>https://s3wiki.yonsei.ac.kr/mcp</nowiki></code>로 입력합니다.
# <code><nowiki>Scan tools</nowiki></code>로 표시된 일곱 도구와 read/write annotation을 확인합니다.
# <code><nowiki>Create</nowiki></code>를 누릅니다.
# <code><nowiki>Workspace settings → Apps → Drafts</nowiki></code>에서 항목을 열고 <code><nowiki>Publish</nowiki></code>를 누릅니다. 표시되면 접근 범위와 action control도 정합니다.
# 공개 읽기 도구를 확인합니다. 서버가 <code><nowiki>open</nowiki></code> 모드라면 쓰기 세 개도 인증 없이 동작하고, <code><nowiki>token</nowiki></code> 모드라면 거부됩니다.
공개 읽기는 OAuth 없이 됩니다. full MCP 쓰기는 Business, Enterprise, Edu에서만 지원됩니다. 서버가 <code><nowiki>open</nowiki></code> 모드면 OAuth 없이도 세 변경 도구를 쓸 수 있습니다. <code><nowiki>token</nowiki></code> 모드에서 웹 쓰기를 열려면 OAuth를 추가해야 합니다. Pro는 read/fetch만 쓸 수 있습니다. Agent mode는 사용자 정의 앱을 사용하지 않고 Deep Research도 read/fetch만 사용합니다.

==== 개인 개발자 모드에서 시험 ====

# <code><nowiki>Settings → Security and login</nowiki></code>에서 <code><nowiki>Developer mode</nowiki></code>를 켭니다.
# <code><nowiki>Settings → Plugins</nowiki></code>를 열거나 [https://chatgpt.com/plugins]로 이동합니다.
# <code><nowiki>+</nowiki></code>를 누르고 같은 이름과 중앙 URL을 입력합니다.
# 도구 목록을 확인한 뒤 새 대화에서 공개 검색을 시험합니다.
이 메뉴는 요금제와 워크스페이스 정책에 따라 보이지 않을 수 있습니다. 개인 개발자 모드 항목은 조직에 게시된 앱이 아니므로, 모두에게 배포하려면 위 관리자 절차를 따릅니다.

==== 사용자 설정 ====

# 새 ChatGPT 대화를 엽니다.
# 앱 또는 도구 메뉴에서 <code><nowiki>S3 Research Memory</nowiki></code>를 선택합니다.
# 공개 읽기 연결을 켜고 검색 요청으로 확인합니다.
ChatGPT 웹은 <code><nowiki>~/.codex/config.toml</nowiki></code>을 읽지 않습니다. 자세한 현재 절차는 [https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta ChatGPT 사용자 정의 MCP 안내], [https://developers.openai.com/apps-sdk/deploy/connect-chatgpt ChatGPT app 연결]과 [https://developers.openai.com/apps-sdk/build/auth 인증 안내]를 따릅니다.

=== ChatGPT desktop app의 Codex, Codex CLI, VS Code Codex 확장 ===

세 클라이언트는 같은 머신에서 <code><nowiki>~/.codex/config.toml</nowiki></code>을 공유합니다. 한 번 등록하면 그 PC에서는 앱, CLI, 확장에 따로 같은 서버를 만들지 않습니다.

==== 연구실 기본 설정 ====

<code><nowiki>S3RM_MCP_TOKEN</nowiki></code>을 현재 프로세스가 읽을 수 있는 환경에 넣고 다음 명령을 한 번 실행합니다.

<pre><nowiki>
codex mcp add s3-research-memory \
--url https://s3wiki.yonsei.ac.kr/mcp \
--bearer-token-env-var S3RM_MCP_TOKEN
codex mcp list
</nowiki></pre>

CLI 명령 직후에는 URL과 환경변수 이름이 저장됩니다. 실제 토큰 값은 들어가지 않습니다. 그 서버 블록에 승인 모드 한 줄을 직접 병합합니다.

<pre><nowiki>
[mcp_servers.s3-research-memory]
url = "https://s3wiki.yonsei.ac.kr/mcp"
bearer_token_env_var = "S3RM_MCP_TOKEN"
default_tools_approval_mode = "auto"
</nowiki></pre>

<code><nowiki>codex mcp add</nowiki></code>는 <code><nowiki>default_tools_approval_mode</nowiki></code> 줄을 자동으로 만들지 않습니다. ChatGPT desktop app의 Codex에서 <code><nowiki>Settings → Configuration → Open config.toml</nowiki></code>을 누르거나 편집기를 열어 위 한 줄만 같은 서버 블록에 추가합니다. 다른 MCP 블록을 덮어쓰지 않습니다.

<code><nowiki>auto</nowiki></code>는 매번 별도 승인 창을 띄우지 않는 설정입니다. 서버가 쓰기를 메모 작성, 관계 연결, 근거 첨부로 제한하고 상태 변경 권한은 주지 않습니다.

* ChatGPT desktop app의 Codex(macOS/Windows): <code><nowiki>Settings → MCP servers</nowiki></code>에서 항목을 확인하고 <code><nowiki>Restart</nowiki></code>합니다.
* Codex CLI: <code><nowiki>codex mcp list</nowiki></code>, 대화형 화면에서는 <code><nowiki>/mcp</nowiki></code>를 사용합니다.
* VS Code Codex 확장: 톱니바퀴의 <code><nowiki>MCP servers</nowiki></code>에서 확인한 뒤 <code><nowiki>Restart extension</nowiki></code>을 누릅니다.
GUI 앱은 셸에서 임시로 export한 환경변수를 받지 못할 수 있습니다. 이때는 운영체제 사용자 환경에 토큰을 넣고 앱과 확장을 완전히 종료했다가 다시 실행합니다.

==== OAuth를 추가한 경우 ====

사용자별 계정이 필요해 OAuth를 추가했다면 앱이나 확장의 <code><nowiki>Authenticate</nowiki></code>로 로그인할 수 있습니다. 공용 토큰을 쓰는 현재 기본 설정에는 필요하지 않습니다.

<pre><nowiki>
codex mcp add s3-research-memory --url https://s3wiki.yonsei.ac.kr/mcp
codex mcp login s3-research-memory
codex mcp list
</nowiki></pre>

공식 설정 항목과 세 클라이언트의 공유 방식은 [https://developers.openai.com/codex/mcp Codex MCP 문서]를 기준으로 했습니다.

=== Claude 웹과 Claude Desktop ===

==== Team/Enterprise 관리자가 한 번만 설정 ====

# Claude 웹에서 <code><nowiki>Organization settings → Connectors → Add → Custom → Web</nowiki></code>을 엽니다.
# 이름을 <code><nowiki>S3 Research Memory</nowiki></code>, URL을 <code><nowiki>https://s3wiki.yonsei.ac.kr/mcp</nowiki></code>로 입력합니다.
# 공개 읽기만 쓸 때는 인증을 추가하지 않습니다. 웹에서도 메모 쓰기가 필요할 때만 OAuth를 연결합니다.
# 사용할 수 있는 계정 범위를 정합니다.
웹과 Desktop의 사용자 정의 커넥터에는 임의의 공용 Bearer header를 넣을 수 있다고 가정하지 않습니다. 현재는 공개 읽기로 연결하고 쓰기는 OAuth를 추가한 뒤 엽니다.

==== 사용자 설정 ====

Claude 웹이나 Desktop에서 <code><nowiki>Customize → Connectors</nowiki></code>를 열고 <code><nowiki>S3 Research Memory</nowiki></code>를 연결합니다. 채팅에서는 <code><nowiki>+ → Connectors</nowiki></code>에서 활성화합니다.

Claude Desktop은 같은 Claude 계정의 원격 커넥터를 사용합니다. 별도 Desktop 설정 파일을 만들지 않고, 같은 계정으로 로그인한 뒤 채팅에서 connector를 켭니다. Hosted connector의 요청은 사용자 PC가 아니라 Anthropic cloud에서 중앙 MCP로 들어옵니다. 그래서 모든 플랫폼이 같은 공개 HTTPS 주소를 사용합니다.

개인 Free/Pro/Max 계정은 <code><nowiki>Customize → Connectors → + → Add custom connector</nowiki></code>에서 같은 URL을 등록할 수 있습니다. Free 계정은 사용자 정의 커넥터 한 개까지 쓸 수 있습니다. Team/Enterprise에서는 소유자가 등록한 connector를 사용합니다. [https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp Anthropic remote connector 문서]에서 현재 절차를 확인할 수 있습니다.

=== Claude CLI / Claude Code와 VS Code Claude 확장 ===

Claude Code에는 연구실 중앙 HTTPS 주소와 공용 토큰 헤더를 사용자 범위에 한 번 등록합니다.

<pre><nowiki>
claude mcp add --transport http --scope user \
s3-research-memory https://s3wiki.yonsei.ac.kr/mcp \
--header 'Authorization: Bearer ${S3RM_MCP_TOKEN}'
</nowiki></pre>

작은따옴표를 유지하면 셸이 토큰을 먼저 펼치지 않습니다. Claude 설정에는 <code><nowiki>${S3RM_MCP_TOKEN}</nowiki></code> 참조가 저장되고, 실행할 때 사용자 환경에서 값을 읽습니다. <code><nowiki>claude</nowiki></code>를 시작한 뒤 <code><nowiki>/mcp</nowiki></code>에서 연결을 확인합니다. 같은 PC의 VS Code Claude 확장도 이 설정을 사용합니다. VS Code 확장을 쓸 때는 확장 프로세스도 토큰 환경변수를 읽을 수 있게 한 뒤 완전히 다시 시작합니다.

Claude.ai에 HTTPS connector를 등록한 조직에서는 <code><nowiki>/mcp</nowiki></code>의 <code><nowiki>claude.ai</nowiki></code> 영역에 나타나는 같은 중앙 커넥터를 대신 켤 수 있습니다.

[https://code.claude.com/docs/en/mcp Claude Code MCP 문서]와 [https://code.claude.com/docs/en/ide-integrations VS Code 통합 문서]가 claude.ai connector 동기화, <code><nowiki>/mcp</nowiki></code>, OAuth와 remote HTTP의 기준입니다.

=== Cursor ===

Cursor의 사용자 전역 <code><nowiki>~/.cursor/mcp.json</nowiki></code>에 중앙 HTTPS 주소와 공용 토큰 헤더를 등록하면 모든 프로젝트와 Cursor CLI가 같은 지식을 읽고 메모도 남길 수 있습니다.

<pre><nowiki>
{
"mcpServers": {
"s3-research-memory": {
"url": "https://s3wiki.yonsei.ac.kr/mcp",
"headers": {
"Authorization": "Bearer ${env:S3RM_MCP_TOKEN}"
}
}
}
}
</nowiki></pre>

Cursor의 환경변수 문법은 <code><nowiki>${env:NAME}</nowiki></code>입니다. 토큰을 운영체제의 사용자 환경에 넣고 Cursor를 완전히 종료했다가 다시 실행합니다.

Cursor 설치 링크 (<code><nowiki>cursor://anysphere.cursor-deeplink/mcp/install?name=s3-research-memory&config=eyJ1cmwiOiJodHRwczovL3Mzd2lraS55b25zZWkuYWMua3IvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyICR7ZW52OlMzUk1fTUNQX1RPS0VOfSJ9fQ%3D%3D</nowiki></code>)는 위 server object를 Cursor 설정 화면에 추가합니다. 링크에는 중앙 URL과 토큰 환경변수 이름이 들어 있지만 실제 토큰 값은 없습니다. 수동 설정 뒤에는 Cursor 사이드바의 <code><nowiki>Customize → MCP</nowiki></code>에서 활성 상태를 확인합니다. Cursor CLI에서는 <code><nowiki>agent mcp list</nowiki></code>와 <code><nowiki>agent mcp list-tools s3-research-memory</nowiki></code>를 사용합니다. 명령 형식은 [https://cursor.com/docs/cli/reference/parameters Cursor CLI 공식 문서]를 따릅니다.

Cursor Teams/Enterprise 관리자는 Dashboard의 <code><nowiki>Integrations & MCP</nowiki></code>에서 같은 설정을 Team Marketplace에 올리고 <code><nowiki>Default On</nowiki></code> 또는 <code><nowiki>Required</nowiki></code>로 배포할 수 있습니다. 공식 스키마와 팀 배포 방식은 [https://cursor.com/docs/mcp Cursor MCP]와 [https://cursor.com/docs/plugins Cursor plugin 배포]를 따릅니다.

VS Code의 일반 <code><nowiki>.vscode/mcp.json</nowiki></code>과 Cursor의 <code><nowiki>.cursor/mcp.json</nowiki></code>은 스키마가 다릅니다. 또한 일반 VS Code MCP 설정이 Codex 또는 Claude 확장에 자동 적용된다는 공식 근거가 없으므로, 이 문서에서는 각 공급자의 설정만 사용합니다.

=== 도구와 권한 ===

{| class="wikitable"
! 도구 !! 용도 !! 쓰기 여부
|-
| <code><nowiki>search_lessons</nowiki></code> || 전체 텍스트 검색과 필터 || 읽기
|-
| <code><nowiki>get_lesson</nowiki></code> || 지정한 메모와 필드 조회 || 읽기
|-
| <code><nowiki>find_related_lessons</nowiki></code> || 들어오고 나가는 관계 탐색 || 읽기
|-
| <code><nowiki>find_analogies</nowiki></code> || 명시된 관계와 후보 유사 사례 탐색 || 읽기
|-
| <code><nowiki>create_lesson_draft</nowiki></code> || 검증된 <code><nowiki>Lesson:</nowiki></code> 페이지 생성 || 메모 작성
|-
| <code><nowiki>link_lessons</nowiki></code> || 허용된 관계 하나 추가 || 관계 추가
|-
| <code><nowiki>attach_evidence</nowiki></code> || 인용 가능한 근거 하나 추가 || 근거 추가
|}

일반 위키 조작, 승인, 상태 전이, 삭제, 이동, 관리자 도구는 제공하지 않습니다. 메모를 만들 때 <code><nowiki>review_state</nowiki></code>, <code><nowiki>reviewer</nowiki></code>, timestamp를 에이전트가 정할 수도 없습니다. <code><nowiki>supersedes</nowiki></code> 관계를 추가해도 기존 메모의 호환 상태값은 바뀌지 않습니다.

=== 요청 형식 ===

모든 요청은 알 수 없는 필드를 거부합니다. <code><nowiki>fields</nowiki></code>에 쓸 수 있는 값은 다음과 같습니다.

<pre><nowiki>
id, title, question, attempt, context, observation, interpretation,
reusable_lesson, applicability, confidence, evidence, record_origin,
author, reviewer, review_state, created_at, updated_at, citations, relations
</nowiki></pre>

<code><nowiki>id</nowiki></code>를 생략해도 결과에는 자동으로 들어갑니다. <code><nowiki>citations</nowiki></code>는 짧은 구조화 근거이고, <code><nowiki>evidence</nowiki></code>는 메모 본문의 근거 설명입니다.

읽기 도구의 주요 인자는 다음과 같습니다.

* <code><nowiki>search_lessons(query="", filters=null, fields=null, limit=5, cursor=null)</nowiki></code>: 검색어는 최대 500자이며 빈 검색어는 필터에 맞는 메모를 나열합니다.
* `get_lesson(lesson_id, fields=null, citation_limit=5, citation_cursor=null, relation_limit=5, relation_cursor=null)`: 기본값은 요약 필드입니다. 근거와 관계는 각각 최대 20개씩 독립적으로 페이지를 넘길 수 있습니다. 본문은 필요한 필드를 지정해 가져옵니다.
* `find_related_lessons(lesson_id, relations=null, direction="both", filters=null, fields=null, limit=5, cursor=null)<code><nowiki>: </nowiki></code>direction<code><nowiki>은 </nowiki></code>outgoing`, <code><nowiki>incoming</nowiki></code>, <code><nowiki>both</nowiki></code> 중 하나입니다. 저장된 <code><nowiki>analogous_to</nowiki></code>는 양방향으로 보입니다.
* `find_analogies(lesson_id, filters=null, fields=null, min_score=0.08, limit=5, cursor=null)`: 명시된 유사 관계는 score 1입니다. 나머지는 제한된 단어 겹침과 최대 8개 공통어를 후보로 돌려줍니다. 후보는 저장된 관계가 아닙니다.
<code><nowiki>filters</nowiki></code>에는 <code><nowiki>review_states</nowiki></code>, <code><nowiki>confidences</nowiki></code>, <code><nowiki>authors</nowiki></code>, <code><nowiki>created_from</nowiki></code>, <code><nowiki>created_to</nowiki></code>, <code><nowiki>updated_from</nowiki></code>, <code><nowiki>updated_to</nowiki></code>, <code><nowiki>has_evidence</nowiki></code>, <code><nowiki>record_origins</nowiki></code>를 쓸 수 있습니다. 출처는 <code><nowiki>lab</nowiki></code>, <code><nowiki>imported</nowiki></code>, <code><nowiki>synthetic</nowiki></code> 중 하나입니다. timestamp 필터에는 시간대가 필요하고 서버는 UTC로 정규화합니다. <code><nowiki>limit</nowiki></code>의 최댓값은 20입니다.

<code><nowiki>review_states</nowiki></code>는 이전 페이지에 저장된 <code><nowiki>review_state</nowiki></code> 호환값으로 결과를 좁히는 필터일 뿐입니다. <code><nowiki>review_state</nowiki></code>와 <code><nowiki>reviewer</nowiki></code>는 기존 페이지와 클라이언트를 계속 읽기 위해 남겨 둔 변경 불가 필드입니다. 값에 상관없이 저장된 메모는 바로 공개되고 검색되며, 승인·노출·수정 권한이나 시스템 동작에는 영향을 주지 않습니다.

쓰기 입력은 더 좁습니다.

* <code><nowiki>create_lesson_draft(draft)</nowiki></code>는 <code><nowiki>title</nowiki></code>, <code><nowiki>question</nowiki></code>, <code><nowiki>attempt</nowiki></code>, <code><nowiki>context</nowiki></code>, <code><nowiki>observation</nowiki></code>, <code><nowiki>interpretation</nowiki></code>, <code><nowiki>reusable_lesson</nowiki></code>, <code><nowiki>applicability</nowiki></code>, <code><nowiki>confidence</nowiki></code>, <code><nowiki>evidence</nowiki></code>, 선택적 <code><nowiki>lesson_id</nowiki></code>만 받습니다.
* <code><nowiki>link_lessons(from_lesson, relation, to_lesson, note="")</nowiki></code>는 존재하는 서로 다른 두 ID가 필요하고, 같은 관계의 중복을 거부합니다.
* <code><nowiki>attach_evidence(lesson_id, evidence)</nowiki></code>는 <code><nowiki>citation</nowiki></code>과 <code><nowiki>kind</nowiki></code>가 필수입니다. <code><nowiki>kind</nowiki></code>는 <code><nowiki>paper</nowiki></code>, <code><nowiki>code</nowiki></code>, <code><nowiki>dataset</nowiki></code>, <code><nowiki>log</nowiki></code>, <code><nowiki>benchmark</nowiki></code>, <code><nowiki>other</nowiki></code> 중 하나이고 <code><nowiki>url</nowiki></code>, <code><nowiki>note</nowiki></code>, <code><nowiki>evidence_id</nowiki></code>는 선택입니다. <code><nowiki>added_by</nowiki></code>와 <code><nowiki>added_at</nowiki></code>은 서버가 넣습니다.
목록 응답에는 <code><nowiki>items</nowiki></code>, <code><nowiki>returned</nowiki></code>, <code><nowiki>has_more</nowiki></code>, <code><nowiki>next_cursor</nowiki></code>, <code><nowiki>partial</nowiki></code>, <code><nowiki>scanned</nowiki></code>, <code><nowiki>scan_limit</nowiki></code>이 들어갑니다. <code><nowiki>partial=true</nowiki></code>는 후보 탐색 한도에 닿았다는 뜻입니다. <code><nowiki>page_limited_by_output</nowiki></code>은 byte 한도 때문에 해당 페이지가 짧아졌다는 뜻이고, 긴 문자열이 잘리면 <code><nowiki>output_truncated</nowiki></code>가 표시됩니다. cursor는 다른 요청 인자에 묶여 있으므로 그대로 이어 쓰거나 처음부터 새 검색을 시작합니다.

=== 적은 token으로 찾는 순서 ===

목록 도구는 기본적으로 ID, 제목, 한 줄 메모, 신뢰도와 짧은 근거만 돌려줍니다.

# 검색어와 상태·신뢰도 필터를 좁히고 <code><nowiki>limit=3~5</nowiki></code>로 시작합니다.
# 지금 판단에 필요한 필드만 요청합니다.
# 다음 묶음은 <code><nowiki>limit</nowiki></code>을 키우지 말고 <code><nowiki>next_cursor</nowiki></code>로 받습니다.
# 후보를 고른 뒤에만 <code><nowiki>get_lesson</nowiki></code>을 호출합니다.
# 답변에 메모를 썼다면 반환된 근거 인용도 함께 보존합니다.
도구 결과의 기본 직렬화 한도는 32 KiB(<code><nowiki>S3RM_MAX_OUTPUT_BYTES=32768</nowiki></code>), 절대 상한은 64 KiB입니다. JSON-RPC 포장과 검증 오류까지 포함한 HTTP 응답 본문도 147,456 bytes를 넘지 않습니다. 응답이 잘렸다면 한도를 우회하려 하지 말고 결과 수나 필드를 줄입니다.

<pre><nowiki>
S3 Research Memory에서 tail latency와 관련된 메모를 최대 5개만 찾아 줘.
id, title, reusable_lesson, applicability, confidence, citations만 반환해.
</nowiki></pre>

<pre><nowiki>
Lesson:gpu_allocator_fragmentation의 궁금했던 점, 당시 조건, 실제 결과, 가능한 원인,
다음에 기억할 것, 언제 맞는지, 관련 자료를 읽고 다른 시스템 분야의 유사 사례를 최대
3개 찾아 줘.
</nowiki></pre>

<pre><nowiki>
이 결과를 메모로 남겨 줘. 근거를 추측하지 말고 제공된 보고서 경로와
checksum만 인용해. 서버가 관리하는 필드는 건드리지 말고 생성된 Lesson ID만 알려 줘.
</nowiki></pre>

=== 비밀과 연결 경계 ===

* 서버의 실제 값은 Git에서 제외된 <code><nowiki>.env</nowiki></code>에 mode <code><nowiki>0600</nowiki></code>으로 둡니다.
* 중앙 URL은 공개해도 되며 읽기에 token이 필요하지 않습니다. 공용 쓰기 token은 연구실에서 공유하고 각 클라이언트의 사용자 설정이나 환경변수에 둡니다.
* 서버는 raw token이 아니라 <code><nowiki>S3RM_MCP_TOKEN_SHA256</nowiki></code> digest만 저장합니다.
* 위키 계정, DB 비밀번호, 관리자 계정, raw token은 Git에 커밋하지 않습니다.
* 컨테이너 내부 <code><nowiki>http://mediawiki/api.php</nowiki></code>는 MCP adapter만 사용합니다. 이를 클라이언트 주소로 바꾸거나 일반 MediaWiki API를 에이전트에 노출하지 않습니다.
* 모든 클라이언트는 <code><nowiki>https://s3wiki.yonsei.ac.kr/mcp</nowiki></code> 하나와 공용 쓰기 주체를 공유합니다. 기본 연결은 HTTPS이며 native client는 공용 Bearer token을 사용합니다.
* ChatGPT 웹과 Claude 웹·Desktop의 쓰기가 필요해질 때만 OAuth를 추가합니다.
* 에이전트는 메모 작성, 관계 연결, 근거 첨부까지만 할 수 있습니다. 상태 변경과 삭제 도구는 없습니다.