> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 개인 MCP

> 권한과 만료 기간을 지정한 자격 증명으로 어시스턴트를 본인 APIAny.AI 계정에 연결합니다.

MCP가 처음인가요? [클라이언트 연결 안내](https://apiany.ai/ko/mcp-guide)의 단계별 예시로 시작하세요.

개인 MCP는 어시스턴트가 모델, 작업, 사용량, API 키, 결제, 프로필, 파일 등 **본인 계정**을 조회하고 관리하도록 합니다. 플랫폼 관리 기능은 제공하지 않습니다. 관리자도 개인 자격 증명으로는 본인 데이터만 접근합니다.

## 자격 증명 선택

| 자격 증명 | 엔드포인트 | 접근 범위 |
| - | - | - |
| `sk_…` | `https://apiany.ai/mcp` | 기존 모델 도구 6개: 개인 `input` 래퍼 없이 평면 인수 사용 |
| `mcp_user_…` | `https://apiany.ai/mcp` | 허용된 범위의 본인 계정만 |
| `sa_admin_…` | `/api/admin/agent/mcp` | 별도 관리자 자격 증명 및 권한: 일반 사용자 이용 불가 |

기존 API 키 MCP는 `list_models`, `get_balance`, `chat_completion`, `generate_image`, `generate_video`, `get_task`를 유지합니다. 개인 토큰에서는 같은 이름의 입력이 다를 수 있으므로 연결 후 `tools/list`를 확인하세요.

## 토큰 생성 및 연결

1. [대시보드 → Agent](https://apiany.ai/ko/dashboard/agent)에 로그인하고 **Personal MCP**를 엽니다.
2. 이름, 필요한 권한, **1\~365일**의 유효 기간을 설정합니다. 기본값은 **30일**입니다.
3. `models:invoke` 또는 `utilities:invoke`에는 본인의 활성 API 키를 연결합니다. 모델 제한, 예산 및 RPM은 그대로 적용됩니다. 계정 조회에는 양수 잔액이 필요하지 않습니다.
4. 생성 시 `mcp_user_` 토큰을 클라이언트의 비밀 설정에 복사합니다. 코드, 대화, 로그에 넣지 마세요. 필요 없으면 같은 대시보드에서 폐기합니다.

아래 값으로 원격 **Streamable HTTP** MCP 연결을 설정합니다. 클라이언트는 Bearer 토큰 `Authorization` 헤더를 지원해야 합니다. 프로토콜 버전은 클라이언트가 협상합니다. OAuth는 구현되지 않아 OAuth 전용 클라이언트는 연결할 수 없습니다. 아래 표는 연결 정보이며 특정 클라이언트 설정 파일이 아닙니다.

| 설정 | 값 |
| - | - |
| URL | `https://apiany.ai/mcp` |
| Transport | Streamable HTTP |
| Authorization | `Bearer mcp_user_YOUR_TOKEN` |

## 호출 전에 도구 확인

연결 초기화 후 `{}`로 `get_capabilities`를 호출하고 `tools/list`를 확인합니다. `audience: user`, `ownership: self`, 허용된 `scopes` 및 도구, `oauth: false`가 반환됩니다. 다른 개인 도구는 업무 매개변수가 없어도 `input` 객체를 사용합니다.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_capabilities",
    "arguments": {}
  }
}
```

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_balance",
    "arguments": {
      "input": {}
    }
  }
}
```

## 권한

권한은 웹에서 선택합니다. MCP는 접근 권한을 만들거나 스스로 확장하거나 API 키를 관리자 자격으로 바꿀 수 없습니다. 숨겨진 도구도 호출마다 소유권과 권한을 확인합니다. `usage:content`에는 명시적 내용 요청과 API 키 내용 기록 설정도 필요합니다.

