개인 MCP

MCP가 처음인가요? 클라이언트 연결 안내의 단계별 예시로 시작하세요. 개인 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를 확인하세요.

토큰 생성 및 연결

대시보드 → Agent에 로그인하고 Personal MCP를 엽니다.
이름, 필요한 권한, 1~365일의 유효 기간을 설정합니다. 기본값은 30일입니다.
models:invoke 또는 utilities:invoke에는 본인의 활성 API 키를 연결합니다. 모델 제한, 예산 및 RPM은 그대로 적용됩니다. 계정 조회에는 양수 잔액이 필요하지 않습니다.
생성 시 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 객체를 사용합니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_capabilities",
    "arguments": {}
  }
}

{
  "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입니다. 각 업로드 단계에는 별도 키를 사용하세요.

{
  "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를 반환하며 원본 전체 결과나 키 비밀 값은 반환하지 않습니다.

{
  "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을 사용하세요.

{
  "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도 필요합니다.

{
  "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"
    }
  }
}

파일 업로드 및 다운로드

파일명, MIME 형식, 정확한 바이트 크기로 begin_upload를 호출합니다. 최대 250 MiB입니다.
0부터 시작하는 index와 Base64 data로 upload_chunk를 호출합니다. 디코딩 후 최대 1 MiB이며 인덱스는 0부터 연속이어야 합니다.
file_id와 선택적 소문자 SHA-256으로 finish_upload를 호출하고 status: ready를 확인합니다.
지원 도구에 ID를 전달합니다. get_artifact는 메타데이터를, offset 지정 시 Base64 바이트를 반환합니다. next_offset이 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가 올 수 있습니다.

{
  "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은 일치하는 보관 요청 기준입니다. 전체 도구 참조, 인증, HTTP API 오류를 확인하세요.

시작하기

연동 가이드

핵심 API

운영 및 결제

개인 MCP

자격 증명 선택

토큰 생성 및 연결

호출 전에 도구 확인

권한

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

모델 및 유틸리티 사용

파일 업로드 및 다운로드

웹사이트 확인 및 결제

중복 작업 없이 오류 처리

유용한 읽기 전용 시작점

​자격 증명 선택

​토큰 생성 및 연결

​호출 전에 도구 확인

​권한

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

​모델 및 유틸리티 사용

​파일 업로드 및 다운로드

​웹사이트 확인 및 결제

​중복 작업 없이 오류 처리

​유용한 읽기 전용 시작점

자격 증명 선택

토큰 생성 및 연결

호출 전에 도구 확인

권한

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

모델 및 유틸리티 사용

파일 업로드 및 다운로드

웹사이트 확인 및 결제

중복 작업 없이 오류 처리

유용한 읽기 전용 시작점