도움말:S3 연구 메모리/MCP 클라이언트

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

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

먼저 운영체제별 연결

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

각 문서는 토큰 입력, 에이전트에게 연결 맡기기, 직접 연결과 확인 순서로 되어 있습니다. 이 문서는 웹 커넥터와 제품별 제약을 확인할 때 사용합니다.

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

지원 상태

플랫폼	중앙 연결 방식	공개 읽기	현재 메모 쓰기
ChatGPT 웹	조직 앱 게시 또는 개인 개발자 모드	가능	`open` 모드의 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를 사용할 수 있는지 확인한 뒤 Workspace settings → Apps → Create를 엽니다.
이름은 S3 Research Memory, MCP URL은 https://s3wiki.yonsei.ac.kr/mcp로 입력합니다.
Scan tools로 표시된 일곱 도구와 read/write annotation을 확인합니다.
Create를 누릅니다.
Workspace settings → Apps → Drafts에서 항목을 열고 Publish를 누릅니다. 표시되면 접근 범위와 action control도 정합니다.
공개 읽기 도구를 확인합니다. 서버가 open 모드라면 쓰기 세 개도 인증 없이 동작하고, token 모드라면 거부됩니다.

공개 읽기는 OAuth 없이 됩니다. full MCP 쓰기는 Business, Enterprise, Edu에서만 지원됩니다. 서버가 open 모드면 OAuth 없이도 세 변경 도구를 쓸 수 있습니다. token 모드에서 웹 쓰기를 열려면 OAuth를 추가해야 합니다. Pro는 read/fetch만 쓸 수 있습니다. Agent mode는 사용자 정의 앱을 사용하지 않고 Deep Research도 read/fetch만 사용합니다.

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

개인 개발자 모드에서 시험

Settings → Security and login에서 Developer mode를 켭니다.
Settings → Plugins를 열거나 [1]로 이동합니다.
+를 누르고 같은 이름과 중앙 URL을 입력합니다.
도구 목록을 확인한 뒤 새 대화에서 공개 검색을 시험합니다.

이 메뉴는 요금제와 워크스페이스 정책에 따라 보이지 않을 수 있습니다. 개인 개발자 모드 항목은 조직에 게시된 앱이 아니므로, 모두에게 배포하려면 위 관리자 절차를 따릅니다.

사용자 설정

새 ChatGPT 대화를 엽니다.
앱 또는 도구 메뉴에서 S3 Research Memory를 선택합니다.
공개 읽기 연결을 켜고 검색 요청으로 확인합니다.

ChatGPT 웹은 ~/.codex/config.toml을 읽지 않습니다. 자세한 현재 절차는 ChatGPT 사용자 정의 MCP 안내, ChatGPT app 연결과 인증 안내를 따릅니다.

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

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

연구실 기본 설정

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

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

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

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

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

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

ChatGPT desktop app의 Codex(macOS/Windows): Settings → MCP servers에서 항목을 확인하고 Restart합니다.
Codex CLI: codex mcp list, 대화형 화면에서는 /mcp를 사용합니다.
VS Code Codex 확장: 톱니바퀴의 MCP servers에서 확인한 뒤 Restart extension을 누릅니다.

GUI 앱은 셸에서 임시로 export한 환경변수를 받지 못할 수 있습니다. 이때는 운영체제 사용자 환경에 토큰을 넣고 앱과 확장을 완전히 종료했다가 다시 실행합니다.

OAuth를 추가한 경우

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

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

공식 설정 항목과 세 클라이언트의 공유 방식은 Codex MCP 문서를 기준으로 했습니다.

Claude 웹과 Claude Desktop

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

Claude 웹에서 Organization settings → Connectors → Add → Custom → Web을 엽니다.
이름을 S3 Research Memory, URL을 https://s3wiki.yonsei.ac.kr/mcp로 입력합니다.
open 모드는 인증을 추가하지 않습니다. github 모드는 OAuth를 선택해 GitHub로 로그인합니다. token 모드는 웹 커넥터 쓰기에 사용하지 않습니다.
사용할 수 있는 계정 범위를 정합니다.