| Scope | 결과 |
| - | - |
| `models:read` | 모델, API 안내 및 유틸리티 조회 |
| `models:invoke` | 모델 실행 및 본인 작업 조회 |
| `usage:read` | 사용량, 요약 및 진단 조회 |
| `usage:content` | 명시적으로 요청한 저장된 요청 내용 조회 |
| `keys:read` | 비밀 값을 제외한 API 키 설정 조회 |
| `keys:write` | API 키 생성, 변경, 비활성화 및 삭제 |
| `keys:secrets` | 웹사이트 승인 후 API 키 한 번 공개 |
| `billing:read` | 잔액, 주문, 구독 및 상품 조회 |
| `billing:write` | 결제 링크, 코드 사용, 알림 및 구독 취소 요청 |
| `account:read` | 프로필, 계정 작업 및 실행 기록 조회 |
| `account:write` | 프로필 변경 및 민감한 계정 작업 요청 |
| `utilities:invoke` | 계정 자격과 할당량에 따라 유틸리티 실행 |
| `files:write` | 본인 파일 업로드, 읽기 및 게시 |

## 쓰기, 결과 및 안전한 재시도

쓰기마다 의도별 고유 `idempotencyKey`를 미리 저장합니다. **공백 없는 인쇄 가능 ASCII 1\~191자**입니다. 응답을 잃으면 동일한 도구, 입력, 키로 다시 호출합니다. 다른 입력에 같은 키를 쓰면 `idempotency_conflict`입니다. 각 업로드 단계에는 별도 키를 사용하세요.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "update_api_key",
    "arguments": {
      "input": {
        "key_id": "YOUR_KEY_ID",
        "rpmLimit": 60
      },
      "idempotencyKey": "set-key-rpm-20261106-01"
    }
  }
}
```

성공 결과는 `structuredContent`와 `content`의 JSON 텍스트로 반환됩니다. 최초 실행 형식은 아래와 같습니다. 재호출은 `replayed: true`와 식별자가 있는 작은 `receipt`를 반환하며 원본 전체 결과나 키 비밀 값은 반환하지 않습니다.

```json theme={null}
{
  "execution_id": "EXECUTION_ID",
  "replayed": false,
  "status": "completed",
  "data": {
    "balance": 100,
    "key": null
  }
}
```

`execution_pending`(409)은 최초 호출이 미해결임을 뜻합니다. `execution_unknown`(409) 또는 `status: unknown`은 실제 작업이 이미 발생했을 수 있다는 뜻입니다. `get_execution` 다음에 관련 작업, 주문 또는 계정 작업을 확인하세요. **새 키로 이 상태를 우회하지 마세요.** MCP 실행이 완료돼도 모델 작업이나 웹 확인은 대기 상태일 수 있습니다.

## 모델 및 유틸리티 사용

`list_models` → `get_model_schema`로 공개 모델 ID를 선택합니다. `body`는 해당 모델이 지원하는 전체 HTTP JSON 요청을 받습니다. 모델 ID는 `body.model`에 넣고 `generate_content`는 대신 바깥쪽 `model`이 필수입니다. 파일 필드는 `edit_image`의 `image`, `image[]`, `mask`만 지원합니다. 다른 미디어 입력에는 게시된 URL을 사용하세요.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "chat_completion",
    "arguments": {
      "input": {
        "body": {
          "model": "PUBLIC_MODEL_ID",
          "messages": [
            {
              "role": "user",
              "content": "Hello"
            }
          ],
          "stream": false
        }
      },
      "idempotencyKey": "chat-example-20261106-01"
    }
  }
}
```

비동기 이미지/동영상은 반환된 `task_id`를 저장하고 `get_task`로 조회합니다. `stream: true` 이벤트는 최종 MCP 결과에 모아서 반환됩니다. SDK 실시간 스트리밍에는 HTTP API를 사용하세요. 선택적 UUID v4 `client_request_id`는 동영상 요청 연결용이며 `idempotencyKey`와 별개입니다. 모델 호출은 크레딧을 사용할 수 있습니다.

모델 결과 수집 한도는 **8 MiB 및 300초**입니다. 수집이 중단되거나 한도를 초과하면 실행 영수증에 알려진 `request_id`가 보존됩니다. 먼저 `get_execution`과 기존 요청 또는 작업을 확인하세요. 미해결 호출을 대신해 새 유료 요청을 만들거나 새 멱등 키를 사용하지 마세요. 클라이언트 연결 종료가 이미 접수된 모델 작업의 취소를 뜻하지는 않습니다.

