AI 에이전트에 HandStack 문서 연결하기

AI 코딩 에이전트에 문서 MCP(Model Context Protocol) 서버를 등록하면, 에이전트가 HandStack 규칙을 기억에 의존해 답하지 않고 이 사이트의 문서를 직접 검색해 근거로 삼습니다. 에이전트는 문서 전체를 컨텍스트에 싣지 않고 search_docs로 후보를 찾은 뒤 get_doc으로 필요한 섹션만 가져옵니다.

서버 주소는 https://handstack.kr/mcp입니다. 설치할 것이 없고, 읽기 전용이며, 로그인이 필요 없습니다.

시작 조건

Claude Code, Codex CLI, Cursor처럼 원격(Streamable HTTP) MCP 서버를 지원하는 AI 에이전트가 설치되어 있어야 합니다.
에이전트를 실행하는 PC에서 https://handstack.kr에 접속할 수 있어야 합니다.

절차

1. 서버 등록하기

사용하는 에이전트의 방법을 고르세요.

Claude Code

claude mcp add --transport http handstack-docs https://handstack.kr/mcp

팀 전체가 쓰려면 프로젝트 루트의 .mcp.json에 넣고 저장소에 커밋합니다.

{
  "mcpServers": {
    "handstack-docs": {
      "type": "http",
      "url": "https://handstack.kr/mcp"
    }
  }
}

Codex CLI

codex mcp add handstack-docs --url https://handstack.kr/mcp

설정 파일(~/.codex/config.toml)에 직접 쓰려면 다음과 같이 추가합니다. 신뢰하는 프로젝트에서는 프로젝트의 .codex/config.toml에 넣어 팀이 함께 쓸 수도 있습니다.

[mcp_servers.handstack-docs]
url = "https://handstack.kr/mcp"

Cursor 및 원격 MCP를 지원하는 클라이언트

MCP 설정 파일에 서버 주소를 추가합니다. 클라이언트가 원격 MCP 서버 주소 입력을 지원하면 같은 주소를 쓸 수 있습니다.

{
  "mcpServers": {
    "handstack-docs": {
      "url": "https://handstack.kr/mcp"
    }
  }
}

2. 새 세션에서 연결 확인하기

등록하기 전에 열어 둔 세션에는 반영되지 않습니다. 현재 세션을 끝내고 새 세션을 시작하세요. 데스크톱 앱이라면 앱을 재시작하면 확실합니다.

Claude Code

새 세션에서 /mcp를 입력하면 등록된 서버와 연결 상태가 보입니다. handstack-docs가 연결됨으로 보여야 합니다.
세션 밖에서는 터미널에서 claude mcp list로 확인합니다.
기본 등록 범위(local)는 등록한 프로젝트 폴더에서만 보입니다. 모든 프로젝트에서 쓰려면 --scope user로 등록하세요. 프로젝트의 .mcp.json으로 등록했다면 그 프로젝트를 열 때 서버를 사용할지 묻는 확인이 처음 한 번 나옵니다.

Codex CLI

새 세션에서 /mcp를 입력하거나, 터미널에서 codex mcp list를 실행합니다. 목록에 handstack-docs가 보여야 합니다.
codex mcp add로 등록하면 ~/.codex/config.toml에 저장되므로 같은 사용자 계정의 이후 모든 세션에서 유지됩니다. 프로젝트의 .codex/config.toml에 넣었다면 그 프로젝트에서만 보입니다.

서버 자체 확인

브라우저에서 https://handstack.kr/mcp를 엽니다. 서버 상태 페이지가 보이면 서버는 실행 중입니다. 이 페이지는 상태 확인용이며 도구 호출은 에이전트가 합니다.

3. 에이전트에 요청하기

문서를 근거로 작업하도록 사용을 명시적으로 지시하면 가장 확실합니다. 먼저 도구가 실제로 호출되는지 가볍게 확인해 보세요.

handstack-docs의 list_docs로 영역별 문서 수를 알려줘.

Claude Code에서

handstack-docs MCP를 사용해 HandStack 화면 개발 규칙을 확인한 뒤, BOD010과 같은 목록 조회 화면을 구현해 줘.

응답 중간에 search_docs, get_doc 같은 도구 호출이 보이면 문서를 근거로 작업하는 것입니다. Claude Code에서는 mcp__handstack-docs__search_docs처럼 mcp__서버이름__도구이름 형태로 표시됩니다.
처음 도구를 호출할 때 허용 여부를 묻습니다. 읽기 전용 서버이니 허용해도 됩니다. 매번 묻지 않게 하려면 .claude/settings.json에 {"permissions": {"allow": ["mcp__handstack-docs"]}}를 추가하세요.
/mcp에서 서버가 연결 실패로 보이면 실패하면의 표를 확인하세요.

