AI 도구 연결과 스킬 설치

Claude Code·Codex·Cursor 같은 AI 도구에 나두바이오 MCP 서버를 연결하고 에이전트 스킬을 설치합니다.

나두바이오 MCP 서버 주소는 https://nadoo.bio/mcp입니다. 스트리밍 HTTP(streamable HTTP) 방식으로 제공하고, 인증은 API 키를 Authorization: Bearer 헤더로 보냅니다. OAuth 로그인은 아직 제공하지 않으므로 헤더를 넣을 수 있는 AI 도구에서 연결하세요.

1. API 키 준비

제품 화면 왼쪽 메뉴 API 키에서 이름, 권한 범위, 만료(30·90·365일, 기본 90일)를 골라 발급합니다. 키는 발급 직후 한 번만 보이므로 바로 복사하세요.
키를 환경 변수 NADOO_BIO_API_KEY에 둡니다. 아래처럼 입력하면 키가 화면과 셸 기록에 남지 않습니다. 새 터미널에서도 쓰려면 셸 설정 파일이나 비밀 관리 도구에 넣으세요. 이후 명령은 모두 이 변수를 읽으므로 키를 명령줄에 직접 붙여 넣지 않습니다.

read -rs NADOO_BIO_API_KEY && export NADOO_BIO_API_KEY   # 키를 붙여 넣고 Enter

키 없이도 list_tools, get_tool_schema, search_docs, read_doc는 부를 수 있습니다. 나머지 도구는 키와 아래 권한 범위가 필요합니다. AI 도구가 계획을 만들고 제출까지 하려면 계획 작성과 작업 제출 권한을 함께 주세요. AI가 만든 계획도 사람이 제품 화면에서 승인해야 제출됩니다.

권한 범위	화면 이름	이 권한이 필요한 MCP 도구
`catalog:read`	도구 목록 읽기	`validate_input`
`jobs:read`	작업·결과 읽기	`inspect_input`, `list_jobs`, `get_job`, `get_result`, `read_result_file`, `get_job_events`, `get_plan`, `list_plans`, `get_provenance`, `create_view_link`
`plans:write`	실행 계획 만들기	`list_execution_options`, `prepare_design_input`, `create_plan`, `label_plan`, `rerun_plan`, `create_batch_plans`, `preview_batch_plans`
`jobs:submit`	작업 제출	`submit_plan`, `submit_batch`, `cancel_job`
`files:write`	파일 올리기	MCP 도구 없음(파일 올리기 HTTP API에서 사용)

2. 빠른 설치

npx nadoo-bio@latest add

PATH에서 claude와 codex를 찾아 아래 3절의 등록 명령을 대신 실행합니다. 둘 다 없으면 JSON 설정 예시를 출력합니다. --client claude 또는 --client codex로 대상을 고르고, --print를 붙이면 실행하지 않고 명령만 보여 줍니다. 키 값은 화면에 출력하지 않습니다.

3. 도구별 수동 연결

Claude Code

claude mcp add --transport http nadoo-bio -s user https://nadoo.bio/mcp --header "Authorization: Bearer $NADOO_BIO_API_KEY"

-s user는 모든 프로젝트에서 쓰도록 사용자 범위에 등록합니다. 빼면 현재 프로젝트에만(local 범위) 등록됩니다. 셸이 $NADOO_BIO_API_KEY를 키 값으로 바꿔 넘기므로 Claude Code 설정 파일에는 키 값이 저장됩니다. 키를 바꾸면 6절처럼 다시 등록하세요.

Codex

codex mcp add nadoo-bio --url https://nadoo.bio/mcp --bearer-token-env-var NADOO_BIO_API_KEY

Codex는 환경 변수 이름만 저장하고 실행할 때 값을 읽습니다. Codex를 띄우는 셸이나 앱 환경에 NADOO_BIO_API_KEY가 있어야 합니다.

JSON 설정 파일을 쓰는 도구

도구	설정 파일	주소 키
Cursor	`.cursor/mcp.json`(프로젝트) 또는 `~/.cursor/mcp.json`	`url`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`serverUrl`
Gemini CLI	`~/.gemini/settings.json`	`httpUrl`
Cline	`cline_mcp_settings.json`(Cline의 MCP 설정 화면에서 엽니다)	`url`, `"disabled": false` 추가