웹과 Desktop의 사용자 정의 커넥터에는 임의의 공용 Bearer header를 넣을 수 있다고 가정하지 않습니다. open 또는 github 모드를 사용하세요.

사용자 설정

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

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

개인 Free/Pro/Max 계정은 Customize → Connectors → + → Add custom connector에서 같은 URL을 등록할 수 있습니다. Free 계정은 사용자 정의 커넥터 한 개까지 쓸 수 있습니다. Team/Enterprise에서는 소유자가 등록한 connector를 사용합니다. Anthropic remote connector 문서에서 현재 절차를 확인할 수 있습니다.

Claude CLI / Claude Code와 VS Code Claude 확장

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

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

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

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

Claude Code MCP 문서와 VS Code 통합 문서가 claude.ai connector 동기화, /mcp, OAuth와 remote HTTP의 기준입니다.

Cursor

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

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

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

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

Cursor Teams/Enterprise 관리자는 Dashboard의 Integrations & MCP에서 같은 설정을 Team Marketplace에 올리고 Default On 또는 Required로 배포할 수 있습니다. 공식 스키마와 팀 배포 방식은 Cursor MCP와 Cursor plugin 배포를 따릅니다.

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

도구와 권한

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

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

요청 형식

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

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

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

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

search_lessons(query="", filters=null, fields=null, limit=5, cursor=null): 검색어는 최대 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): direction은 outgoing`, incoming, both 중 하나입니다. 저장된 analogous_to는 양방향으로 보입니다.
`find_analogies(lesson_id, filters=null, fields=null, min_score=0.08, limit=5, cursor=null)`: 명시된 유사 관계는 score 1입니다. 나머지는 제한된 단어 겹침과 최대 8개 공통어를 후보로 돌려줍니다. 후보는 저장된 관계가 아닙니다.

filters에는 review_states, confidences, authors, created_from, created_to, updated_from, updated_to, has_evidence, record_origins를 쓸 수 있습니다. 출처는 lab, imported, synthetic 중 하나입니다. timestamp 필터에는 시간대가 필요하고 서버는 UTC로 정규화합니다. limit의 최댓값은 20입니다.

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

쓰기 입력은 더 좁습니다.

create_lesson_draft(draft)는 title, question, attempt, context, observation, interpretation, reusable_lesson, applicability, confidence, evidence, 선택적 lesson_id만 받습니다.
link_lessons(from_lesson, relation, to_lesson, note="")는 존재하는 서로 다른 두 ID가 필요하고, 같은 관계의 중복을 거부합니다.
attach_evidence(lesson_id, evidence)는 citation과 kind가 필수입니다. kind는 paper, code, dataset, log, benchmark, other 중 하나이고 url, note, evidence_id는 선택입니다. added_by와 added_at은 서버가 넣습니다.

목록 응답에는 items, returned, has_more, next_cursor, partial, scanned, scan_limit이 들어갑니다. partial=true는 후보 탐색 한도에 닿았다는 뜻입니다. page_limited_by_output은 byte 한도 때문에 해당 페이지가 짧아졌다는 뜻이고, 긴 문자열이 잘리면 output_truncated가 표시됩니다. cursor는 다른 요청 인자에 묶여 있으므로 그대로 이어 쓰거나 처음부터 새 검색을 시작합니다.

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

적은 token으로 찾는 순서

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

검색어와 상태·신뢰도 필터를 좁히고 limit=3~5로 시작합니다.
지금 판단에 필요한 필드만 요청합니다.
다음 묶음은 limit을 키우지 말고 next_cursor로 받습니다.
후보를 고른 뒤에만 get_lesson을 호출합니다.
답변에 메모를 썼다면 반환된 근거 인용도 함께 보존합니다.

도구 결과의 기본 직렬화 한도는 32 KiB(S3RM_MAX_OUTPUT_BYTES=32768), 절대 상한은 64 KiB입니다. JSON-RPC 포장과 검증 오류까지 포함한 HTTP 응답 본문도 212,992 bytes를 넘지 않습니다. 응답이 잘렸다면 한도를 우회하려 하지 말고 결과 수나 필드를 줄입니다.

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

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

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

비밀과 연결 경계

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