Claude Code — HTTP MCP (권장)
Claude Code 는 stdio 와 HTTP 두 MCP transport 를 모두 지원한다. ainote 는 HTTP transport 가 권장 경로 — npm 패키지 설치 불필요, 즉시 최신 도구 노출.
설정 (1단계)
~/.claude.json 의 mcpServers 에 추가:
{
"mcpServers": {
"ainote": {
"type": "http",
"url": "https://api.ainote.dev/api/mcp",
"headers": {
"Authorization": "McpKey <YOUR_MCP_KEY>"
}
}
}
}type: "http" 필수
원격 MCP 서버는 type: "http" 필드 명시 안 하면 Claude Code 의 user-level MCP 로더가 전체 mcpServers 블록을 스키마 검증 실패로 거부한다. 한 항목 누락 시 다른 모든 MCP 서버도 같이 안 뜸. 2026-04-15 ainote 자체 사고 사례.
MCP key 발급
세 방법 중 하나:
(a) Claude 안에서 즉시 (가장 쉬움)
임시로 key 없이 등록:
{
"mcpServers": {
"ainote": { "type": "http", "url": "https://api.ainote.dev/api/mcp" }
}
}Claude Code 재시작 후 입력:
"ainote 가입시켜줘 — 이메일 me@example.com / 비밀번호 abcd1234"
→ signup_and_get_key 가 호출돼서 key 가 응답에 표시된다. 그 key 를 위 config 의 Authorization header 에 추가하고 다시 재시작.
(b) CLI device flow
npx @ainote/mcp login브라우저로 RFC 8628 device authorization grant → key 가 OS Keychain 에 저장. ~/.claude.json 에 별도 헤더 안 넣어도 stdio mode 에서 자동 사용.
(c) 웹
app.ainote.dev → 가입 → Settings → MCP keys → Generate.
동작 확인
Claude Code 재시작 후:
"내 ainote 태스크 목록 보여줘"
list_tasks 가 호출돼서 응답이 표시되면 정상. 도구가 안 보이면:
~/.claude.json의 JSON 문법 (콤마 / 따옴표) 확인claude --debug모드로 MCP 로딩 로그 확인curl https://api.ainote.dev/health→ 200 OK 인지
사용 가능 도구
26개 도구가 모두 노출된다. 카테고리:
- Tasks (5): list_tasks, create_task, update_task, delete_task, list_categories
- Dev Docs (7): list_dev_docs, get_dev_doc, create_dev_doc, update_dev_doc, pull_dev_docs, delete_dev_doc, list_dev_categories
- Onboarding (3): signup_and_get_key, login_and_get_key, get_setup_guide
- Vaults (5): vault_list, vault_create, vault_clone, vault_connect_status, vault_sync
- Sync (3): sync_push, sync_pull, sync_list
- Handoffs (3): handoff_save, handoff_list, handoff_get
Tool annotations 활용
Claude Code 는 tools/list 응답의 annotations 를 읽어 자율 호출을 게이트한다. 예:
destructiveHint: true도구 (delete_task,vault_sync,handoff_list등) → user confirmation 우선idempotentHint: true도구 → 타임아웃/네트워크 오류 시 자동 재시도 안전openWorldHint: true도구 (vault_create,signup_and_get_key) → 외부 시스템 호출, 결과 비결정적 가능
자주 묻는 문제
"ainote MCP 가 도구 목록에 안 보임" — type: "http" 필드 누락. ~/.claude.json 전체에서 다른 mcpServers 도 같이 안 뜨면 99% 이 원인.
"401 Unauthorized" — Authorization header 의 McpKey 접두사 (공백 포함) 확인. Bearer ... 아님.
"도구는 보이는데 호출 시 timeout" — https://api.ainote.dev/health 가 응답하는지 확인. Render free tier 가 15분 idle 후 cold start (5-10초).