Cursor 예시입니다. 다른 도구는 주소 키 이름만 표에 맞게 바꿉니다.

{
  "mcpServers": {
    "nadoo-bio": {
      "url": "https://nadoo.bio/mcp",
      "headers": {
        "Authorization": "Bearer <API 키>"
      }
    }
  }
}

이 파일에는 키 값이 평문으로 들어가므로 저장소에 커밋하지 마세요. 설정 파일 안에서 환경 변수를 치환하는 문법은 도구마다 다르고 이 문서에서 확인하지 않았습니다. 쓰려면 각 도구의 문서를 확인하세요.

VS Code

명령 팔레트에서 MCP: Add Server를 고르고 HTTP를 선택한 뒤 주소 https://nadoo.bio/mcp와 이름 nadoo-bio를 입력합니다. 만들어진 서버 설정에 Authorization 헤더를 추가합니다. 헤더와 비밀 입력 방식은 VS Code 문서를 확인하세요.

주소만 받는 커넥터

Claude Desktop 같은 앱의 원격 커넥터 화면이 헤더 입력을 받는지는 확인하지 않았습니다. 나두바이오는 OAuth를 지원하지 않으므로 헤더를 넣을 수 없으면 키가 필요한 도구를 쓸 수 없습니다.

4. 연결 확인

Claude Code: claude mcp list 또는 대화 안에서 /mcp. Codex: codex mcp list.
npx nadoo-bio@latest doctor: 서버 응답과 도구 수를 확인하고, NADOO_BIO_API_KEY가 있으면 키가 유효한지와 jobs:read 권한이 있는지 알려 줍니다.
AI 도구에 **"나두바이오 도구 목록 보여줘"**라고 요청합니다. list_tools는 키 없이도 동작하므로, 여기서 실패하면 인증보다 연결 설정을 먼저 확인하세요.

5. 에이전트 스킬 설치

스킬은 AI 도구가 나두바이오 MCP 도구를 올바른 순서로 쓰도록 돕는 SKILL.md 지침 묶음입니다. 스킬만으로는 기능이 없으므로 MCP 연결을 먼저 마치세요.

스킬	언제 쓰나	sha256 앞 12자
`nadoobio-account-and-approval`	나두바이오에서 권한·승인·사용 한도 때문에 막혔을 때 사용한다. scope_required, not_found, plan_not_approved, monthly_limit_exceeded, context_changed 같은 오류의 뜻과 사용자에게 무엇을 요청할지 정리한다. 우회하거나 다른 자원을 추측해 접근하지 않게 한다.	`256f3ebc797c`
`nadoobio-batch-screening`	나두바이오에서 후보 여러 건을 한 번에 계획·실행할 때 사용한다. 단건 도구를 반복 호출하지 않고 보관 CSV·FASTA로 create_batch_plans를 만든 뒤 묶음 승인과 submit_batch로 제출한다. 행별 거절과 월 한도 도중 중단을 해석한다.	`2310c16ba572`
`nadoobio-input-preparation`	나두바이오에서 단백질 연구 도구를 고르고 입력을 준비·검증할 때 사용한다. list_tools로 도구를 찾고 get_tool_schema로 입력 계약을 읽은 뒤 validate_input과 inspect_input으로 서열·보관 파일이 계약을 통과하는지 확인한다. ProteinMPNN 설계 구간은 prepare_design_input으로 준비한다. 실행 계획을 만들기 전 단계다.	`5534a90972c6`
`nadoobio-plan-and-submit`	나두바이오에서 작업을 실행할 때 사용한다. list_execution_options → create_plan → 사람 승인 → submit_plan → get_job 폴링 순서를 지키고, 승인 링크 전달·멱등 재시도·월 한도 초과 대응을 다룬다. 사람 승인 없이 실행하려 하거나 같은 요청을 새 키로 반복하지 않게 한다.	`9339548db2de`
`nadoobio-reproducibility`	나두바이오에서 이전 결과를 재현·인용하거나 같은 입력으로 다시 돌릴 때 사용한다. get_plan의 planHash·릴리스·정책, get_provenance의 계보, rerun_plan의 원 계획 연결을 읽는 법과, 입력 고정이 출력 동일성을 뜻하지 않는다는 경계를 다룬다.	`fcbfab94dfb1`
`nadoobio-result-interpretation`	나두바이오 작업 결과를 읽고 다음 단계를 고를 때 사용한다. get_result로 검증된 산출물 목록을 확인하고 read_result_file로 작은 텍스트 결과(지표 CSV 등)의 값을 읽으며, 계산 예측·구조 신뢰도·실제 결합·실험 검증을 섞지 않도록 지표의 의미와 한계를 설명한다. 결과 화면 링크를 사용자에게 준다.	`f9c5def9f3e9`