32개 유틸리티는 `list_utilities` → `get_utility_schema` → `run_utility` 순서로 사용합니다. 기존 자격과 할당량이 유지되며 일부 일괄 작업은 유료 계정 자격이 필요합니다. 값은 `parameters`, 본인 파일 ID는 `files`에 넣습니다. 바이너리/큰 결과는 임시 파일입니다. 파일 입력과 비 JSON 출력에는 `files:write`도 필요합니다.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "run_utility",
    "arguments": {
      "input": {
        "utility": "image-hash",
        "parameters": {},
        "files": {
          "image": [
            "YOUR_FILE_ID"
          ]
        }
      },
      "idempotencyKey": "image-hash-example-01"
    }
  }
}
```

## 파일 업로드 및 다운로드

1. 파일명, MIME 형식, 정확한 바이트 크기로 `begin_upload`를 호출합니다. 최대 **250 MiB**입니다.
2. 0부터 시작하는 `index`와 Base64 `data`로 `upload_chunk`를 호출합니다. 디코딩 후 최대 **1 MiB**이며 인덱스는 0부터 연속이어야 합니다.
3. `file_id`와 선택적 소문자 SHA-256으로 `finish_upload`를 호출하고 `status: ready`를 확인합니다.
4. 지원 도구에 ID를 전달합니다. `get_artifact`는 메타데이터를, `offset` 지정 시 Base64 바이트를 반환합니다. `next_offset`이 `null`일 때까지 계속합니다. 다운로드 링크는 소유자의 웹 로그인이 필요합니다.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "begin_upload",
    "arguments": {
      "input": {
        "name": "example.png",
        "mime_type": "image/png",
        "size": 12345
      },
      "idempotencyKey": "upload-example-begin-01"
    }
  }
}
```

임시 파일은 암호화되어 본인 계정만 접근하며 **24시간** 뒤 만료됩니다. 한도는 **1 GiB / 미만료 파일 100개**이며 도구별 제한은 더 작을 수 있습니다. `upload_image`와 `upload_media`는 별도 게시 작업입니다. 결과 URL은 공유할 수 있으므로 해당 URL로 접근을 허용할 파일만 게시하세요.

파일 작업은 내용을 읽기 전에 소유권, 준비 상태, 파일 수와 크기를 확인합니다. 같은 ID를 반복해도 각 참조가 개수와 총 크기에 포함됩니다.

* `upload_media`: 최대 **20개 파일 / 총 250 MiB**.
* `upload_image`: 파일 1개, 최대 **50 MiB**.
* `edit_image`: 모든 필드 합계 최대 **20개 파일**, 그중 `mask`는 최대 **1개**이며 **파일당 50 MiB / 총 100 MiB**입니다. 입력 스키마의 필드별 배열 제한도 적용됩니다.
* `run_utility`: `get_utility_schema`의 파일 수, 개별 크기 및 총 크기 제한이 적용되며, 카탈로그가 더 허용해도 **총 250 MiB**를 초과할 수 없습니다.

## 웹사이트 확인 및 결제

* **API 키 비밀 값:** `start_reveal_key_action` → 사용자가 `confirmation_url`에서 승인 → 작업 `id`를 `action_id`로 `reveal_api_key` 호출. 해당 키와 자격 증명에 연결되며 작업 생성 15분 후 만료되고 한 번만 사용됩니다. `create_api_key`는 메타데이터만 반환합니다.
* **구독 취소:** `cancel_subscription`이 확인을 시작하고 사용자가 웹에서 실행합니다. 완료 보고 전에 `get_account_action`과 구독 상태를 확인합니다.
* **비밀번호/계정 삭제:** `password_change` 또는 `delete_account`로 `start_account_action`을 호출합니다. 이메일 코드와 비밀번호는 사용자가 웹에서 입력하며 어시스턴트에 전달하지 않습니다. 삭제는 접근을 폐기하고 로그아웃하므로 이후 MCP를 계속 조회하지 마세요.
* **결제:** `list_billing_products` → `create_checkout` → 사용자 결제 → `get_payment_status`. 결제 링크는 결제 성공이 아닙니다.
* **실제 메시지:** `resend_invoice`, `test_credit_alert`는 이메일 또는 Webhook을 보냅니다. 사용자가 명시적으로 발송을 요청할 때만 호출합니다.

