daiops MCP 연결 가이드

외부 MCP 클라이언트(Claude Desktop·IDE·타 에이전트)에서 daiops 직원(워크스페이스)을 표준 MCP 도구로 호출하는 방법. (AGENT-API-3 Phase A)

REST 면(트리거·SSE 챗)은 GET /api/v1/openapi로 문서화되며, MCP 면은 JSON-RPC라 이 문서로 별도 안내한다.

방향 주의: 이 MCP 서버는 "직원 자체"를 외부에 노출한다. 에이전트가 내부에서 쓰는 연동 도구(slack_read 등, mcp-bridge-server.ts)와는 반대 방향이다.

1. 엔드포인트 (Streamable HTTP transport)

POST /api/v1/workspaces/{workspaceId}/mcp   # JSON-RPC (initialize / tools/list / tools/call / notifications)
GET  /api/v1/workspaces/{workspaceId}/mcp   # server→client SSE 스트림(세션 확립 후)

• Base URL: https://daiops.com
• Content-Type: application/json (POST)

2. 인증

Bearer API 키(dai_live_…)를 사용한다. Settings → API 키에서 발급.

• mcp (전체): 대화(chat_with_employee)·작업 실행(run_task)·파일 반출(deliver_file)·세션 취소(cancel_session) 등 모든 도구.
• mcp:read (읽기 전용): 지식 조회(query_wiki)·세션 나열(list_sessions)만. mcp가 mcp:read를 자동 포함한다. 읽기 전용 키는 tools/list에서 실행 도구가 감춰지고, 호출 시 -32003(insufficient_scope).

Authorization: Bearer dai_live_xxxxxxxx

• rate limit: 키 단위 분당 120회 초과 시 429(+Retry-After).
• quota: 비용 발생 경로(tools/call)에만 사용량 한도 게이트 적용. 핸드셰이크(initialize/tools/list)는 무비용.

3. 세션 핸드셰이크

1. initialize 요청 → 응답 헤더로 Mcp-Session-Id(mcp_…) 발급.
2. 이후 모든 요청(tools/list·tools/call·ping)은 그 Mcp-Session-Id 헤더를 되보내야 한다.
3. 서버는 무상태다 — 세션 상태를 영속하지 않는다(serverless 다중 인스턴스). 대화 연속성은 각 도구의 caller_id/session_id 인자가 담당한다.

4. Claude Desktop 연결

Claude Desktop은 원격 MCP(HTTP)를 mcp-remote 브리지로 연결한다. claude_desktop_config.json:

{
  "mcpServers": {
    "daiops": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://daiops.com/api/v1/workspaces/<WORKSPACE_ID>/mcp",
        "--header",
        "Authorization: Bearer ${DAIOPS_API_KEY}"
      ],
      "env": { "DAIOPS_API_KEY": "dai_live_xxxxxxxx" }
    }
  }
}

• <WORKSPACE_ID>: 연결할 직원(워크스페이스)의 UUID.
• DAIOPS_API_KEY: mcp 스코프 API 키.
• 설정 후 Claude Desktop 재시작 → 도구 목록에 chat_with_employee·run_task·query_wiki·deliver_file·list_sessions·cancel_session이 나타난다.

Streamable HTTP를 네이티브 지원하는 클라이언트라면 mcp-remote 없이 URL+헤더를 직접 지정해도 된다.

5. 노출 도구 (tools/list)

백엔드가 준비된(ready) 도구만 노출된다.

파일 인바운드는 MCP 미지원 — MCP 도구에는 파일 입력 파라미터가 없다. 파일을 넣으려면 REST(POST /messages + 업로드 티켓 POST /files)나 A2A(FilePart)를 쓴다. MCP는 산출물 받기(위 chat_with_employee <generated_files>·deliver_file)만 지원.

6. JSON-RPC 예시

initialize

curl -sD - -X POST https://daiops.com/api/v1/workspaces/$WS/mcp \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
# → 응답 헤더 Mcp-Session-Id: mcp_....  본문 result.protocolVersion / serverInfo

tools/list

curl -s -X POST https://daiops.com/api/v1/workspaces/$WS/mcp \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# → result.tools[] (chat_with_employee / run_task / query_wiki / deliver_file / list_sessions / cancel_session)

tools/call

curl -s -X POST https://daiops.com/api/v1/workspaces/$WS/mcp \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"query_wiki","arguments":{}}}'
# → result.content[] ([{type:"text", text:"..."}]) + isError

7. 오류 규약 (JSON-RPC)

JSON-RPC 오류는 HTTP 200 본문에 error로 실린다(전송 계층 오류는 HTTP 상태로).

도구 실행 오류(필수 인자 누락·내부 실패 등)는 JSON-RPC error가 아니라 result.isError:true + content로 반환된다(MCP 관례). 프로토콜 오류(-326xx)와 도구 오류를 구분하라.

8. 라이프사이클 — 직원 상태와 auto-wake

직원(워크스페이스)은 유휴 시 자동 퇴근(중지)하고, 장기 미사용 시 휴직(archived, 컴퓨트 삭제)한다. 실행 도구는 상태에 따라 다르게 반응한다:

• 퇴근(stopped): chat_with_employee/run_task 호출 시 자동 출근(auto-wake) 후 실행. 첫 응답이 수 초~수십 초 지연될 수 있다. run_task는 즉시 "accepted"를 반환하고 백그라운드에서 깨워 실행한다.
• 휴직(archived): 컴퓨트가 삭제된 상태라 자동 복귀하지 않는다. 도구 결과 isError:true + "on leave (archived) and must be revived". 복귀(revive)는 소유자가 대시보드에서 수행.
• 깨우기 실패/일시 불가: isError:true + "waking up or temporarily unavailable". 잠시 후 재시도.
• 직원이 바쁨(동시 실행 상한 초과): chat_with_employee/run_task 모두 isError:true + "Employee is busy, retry shortly (retry in ~Ns)". 리소스 등급별 동시 실행 상한을 넘으면 발생 — N초 후 재시도하면 처리된다(MCP는 HTTP 헤더가 없어 재시도 힌트를 이 텍스트로 전달).
• 활발히 호출되는 직원은 자동 퇴근되지 않는다(호출이 활동 타이머를 갱신).

9. e2e 검증

로컬/실연결 검증은 docs/agent-api/e2e-mcp.sh(initialize→tools/list→tools/call) 또는 MCP Inspector(npx @modelcontextprotocol/inspector)로 위 URL+헤더를 지정해 수행한다.