가장 간단한 방법은 오픈 소스 skills CLI로 나두바이오 문서 도메인에서 바로 받는 것입니다. Claude Code, Codex, Cursor, Copilot, Windsurf, Cline, Gemini CLI 등 여러 AI 도구의 스킬 폴더를 알아서 찾아 설치하고, 나중에 npx skills update로 갱신합니다.

npx skills add https://nadoo.bio          # 설치할 도구와 스킬을 고릅니다
npx skills add https://nadoo.bio --all -g   # 모든 스킬을 사용자 범위에 설치

도메인의 /.well-known/agent-skills/index.json에 스킬 목록과 sha256이 있고, skills CLI가 이 값으로 파일을 확인합니다.

Claude Code와 Codex는 플러그인으로 설치할 수도 있습니다. 플러그인은 스킬과 MCP 서버 설정을 함께 넣고, 새 버전이 나오면 갱신됩니다.

# Claude Code 대화창에서
/plugin marketplace add nadoomodoo/nadoo-bio-plugins
/plugin install nadoo-bio@nadoo-bio

# Codex
codex plugin marketplace add https://github.com/nadoomodoo/nadoo-bio-plugins.git
codex plugin add nadoo-bio@nadoo-bio

나두바이오 CLI로도 설치할 수 있습니다. 같은 명령을 다시 실행하면 최신 내용으로 덮어씁니다.

npx nadoo-bio@latest skills install --client claude   # ~/.claude/skills
npx nadoo-bio@latest skills install --client codex    # $CODEX_HOME/skills, 없으면 ~/.codex/skills
npx nadoo-bio@latest skills install --dir <폴더>       # 다른 도구

npx nadoo-bio@latest skills list는 패키지에 든 스킬과 sha256 전체 값을 보여 주고, --dir나 --client를 함께 주면 설치된 파일과 비교합니다. 지우려면 npx nadoo-bio@latest skills remove --client claude처럼 실행하며, 나두바이오 스킬 폴더만 지웁니다.

MCP 서버도 같은 스킬을 Skills 확장(io.modelcontextprotocol/skills)과 resources/list로 제공합니다. Codex(CLI 0.154.0)는 연결만으로 이 리소스에서 스킬을 읽어 쓰는 것을 확인했습니다. 다른 AI 도구는 확인하지 않았으므로 파일 설치를 함께 쓰세요.

스킬은 MIT 라이선스로 제공하므로 자유롭게 복사·수정·재배포할 수 있습니다. 나두바이오 서비스 이용은 서비스 약관을 따릅니다.

6. 키 교체와 연결 제거

키가 만료되기 전에 새 키를 발급하고 NADOO_BIO_API_KEY를 바꿉니다. Codex는 변수만 바꾸면 되고, Claude Code와 JSON 설정 파일은 키 값이 저장돼 있으므로 다시 등록하거나 파일을 고칩니다. 교체가 끝나면 API 키 화면에서 이전 키를 폐기하세요.

claude mcp remove nadoo-bio -s user
codex mcp remove nadoo-bio
# 또는 둘 다 한 번에
npx nadoo-bio@latest remove

문제 해결

증상	확인할 것
`invalid_credentials` 또는 `authentication_required`	키 오타, 만료, 폐기 여부. 구성원이 정지·제외되면 그 사람의 키도 막힙니다.
`scope_required`	오류의 `required` 값이 빠진 권한 범위입니다. 그 범위를 넣어 키를 새로 발급하세요.
`agent_execution_disabled`	서비스 설정에서 AI 에이전트 실행이 꺼져 조회만 됩니다. 관리자에게 문의하세요.
다른 서버에 연결해야 함	CLI는 `NADOO_BIO_URL`로 주소를 바꿉니다. AI 도구 설정의 주소도 같은 서버의 `/mcp`로 바꿉니다.

이 페이지의 내용