Loafacto Hub 문서

Appearance

API 키로 시스템 MCP 사용하기 ​

외부 AI 에이전트나 스크립트에서 Loafacto의 내장 MCP 도구(태스크/문서/GitHub)를 사용하려면 개인 API 키가 필요합니다. 이 문서는 발급부터 호출까지의 전체 흐름을 설명합니다.

1. API 키 발급 ​

  1. 웹에 로그인 후 마이페이지 → API 키 메뉴로 이동
  2. [+ 새 API 키] 버튼 클릭
  3. 입력 항목:
    • 이름: 키의 용도를 알아볼 수 있는 라벨 (예: 내 Claude Desktop, N8N 연동)
    • 권한 스코프: 아래 표 참고. 체크된 항목만 호출 가능
    • 만료: 무기한 / 30일 / 90일 / 180일 / 1년 중 선택
  4. [생성] 클릭 → 평문 키가 한 번만 표시됨 → 복사 후 안전한 곳(비밀번호 관리자 등)에 보관

⚠️ 키를 분실하면 복구 불가능합니다. 새 키를 발급받고 기존 키는 삭제하세요.

스코프 목록 ​

스코프설명
tasks:read태스크 목록/통계/검색 조회
tasks:write태스크 생성/수정/삭제
docs:read문서 목록/검색/상세 조회
docs:write문서 생성/수정/삭제
github:readGitHub 커밋/이슈/PR/워크플로우 조회
github:writeGitHub 이슈 생성/댓글 작성

2. HTTP로 도구 호출 ​

엔드포인트 ​

  • 사용 가능 도구 목록: GET https://<your-host>/api/v1/public/mcp/tools
  • 도구 호출: POST https://<your-host>/api/v1/public/mcp/call

인증 헤더 ​

모든 요청에 다음 헤더 필수:

Authorization: Bearer lfct_pk_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

사용 가능한 도구 조회 ​

bash
curl https://loafacto.com/api/v1/public/mcp/tools \
  -H "Authorization: Bearer lfct_pk_..."

응답 예시:

json
{
  "scopes": ["tasks:read", "tasks:write"],
  "tool_count": 8,
  "tools": [
    {
      "name": "list_tasks",
      "description": "태스크 목록 조회",
      "scope": "tasks:read",
      "parameters": {
        "status":      { "type": "str", "default": "",   "required": false },
        "assignee_id": { "type": "str", "default": "",   "required": false },
        "limit":       { "type": "int", "default": 50,   "required": false }
      }
    }
    // ...
  ]
}

도구 호출 ​

bash
curl https://loafacto.com/api/v1/public/mcp/call \
  -H "Authorization: Bearer lfct_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_tasks",
    "arguments": { "status": "in_progress", "limit": 10 }
  }'

응답:

json
{
  "result": [
    { "id": "...", "title": "...", "status": "in_progress", ... }
  ]
}

태스크 생성 예시 (쓰기) ​

bash
curl https://loafacto.com/api/v1/public/mcp/call \
  -H "Authorization: Bearer lfct_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_task",
    "arguments": {
      "title": "주간 보고서 작성",
      "description": "이번 주 진행 상황 정리",
      "priority": "high",
      "due_date": "2026-05-01"
    }
  }'

3. 데이터 범위 ​

API 키로 호출 시 해당 키 소유자의 데이터 범위로 자동 필터링됩니다:

  • 태스크: 본인이 생성했거나 본인에게 할당된 것
  • 문서: 본인이 작성했거나 공개(is_public=true)인 것
  • GitHub: 관리자가 등록한 공용 레포 + PAT 권한 내

다른 사용자의 비공개 데이터는 절대 접근할 수 없습니다.

4. 응답 코드 ​

코드의미
200성공
400인자 오류 (잘못된 enum, 필수 누락 등)
401인증 실패 (키 없음 / 만료 / 폐기)
403권한 부족 (해당 스코프 미체크 or 타인 데이터 수정 시도)
404존재하지 않는 도구명
500서버 오류

5. Claude Desktop 연동 ​

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는
%APPDATA%\Claude\claude_desktop_config.json (Windows) 에 추가:

json
{
  "mcpServers": {
    "loafacto": {
      "transport": "http",
      "url": "https://loafacto.com/api/v1/public/mcp",
      "headers": {
        "Authorization": "Bearer lfct_pk_..."
      }
    }
  }
}

ℹ️ 현재는 JSON-RPC 스타일의 경량 HTTP 엔드포인트를 제공합니다. MCP 표준의 SSE/streamable HTTP 전송 지원은 향후 추가 예정입니다.

6. 보안 권장 사항 ​

  • 환경 변수 사용: 키를 코드에 하드코딩하지 말고 .env 또는 비밀 저장소에서 주입
  • 최소 권한 원칙: 쓰기 작업이 필요 없으면 :write 스코프를 체크하지 마세요
  • 짧은 만료 기간: CI/CD 같은 자동화엔 90일 이하 만료 설정 후 주기적 교체
  • 노출 시 즉시 폐기: 실수로 키가 노출되면 마이페이지에서 즉시 삭제 → 새 키 발급

7. 사용 통계 확인 ​

마이페이지 → API 키에서 각 키의 다음 정보를 확인할 수 있습니다:

  • 마지막 사용 시점
  • 누적 호출 횟수
  • 만료까지 남은 일수

문제가 발생하면 관리자에게 문의하시거나 마이페이지의 "지원 문의" 채널을 이용하세요.