Codex CLI에서

handstack-docs MCP를 사용해 HandStack 화면 개발 규칙을 확인한 뒤, BOD010과 같은 목록 조회 화면을 구현해 줘.

응답 중간에 handstack-docs의 search_docs, get_doc 호출 내역이 보이면 문서를 근거로 작업하는 것입니다.
도구 호출 승인을 묻는 화면이 나오면 읽기 전용 서버이니 허용해도 됩니다.
다른 세션에서 쓰던 handstack-docs가 안 보이면 codex mcp list로 등록이 남아 있는지, 새 세션인지 확인하세요.

이런 요청도 쓸 수 있습니다

"handstack-docs로 쿼리 ID 규칙을 찾아서 LD01 형식으로 새 SQL 계약을 만들어 줘."
"prompter 모듈에서 MCP 서버 사용 범위를 제한하는 설정을 문서에서 확인해 줘."
"handstack-docs의 get_sample로 prompter decision 예제를 찾아서 구조를 설명해 줘."

매번 사용을 지시하기 번거롭다면 프로젝트의 AGENTS.md(Codex)나 CLAUDE.md(Claude Code)에 "HandStack 규칙은 handstack-docs MCP로 확인한다"는 문구를 넣어 두세요. 템플릿은 프로젝트 규칙 파일과 함께 쓰기를 참고하세요.

검색은 한글 조사가 붙어도 찾도록 2글자 단위로 색인합니다. API 이름(syn.$w.transactionAction), 설정 키, 식별자는 그대로 검색하세요. 바이브 코딩 지침 같은 보조 자료는 순위가 낮게 반영됩니다.

연결 해제하기

에이전트에 등록한 정보만 지우면 됩니다. 서버와 프로젝트 파일에는 영향이 없고, 다시 연결하려면 위의 등록 절차를 반복하면 됩니다.

Claude Code

claude mcp remove handstack-docs

같은 이름을 여러 범위에 등록했다면 범위를 지정해 지웁니다.

claude mcp remove handstack-docs --scope local     # 또는 user, project

.mcp.json으로 팀과 공유하고 있다면 파일에서 handstack-docs 항목을 지우고 커밋해야 팀원에게도 반영됩니다.
.claude/settings.json에 mcp__handstack-docs 자동 허용 규칙을 넣었다면 함께 지웁니다.
claude mcp list에 더 이상 보이지 않으면 해제된 것입니다. 이미 열려 있는 세션은 다시 시작하세요.

Codex CLI

codex mcp remove handstack-docs

~/.codex/config.toml에 직접 적었다면 [mcp_servers.handstack-docs] 블록을 지워도 됩니다.
프로젝트의 .codex/config.toml에 넣은 항목은 위 명령으로 지워지지 않습니다. 해당 파일에서 직접 지우세요.
지우지 않고 잠시 쓰지 않으려면 설정 파일의 해당 블록에 enabled = false를 두는 방법도 있습니다.
codex mcp list에서 확인합니다.

Cursor 및 기타 클라이언트

MCP 설정 파일에서 handstack-docs 항목을 지우고 클라이언트를 다시 시작합니다.

규칙 파일도 함께 정리하세요. 프로젝트의 AGENTS.md나 CLAUDE.md에 "handstack-docs 도구로 문서를 조회하라"는 안내가 남아 있으면 에이전트가 없는 도구를 찾습니다. 해당 문구를 지우거나 MCP를 쓸 수 없을 때의 llms.txt 안내로 바꾸세요.

제공 도구

도구	용도	주요 인자
`search_docs`	키워드로 관련 섹션 검색	`query`, `section`, `module`, `limit`
`get_doc`	문서 본문 또는 한 섹션 읽기	`doc`(id·URL·제목), `section`, `max_chars`
`list_docs`	영역·모듈·경로별 문서 목록	`section`, `module`, `prefix`
`get_sample`	문서에 딸린 예제 파일 조회	`path`, `query`

section 값은 startup(시작하기), tutorial(따라 만들기), guides(작업별 가이드), reference(API·설정 참조), ide(IDE 사용하기), twelvefactor(배포·운영 원칙)입니다. module은 transact, dbclient, wwwroot, prompter처럼 서버 모듈 문서를 가리킵니다.

프로젝트 규칙 파일과 함께 쓰기

MCP 서버는 문서를 찾아 주고, 프로젝트별 규칙은 에이전트 지침 파일이 맡습니다. 둘을 함께 두면 에이전트가 먼저 문서를 확인하고 규칙을 지킵니다.