## 중복 작업 없이 오류 처리

연결/인증 실패는 HTTP 오류일 수 있습니다. 도구 실패는 `isError: true`이며 `structuredContent.error.code`, `status`, `execution_id`, `receipt`를 확인합니다. 재호출에는 미완료 실행 `status`가 올 수 있습니다.

```json theme={null}
{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": "execution_pending",
      "message": "The original execution is pending; inspect its receipt before retrying",
      "status": 409,
      "execution_id": "EXECUTION_ID"
    }
  }
}
```

| Code | 결과 |
| - | - |
| 401 · `invalid_grant` | 토큰이 무효, 만료 또는 폐기됨. 웹 Personal MCP 확인. |
| 403 · `insufficient_scope` | 웹에서 필요한 권한 선택. 어시스턴트는 스스로 확장 불가. |
| 400 · `model_key_required` | 본인의 활성 API 키 연결. |
| 400 · `invalid_input` / `idempotency_required` | `tools/list` 확인 후 입력 수정 또는 쓰기 키 추가. |
| 404 · `not_found` | 사용 불가, 만료 또는 타인 리소스. 다른 계정 ID 사용 금지. |
| 409 · `idempotency_conflict` | 키가 다른 입력에 사용됨. 새 작업 전 기존 의도 확인. |
| 409 · `execution_pending` / `execution_unknown` | 기존 실행과 리소스 확인. 새 키로 재시도 금지. |
| 409 · `confirmation_required` / `action_closed`; 410 · `action_expired` | 웹 작업 상태 확인. 승인과 실행은 별도 단계. |
| 413 · `file_too_large` / `response_too_large`; 429 · `file_quota` | 도구 및 임시 파일 제한 준수. 모델 출력 초과 시 유료 재호출 전 기록 확인. |
| 402 / 429 | 잔액, 키 예산, RPM, 이용 자격 및 실제 오류 확인. |
| 503 · `storage_unavailable` | 개인 MCP 일시 이용 불가. 실행 ID 저장 후 나중에 확인. |

## 유용한 읽기 전용 시작점

* 지출 확인: `get_balance` → `summarize_usage` → 개별 요청 `list_usage`.
* 실패 조사: `task_id`로 `diagnose_request`; 모델 재호출 전에 실제 오류와 환불 상태 확인.
* 연결 준비: `list_models` → `get_model_schema` → `get_api_guide`; 안내 조회에는 모델 호출 불필요.
* 계정 보안 확인: `list_api_keys` → `get_api_key` → `list_login_records`.

사용량은 시간대가 포함된 ISO 8601 `from` 이상, `to` 미만입니다. 기본 최근 30일, 최대 366일이며 보관 기록만 포함합니다. 없는 날짜는 사용량 0의 증거가 아닙니다. `get_overview.timezoneOffset`은 JavaScript `getTimezoneOffset` 분 값(UTC−현지 시간), 기본 0입니다. 사용 목록과 요약은 UTC입니다.

`summarize_usage`의 `creditsCharged`, `netCreditsCharged`는 보관 기록의 순청구액입니다. `linkedRefundCredits`는 비동기 작업에 연결된 알려진 환불만 포함합니다. `knownGrossCredits`는 순청구액에 이 환불을 더한 값이며 완전한 총지출은 아닙니다. `totalTokens`, `averageLatencyMs`, `pending`, `processing`은 일치하는 보관 요청 기준입니다.

[전체 도구 참조](https://docs.apiany.ai/ko/reference/mcp-tools.md), [인증](https://docs.apiany.ai/ko/authentication.md), [HTTP API 오류](https://docs.apiany.ai/ko/operations/errors.md)를 확인하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.