본문으로 건너뛰기
시작하기
제품요금제문서블로그로그인English시작하기

Claude Code

Claude Code(Anthropic의 terminal coding agent)를 MCP로 AiNecto에 연결합니다.

AiNecto MCP 서버 추가​

claude mcp add 명령으로 AiNecto를 user scope 에 등록합니다.

claude mcp add --scope user --transport http ainecto https://ainecto.com/mcp

--scope user 를 꼭 붙이세요. 빼면 claude mcp add 는 local scope 로 등록하는데, local 은 ainecto init 이 쓰는 .mcp.json 보다 우선합니다 — 그러면 저장소의 역할이 영영 적용되지 않습니다. user scope 로 두면 ainecto init 을 실행한 저장소에서는 그 저장소의 project 항목(역할이 붙은 ainecto 서버)이 이기고, 나머지 폴더는 이 항목을 씁니다.

첫 tool call 시 Claude Code가 OAuth 요구사항을 감지하고 authorization 절차를 안내합니다.

  1. 브라우저 창이 AiNecto authorization page로 열립니다.
  2. 로그인하거나 기존 세션을 사용합니다.
  3. consent screen을 승인합니다.
  4. Claude Code가 token을 받아 local session에 저장합니다.

연결 확인:

claude mcp list

이 user scope 연결에는 역할이 없습니다. 역할 없는 세션이면 서버가 Claude Code 에게, 이 저장소의 세션이 가질 역할을 사용자에게 묻고 그 답으로 ainecto init 을 실행하라고 안내합니다. CLI → 저장소 설정 을 참고하세요.

npx -y ainecto@latest init                     # 사람이 터미널에서: 역할과 프로젝트를 물어봄
npx -y ainecto@latest init --role <역할>        # 에이전트가, 사용자가 고른 역할로

사용해 보기​

Claude Code 세션에서:

List my ERD documents in AiNecto.

Claude Code가 mcp__ainecto__list_documents를 type=erd로 호출하고 결과를 출력합니다.

Open ERD document <uuid> and show me the users table.

Claude Code는 mcp__ainecto__erd_list_tables와 mcp__ainecto__erd_get_table을 호출해 스키마를 보여줍니다.

설정 파일​

파일을 손으로 고치기보다 위의 claude mcp add --scope user 명령을 쓰세요 — user scope 설정을 대신 써 줍니다(scope 별 저장 위치는 Claude Code MCP docs 참고).

저장소의 .mcp.json 은 ainecto init 이 쓰며, 역할이 붙은 ainecto 항목 하나가 들어갑니다.

{
  "mcpServers": {
    "ainecto": {
      "command": "npx",
      "args": ["-y", "@ainecto/mcp", "--role", "development"]
    }
  }
}

그런 저장소에 local scope 의 ainecto 항목을 더하지 마세요. 이 항목을 가립니다.

Scope와 권한​

AiNecto가 발급한 token은 사용자 계정 범위로 동작합니다. Claude Code는 사용자가 볼 수 있거나 편집할 수 있는 document만 접근합니다.

  • OWNER / EDITOR — 읽기 + 쓰기 가능
  • VIEWER — 읽기 전용(write tool call은 permission error)

토큰은 AiNecto 계정 설정 → Connected apps에서 언제든 revoke할 수 있습니다.

문제 해결​

인증 중 브라우저가 열리지 않음
터미널에 표시된 authorization URL을 복사해 직접 여세요.

"plan does not include MCP"
MCP는 유료 요금제가 필요합니다. 계정 설정에서 업그레이드하거나 요금제를 참고하세요.

ainecto init 뒤에도 역할이 적용되지 않음
역할은 새 세션부터 적용됩니다. 종료한 뒤 저장소에서 claude -c 로 이어 가고, .mcp.json 의 ainecto 서버를 쓸지 물으면 승인하세요. 그래도 역할이 없으면 다른 ainecto 항목이 가리고 있는 것입니다. claude mcp get ainecto 로 확인해 local scope 라면 claude mcp remove ainecto -s local 로 지우고 다시 시작하세요.

Tool call이 401을 반환함
토큰이 만료되었습니다. 아무 tool call이나 다시 실행하면 Claude Code가 refresh를 시도합니다. 필요하면 서버를 제거 후 다시 추가하세요.

최종 수정: 에