클라이언트 연결

전제 조건

HTTP MCP URL을 수락하는 MCP 클라이언트 (Claude, Cursor, ChatGPT, Claude Code, 사용자 정의 클라이언트 등)
최초 OAuth 동의를 위한 브라우저 (API 키를 사용하지 않는 경우)
Runtime을 하나의 프로젝트에 고정하려는 경우 프로젝트 id

정확한 호스트네임은 배포 방식에 따라 다릅니다. 아래 프로덕션 유형 예시는 https://mcp.getodin.ai를 사용합니다. 온프레미스 또는 비공개 배포의場合は 환경의 MCP 호스트를 대신 사용하세요.

MCP 클라이언트에 EKB 추가

대부분의 클라이언트는 URL만 필요하며 OAuth를 직접 실행합니다.

{
  "mcpServers": {
    "ekb-builder": { "url": "https://mcp.getodin.ai/builder/mcp" },
    "ekb": { "url": "https://mcp.getodin.ai/runtime/mcp" }
  }
}

필요한 엔드포인트만 사용하세요. 많은 팀은 일상용 어시스턴트가 구성을 변경할 수 없도록 Runtime만으로 시작합니다.

엔드포인트	서버	목적
`…/builder/mcp`	EKB Builder	에이전트, 워크플로우, 테이블, 인터페이스, KB 생성 및 변경
`…/runtime/mcp`	EKB Runtime	에이전트 질문, 게시된 도구 실행, KB 검색, 테이블 쿼리

도구 표면은 Builder 및 Runtime을 참고하세요.

클라이언트 팁

클라이언트 유형	팁
Cursor / Claude Code 스타일 `mcpServers` JSON	위의 URL 블록을 클라이언트의 MCP 구성에 붙여넣으세요
별도의 "원격 MCP" UI가 있는 클라이언트	전체 `…/builder/mcp` 또는 `…/runtime/mcp` URL을 붙여넣으세요
사용자 정의 헤더를 지원하는 클라이언트	Runtime에는 `x-project-id`를, CI에는 API 키 헤더를 추가하세요

프롬프트 시 로그인

최초 사용 시 클라이언트는 인증 챌린지를 수신하고 브라우저 동의 흐름을 엽니다:

필요 시 EKB에 로그인
클라이언트 이름과 권한 확인 (Build in your workspace 또는 Use your agents and tools)
승인 또는 거부

동의 후 클라이언트는 본인으로서 EKB를 호출합니다. 해당 프로젝트에서 사용자 계정이 할 수 있는 일만 가능하며, 일반적인 EKB 권한이 계속 적용됩니다.

동의 링크는 만료되거나 일회용이 됩니다. 요청이 만료되었다는 메시지가 표시되면 MCP 클라이언트에서 연결을 다시 시작하세요.

세부 정보: 인증.

프로젝트 고정 (Runtime)

클라이언트가 사용자 정의 헤더를 지원하면 다음을 전달하세요:

x-project-id: <your-project-id>

모드	동작
`x-project-id` 포함	도구가 해당 프로젝트로 범위가 지정되며 이름이 더 짧게 유지됩니다 (예: `ask_support_bot`)
고정 없음	Runtime이 접근 가능한 프로젝트 간에 집계할 수 있으며, 에이전트/도구 이름에 프로젝트 이름이 포함될 수 있습니다

Builder는 헤더로 고정하지 않습니다. 모델이 생성/업데이트 호출마다 프로젝트 id를 전달합니다 (target_project_id 또는 project_id, 도구 스키마에 따름). 프로젝트 id를 찾아야 할 때는 Runtime의 list_odin_projects(또는 알려진 id)를 사용하세요.

헤드리스 접근 (CI 및 자동화)

대화형 OAuth는 브라우저가 필요합니다. CI, 평가, 스크립트의 경우 사용자 수준 API 키와 시크릿을 헤더로 전달하세요:

{
  "mcpServers": {
    "ekb": {
      "url": "https://mcp.getodin.ai/runtime/mcp",
      "headers": {
        "X-API-KEY": "...",
        "X-API-SECRET": "...",
        "x-project-id": "optional-project-id"
      }
    }
  }
}

프로젝트 목록 확인과 다중 프로젝트 Runtime이 계속 작동하도록 프로젝트 범위 키보다 사용자 수준 키를 권장합니다. 인증을 참고하세요.

문제 해결

증상	확인할 사항
동의 페이지에 요청이 만료되었다고 표시	클라이언트에서 연결을 다시 시작하세요. 보류 요청은 유효 기간이 짧습니다
클라이언트는 연결되었지만 도구가 비어 있음 / 잘못된 프로젝트	Runtime URL과 Builder URL을 확인하세요. 단일 프로젝트를 의도했다면 `x-project-id`를 설정하세요
`run_*` 도구 누락	먼저 EKB에서 워크플로우 / 사용자 정의 도구를 게시하세요. 초안은 노출되지 않습니다
에이전트의 `ask_*` 누락	동일한 계정으로 제품에서 해당 에이전트에 접근할 수 있는지 확인하세요
Builder가 잘못된 프로젝트에 생성	쓰기 도구에서 모델이 `target_project_id` / `project_id`를 전달하는지 확인하세요
API 키가 한 프로젝트에서만 작동	프로젝트 간 `list_odin_projects`가 필요하면 사용자 수준 키로 전환하세요

전제 조건​

MCP 클라이언트에 EKB 추가​

클라이언트 팁​

프롬프트 시 로그인​

프로젝트 고정 (Runtime)​

헤드리스 접근 (CI 및 자동화)​

문제 해결​