AGENTS.md 템플릿: 식별자, 파일 배치, 계약 작성, 보안 규칙
CLAUDE.md 템플릿: Claude Code의 문서 조회 방식, 작업 순서, 검증 규칙

MCP를 쓸 수 없을 때

MCP를 지원하지 않는 도구나 웹 기반 에이전트에는 정적 파일을 제공합니다.

파일	내용
`/llms.txt`	문서별 한 줄 설명과 링크 목차
`/llms-full.txt`	전체 문서 본문(약 3MB)
`/llms-startup.txt`, `/llms-tutorial.txt`, `/llms-guides.txt`, `/llms-reference.txt`, `/llms-ide.txt`, `/llms-twelvefactor.txt`	영역별 본문. 전체 파일이 너무 클 때 필요한 영역만 사용

동작 방식

문서 사이트를 빌드할 때 플러그인이 모든 문서를 순수 마크다운으로 바꾸고 섹션(H2·H3) 단위로 나눠 https://handstack.kr/agent/docs-index.json을 만듭니다.
서버는 이 인덱스를 읽어 검색하고, 10분마다 새 배포를 확인합니다. 새 문서가 배포되면 클라이언트 설정을 바꾸지 않아도 반영됩니다.
요청마다 응답 하나를 돌려주는 방식이라 세션이나 로그인 정보를 저장하지 않습니다.
남용을 막기 위해 IP당 분당 요청 수를 제한합니다. 제한을 넘으면 429 응답이 오고 Retry-After 초 뒤에 다시 시도하면 됩니다.

실패하면

증상	확인할 것
서버에 연결되지 않음	브라우저로 `https://handstack.kr/mcp`를 열어 상태 페이지가 보이는지. 사내 프록시가 `POST`를 막는지
`429` 응답	요청 제한을 넘었습니다. `Retry-After` 초 뒤에 다시 시도하세요
`403` 응답	브라우저 기반 클라이언트의 `Origin`이 허용 목록에 없습니다. 일반 MCP 클라이언트는 영향이 없습니다
최신 문서가 반영되지 않음	새 배포 후 10분 정도 기다리세요
검색 결과가 엉뚱함	질문 문장 대신 핵심 키워드(API 이름, 식별자)로 검색하고 `section`·`module`로 좁히기
해제했는데 도구가 계속 보임	다른 범위(local·user·project)나 프로젝트의 `.mcp.json`·`.codex/config.toml`에 같은 이름이 남아 있는지 확인하고, 열려 있던 세션을 다시 시작하세요

직접 운영하기

사내망에서 같은 서버를 운영하거나 문서를 수정하면서 확인하려는 경우의 방법입니다. 사이트 호스트에 서버를 붙이는 방법과 환경 변수는 저장소의 mcp/README.md에 정리되어 있습니다.

서버만 따로 실행하기

저장소의 mcp/ 폴더에서 실행합니다. 기본적으로 127.0.0.1:8787에만 바인딩합니다.

cd mcp
npm install
HANDSTACK_DOCS_INDEX=../build/agent/docs-index.json npm start
claude mcp add --transport http handstack-docs-local http://127.0.0.1:8787/mcp
codex mcp add handstack-docs-local --url http://127.0.0.1:8787/mcp   # Codex CLI

문서를 고치면서 확인하기

사이트 개발 서버(npm run start)가 MCP 서버를 함께 실행하고 http://localhost:3000/mcp로 제공합니다. 문서를 저장하면 검색 인덱스가 자동으로 갱신되고 1분 안에 MCP 응답에 반영됩니다. mcp/에서 npm install을 한 번 해 두어야 합니다.

npm install --prefix mcp
npm run start
claude mcp add --transport http handstack-docs-dev http://localhost:3000/mcp
codex mcp add handstack-docs-dev --url http://localhost:3000/mcp   # Codex CLI

브라우저로 http://localhost:3000/mcp를 열면 상태 페이지가 보입니다. 끄려면 AGENT_DOCS_MCP=false npm run start로 실행하세요.

시작 조건​

절차​

1. 서버 등록하기​

2. 새 세션에서 연결 확인하기​

3. 에이전트에 요청하기​

연결 해제하기​

제공 도구​

프로젝트 규칙 파일과 함께 쓰기​

MCP를 쓸 수 없을 때​

동작 방식​

실패하면​

직접 운영하기​

서버만 따로 실행하기​

문서를 고치면서 확인하기​

시작 조건

절차

1. 서버 등록하기

2. 새 세션에서 연결 확인하기

3. 에이전트에 요청하기

연결 해제하기

제공 도구

프로젝트 규칙 파일과 함께 쓰기

MCP를 쓸 수 없을 때

동작 방식

실패하면

직접 운영하기

서버만 따로 실행하기

문서를 고치면서 확인하기