설정 파일에 서버를 한 번 등록하면 대화 중에 search_kds 와 get_kds_figure 가 붙습니다. 이 방법은 서버를 사용자 컴퓨터에서 직접 띄웁니다 — 질의도 조문도 네트워크로 나가지 않습니다. 설치 없이 쓰시려면 원격으로 붙는 방법이 따로 있습니다.
Optra 저장소를 받고 가상환경을 만든 뒤 requirements.txt 를 설치합니다. 파이썬 3.11 이상이 필요합니다.
Claude Desktop 의 설정 → 개발자 → 설정 편집으로 열거나, 아래 경로를 직접 엽니다.
파일이 없으면 새로 만듭니다.
경로 두 곳을 실제 설치 위치로 바꿉니다. 둘 다 절대경로여야 합니다 — Claude Desktop 은 홈 디렉터리 기호(~)를 풀어주지 않습니다.
{
"mcpServers": {
"Optra-kds": {
"command": "/경로/optra/.venv/bin/python3",
"args": ["/경로/optra/server/server.py"]
}
}
}
이미 다른 서버가 등록돼 있으면 mcpServers 안에 항목만 추가합니다.
창만 닫으면 프로세스가 남아 설정을 다시 읽지 않습니다. macOS 는 Cmd+Q 로 종료합니다.
대화 입력창의 도구 목록에 Optra-kds 가 보이면 붙은 것입니다. "KDS 41 12 00 5.7.3(3) 보여줘" 처럼 조문번호로 물어보면 정확매칭으로 바로 찾아옵니다.
서버는 뜰 때 조문 캐시를 한 번만 읽습니다. build_phase2.py 로 캐시를 다시 만든 뒤에는 Claude Desktop 을 재시작해야 새 내용이 반영됩니다.
재빌드 중에는 캐시에 _rebuilding 표시가 놓이고 서버가 뜰 때 경고를 냅니다. 경고가 보이면 끝날 때까지 기다립니다.
저장소도 파이썬도 기준 캐시도 필요 없습니다. 주소와 토큰만으로 붙습니다. 대신 질의가 저희 서버를 지납니다 — 무엇이 남고 무엇이 남지 않는지는 기준 연결 개요에 적었습니다. 토큰은 마이페이지 에서 직접 내시면 됩니다. 무료입니다.
Claude Desktop 의 설정에는 헤더를 넣는 칸이 없습니다. 그래서 mcp-remote 를 사이에 둡니다 — 이 다리를 로컬에서 띄우면 그것이 헤더를 붙여 원격 서버로 넘겨 줍니다. Node.js 18 이상이 필요합니다. 설정 파일의 위치는 위 02 단계와 같습니다.
{
"mcpServers": {
"Optra-kds": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://mcp.optra.kr/mcp",
"--header",
"Authorization:Bearer <받으신 토큰>"
]
}
}
}
Bearer 뒤에 빈칸을 두지 않았습니다. 빈칸이 있는 꼴도 지금은 동작하지만, 헤더 값 안의 빈칸에서 인자가 갈리는 문제가 알려져 있습니다. 콜론 뒤 빈칸은 HTTP 문법상 선택이라 서버는 둘 다 받으니, 안 갈라지는 쪽으로 적어 둡니다.
설정에 적은 값이 npx 가 띄우는 프로세스의 명령줄에 그대로 실립니다. 환경변수로 옮겨도 마찬가지입니다 — npm 이 환경변수를 명령줄로 다시 내보냅니다.
혼자 쓰는 컴퓨터라면 문제되지 않습니다. 여러 사람이 쓰는 컴퓨터라면 위의 로컬 방식을 권합니다.
토큰을 막 받으신 직후라면 잠시 걸릴 수 있습니다. 서버가 뜰 때 토큰 목록을 한 번만 읽어서, 저희 쪽에서 반영해 드려야 합니다. 바로 안 되면 그것일 가능성이 큽니다 — 토큰이 틀린 것이 아닙니다.