AI 도구 연결과 스킬 설치
Claude Code·Codex·Cursor 같은 AI 도구에 나두바이오 MCP 서버를 연결하고 에이전트 스킬을 설치합니다.
나두바이오 MCP 서버 주소는 https://nadoo.bio/mcp입니다. 스트리밍 HTTP(streamable HTTP) 방식으로 제공하고, 인증은 API 키를 Authorization: Bearer 헤더로 보냅니다. MCP 연결용 OAuth 인증은 아직 제공하지 않으므로 헤더를 넣을 수 있는 AI 도구에서 연결하세요. 웹 화면의 브라우저 로그인과 MCP의 API 키 인증은 별개입니다.
- API 키 준비
- 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 | 작업·결과 읽기 | get_candidate_selection, preview_candidate_selection, list_candidate_inputs, inspect_input, list_projects, list_artifacts, list_jobs, get_job, get_result, query_result_table, read_result_file, preview_structure_comparison, create_structure_comparison, list_structure_comparisons, get_structure_comparison, list_result_views, render_result_view, get_job_events, list_workflow_runs, get_workflow_run, 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_delegated_plan, submit_batch, cancel_job |
files:write | 파일 올리기 | create_upload, get_upload, complete_upload, cancel_upload, create_structure_comparison |
2. 연결 방법 선택
아래에서 사용하는 AI 도구의 연결 방법을 선택하세요. MCP 서버를 연결한 뒤 5절의 스킬을 설치하면 나두바이오의 작업 절차도 함께 사용할 수 있습니다.
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가 연결할 때 환경 변수 값으로 바꿉니다. 그래서 설정 파일에 키 값이 남지 않으며, Claude Code를 띄우는 환경에 NADOO_BIO_API_KEY가 있어야 합니다. 큰따옴표로 감싸면 셸이 키 값을 펼쳐 설정 파일에 그대로 저장되므로 쓰지 마세요.
Codex
codex mcp add nadoo-bio --url https://nadoo.bio/mcp --bearer-token-env-var NADOO_BIO_API_KEYCodex는 환경 변수 이름만 저장하고 실행할 때 값을 읽습니다. 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 키>"
}
}
}
}이 예시는 API 키를 설정 파일에 직접 저장하므로 저장소에 커밋하지 마세요. 환경 변수나 비밀 입력 기능을 쓰려면 해당 AI 도구가 지원하는 설정 문법을 따르세요.
VS Code
명령 팔레트에서 MCP: Add Server를 고르고 HTTP를 선택한 뒤 주소 https://nadoo.bio/mcp와 이름 nadoo-bio를 입력합니다. 만들어진 서버 설정에 Authorization 헤더를 추가합니다. 헤더와 비밀 입력 방식은 VS Code 문서를 확인하세요.
주소만 받는 커넥터
연결 화면에서 인증 헤더를 설정할 수 있어야 API 키가 필요한 MCP 도구를 사용할 수 있습니다. 서버 주소만 입력할 수 있는 커넥터라면 헤더 설정을 지원하는 다른 연결 방식을 사용하세요. 나두바이오는 MCP 연결용 OAuth 인증을 제공하지 않으며, 웹 로그인으로 API 키 인증을 대신할 수 없습니다.
4. 연결 확인
먼저 get_connection_context로 API 키의 계정·조직·스코프를 확인하세요. 공개 목록 조회 성공은 인증 성공이 아닙니다. legacyUnscoped가 true이면 구형 역할 권한 경로이며 최소 스코프 키와 다릅니다. 이 조회는 프로젝트 접근·유료 실행을 승인하지 않습니다. 웹 링크는 브라우저의 로그인 계정으로 다시 검사하며 키를 URL에 넣지 않습니다.
- Claude Code:
claude mcp list또는 대화 안에서/mcp. Codex:codex mcp list. - AI 도구에 **"나두바이오 도구 목록 보여줘"**라고 요청합니다.
list_tools는 키 없이도 동작하므로, 여기서 실패하면 인증보다 연결 설정을 먼저 확인하세요.
웹에서 승인한 유료 작업 전달
활성 배포에서 지원되는 USD LIVE 계획은 승인 화면의 에이전트 위임 준비에서 대상 키를 선택하고 검토·동의를 기록합니다. 위임 상세의 제출 요청 만들기 → 제출 요청 복사로 받은 JSON을 에이전트에 전달하고 제출을 요청하세요. 링크 열기나 복사만으로 작업이 실행되지 않습니다. 현재 승인 세션·기한·실행 지원 상태에 따라 버튼이 표시되며, 재로그인만으로 원 승인 권한이 복구되는 것은 아닙니다.
에이전트는 복사한 submit_delegated_plan의 arguments를 그대로 사용하고 원 requestKey와 본문을 보존합니다. 응답 유실은 같은 명령으로 복구합니다. 지정된 API 키와 jobs:submit이 필요하고, 접수 후 get_job 조회에는 별도로 jobs:read가 필요합니다. 조회 권한이 없으면 접수 실패로 판단하거나 재제출하지 말고 반환된 작업 링크를 여세요. API 키는 연결 설정에만 두고 명령이나 URL에 넣지 않습니다. 모든 모델·통화 경로의 위임을 지원한다는 뜻은 아닙니다.
5. 에이전트 스킬 설치
스킬은 AI 도구가 나두바이오 MCP 도구를 올바른 순서로 쓰도록 돕는 SKILL.md 지침 묶음입니다. 스킬만으로는 기능이 없으므로 MCP 연결을 먼저 마치세요.
| 스킬 | 언제 쓰나 | sha256 앞 12자 |
|---|---|---|
nadoobio-account-and-approval | 나두바이오에서 권한·승인·사용 한도 때문에 막혔을 때 사용한다. scope_required, not_found, plan_not_approved, monthly_limit_exceeded, context_changed 같은 오류의 뜻과 사용자에게 무엇을 요청할지 정리한다. 우회하거나 다른 자원을 추측해 접근하지 않게 한다. | a6dd78911a1e |
nadoobio-batch-screening | 나두바이오에서 후보 여러 건의 계획을 만들고 제출 가능 상태를 확인할 때 사용한다. 단건 도구를 반복 호출하지 않고 보관 CSV·FASTA로 create_batch_plans를 실행하며, 승인·제출 가능 여부는 결과의 approval.status와 reason에 따른다. | 8689bbba1619 |
nadoobio-complex-analysis | 복합체 또는 표적 단백질 분해 연구의 구조 결과에서 사슬 대응과 접촉·배치 지표를 검토한다. | 6f6312f2a21c |
nadoobio-docking-screening | 분자 도킹과 후보 스크리닝에서 입력 준비 조건과 점수 비교 가능성을 판단한다. | 000ad86c87dd |
nadoobio-dynamics | 분자동역학 시뮬레이션의 궤적·시간·주기 경계와 결과 해석을 확인한다. | 6a981f354bbc |
nadoobio-folding | 단백질 서열로 구조를 예측하거나 접힘 결과를 검토할 때 입력·구조 신뢰도의 의미를 확인한다. | b4c914327bd5 |
nadoobio-input-preparation | 나두바이오에서 단백질 연구 도구를 고르고 입력을 준비·검증할 때 사용한다. list_tools로 도구를 찾고 get_tool_schema로 입력 계약을 읽은 뒤 validate_input과 inspect_input으로 서열·보관 파일이 계약을 통과하는지 확인한다. 지원되는 설계 구간 준비 계약을 확인한다. 실행 계획을 만들기 전 단계다. | a6af4a9d52f7 |
nadoobio-metric-interpretation | 구조 신뢰도·비교 오차·후보 점수·실험값을 혼동하지 않고 연구 결과의 근거 수준을 설명한다. | 366163d78bd8 |
nadoobio-plan-and-submit | 나두바이오에서 작업을 실행할 때 사용한다. list_execution_options → create_plan → 사람 승인 → submit_plan → get_job 폴링 순서를 지키고, 승인 링크 전달·멱등 재시도·월 한도 초과 대응을 다룬다. 사람 승인 없이 실행하려 하거나 같은 요청을 새 키로 반복하지 않게 한다. | c84e012f5fdd |
nadoobio-protein-design | 항체·단백질 서열 또는 구조 설계의 입력 조건을 정하고 설계와 검증을 구분한다. | 186004f4de2f |
nadoobio-reproducibility | 나두바이오에서 이전 결과를 재현·인용하거나 같은 입력으로 다시 돌릴 때 사용한다. get_plan의 planHash·릴리스·정책, get_provenance의 계보, rerun_plan의 원 계획 연결을 읽는 법과, 입력 고정이 출력 동일성을 뜻하지 않는다는 경계를 다룬다. | 4445c2b467eb |
nadoobio-research-routing | 연구 의도에서 구조 예측·도킹·설계·복합체·궤적·지표 해석 중 필요한 과업과 현재 실행 가능한 도구를 찾는다. | fe09e436a89d |
nadoobio-result-interpretation | 나두바이오 작업 결과를 읽고 다음 단계를 고를 때 사용한다. get_result로 검증된 산출물 목록을 확인하고 read_result_file로 작은 텍스트 결과(지표 CSV 등)의 값을 읽으며, 계산 예측·구조 신뢰도·실제 결합·실험 검증을 섞지 않도록 지표의 의미와 한계를 설명한다. 두 구조 파일을 비교하거나 저장된 비교를 찾아 수치·이미지·같은 결과 링크로 다시 보여 줄 때도 사용한다. 결과 화면 링크를 사용자에게 준다. | e8318245b12f |
nadoobio-structure-comparison | 나두바이오의 단백질 구조 두 개를 비교할 때 사용한다. 검증된 실행 결과 또는 보관 파일에서 모델·사슬·구간을 확인하고, 겹친 구조·Cα RMSD·위치별 편차를 계산해 저장하고 다시 연다. | d911434bfe0f |
가장 간단한 방법은 오픈 소스 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가 이 값으로 파일을 확인합니다.
MCP 서버도 같은 스킬을 Skills 확장(io.modelcontextprotocol/skills)과 resources/list로 제공합니다. AI 도구가 MCP 스킬 리소스를 읽지 못하면 위의 파일 설치 방법을 사용하세요.
스킬은 MIT 라이선스로 제공하므로 자유롭게 복사·수정·재배포할 수 있습니다. 나두바이오 서비스 이용은 서비스 약관을 따릅니다.
6. 키 교체와 연결 제거
키가 만료되기 전에 새 키를 발급하고 NADOO_BIO_API_KEY를 바꿉니다. Codex와 3절 방식으로 등록한 Claude Code는 변수만 바꾸면 되고, JSON 설정 파일은 키 값이 저장돼 있으므로 파일을 고칩니다. 예전 안내처럼 큰따옴표로 등록한 Claude Code는 설정 파일에 키 값이 남아 있으므로 한 번 지우고 3절 명령으로 다시 등록하세요. 교체가 끝나면 API 키 화면에서 이전 키를 폐기하세요.
claude mcp remove nadoo-bio -s user
codex mcp remove nadoo-bio문제 해결
| 증상 | 확인할 것 |
|---|---|
invalid_credentials 또는 authentication_required | 키 오타, 만료, 폐기 여부. 구성원이 정지·제외되면 그 사람의 키도 막힙니다. |
scope_required | 오류의 required 값이 빠진 권한 범위입니다. 그 범위를 넣어 키를 새로 발급하세요. |
agent_execution_disabled | 서비스 설정에서 AI 에이전트 실행이 꺼져 조회만 됩니다. 관리자에게 문의하세요. |
| 다른 서버에 연결해야 함 | AI 도구 설정의 서버 주소를 연결할 서버의 /mcp 주소로 바꿉니다. |