MCP 엔드포인트
IronFlock은 MCP 서버입니다. Claude를 비롯해 Model Context Protocol을 지원하는 모든 클라이언트는 API 키가 허용하는 범위 안에서 IronFlock이 제공하는 도구로 프로젝트 목록을 조회하고, 프로젝트의 디바이스, 앱, 데이터를 읽고, 이에 대해 작업할 수 있습니다. 이 엔드포인트는 REST API와 같은 API 서비스의 일부이며, 같은 API 키를 사용합니다.
주소 및 인증
| IronFlock 클라우드의 URL | https://api.ironflock.com/mcp |
| 어플라이언스의 URL | https://api. 뒤에 어플라이언스의 도메인, 그 뒤에 /mcp. 어플라이언스가 IronFlock API 서비스를 실행하게 되면 사용할 수 있습니다 |
| 전송 방식 | Streamable HTTP |
| 인증 | Authorization: Bearer <your API key> |
API 키 생성에 설명된 대로 Studio에서 API 키를 생성하십시오. 모든 요청에는 키가 포함됩니다. 키가 없거나 유효하지 않은 키(삭제됨, 만료됨, 또는 다른 IronFlock의 키)로 보낸 요청은 HTTP 401로 응답합니다. 서버는 브라우저를 통한 로그인(OAuth)을 제공하지 않습니다. 키가 유일한 접근 방법입니다.
서버는 세션을 유지하지 않습니다. 모든 요청은 각각 독립적으로 응답되므로, 클라이언트는 자유롭게 연결하고, 연결을 끊고, 다시 연결할 수 있습니다. 서버는 모든 요청에 하나의 JSON 본문으로 응답하며, 수신할 이벤트 스트림은 없습니다.
Claude 연결
키는 Claude 자체의 설정에 직접 입력합니다. 채팅에 키를 절대 붙여 넣지 마십시오.
Claude Code
Claude Code는 IronFlock의 MCP 서버를 선언하는 ironflock 플러그인을 통해 연결합니다. 터미널, IDE 확장 프로그램, Claude 데스크톱 앱의 Code 탭에서 작동합니다.
-
Claude Code 세션에서 마켓플레이스를 추가하고 플러그인을 설치합니다:
/plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock -
설치하면 두 가지 설정이 있는 대화 상자가 열립니다. IronFlock API address는 클라우드의 경우
https://api.ironflock.com이고, 어플라이언스의 경우https://api.뒤에 어플라이언스의 도메인을 붙인 주소입니다. 두 경우 모두/mcp와 끝의 슬래시를 붙이지 않습니다. IronFlock API key는 Studio에서 받은 키입니다. Claude Code는 이 키를 설정 파일이 아니라 시스템의 보안 자격 증명 저장소에 보관합니다. -
Claude Code를 다시 시작합니다. 그러면
/mcp에 서버plugin:ironflock:ironflock이 연결됨으로 표시됩니다.
나중에 /plugin configure ironflock@ironflock으로 설정을 변경하고 Claude Code를 다시 시작하십시오. 키가 설정될 때까지 서버는 시작되지 않습니다. 셸에서 설치하면(claude plugin install) 대화 상자가 열리지 않으므로, 세션에서 /plugin configure ironflock@ironflock으로 설정을 마치십시오. Claude Code로 개발에서 플러그인과 스킬을 설명합니다.
웹, 데스크톱, 휴대폰의 Claude와 Cowork
플러그인 자체의 연결은 Claude Code에서만 작동합니다. Claude 앱의 채팅과 Cowork에서는 IronFlock을 키를 요청 헤더로 사용하는 사용자 지정 커넥터로 한 번 추가합니다. 사용자 지정 커넥터의 요청 헤더는 일부 조직에서만 사용할 수 있는 베타 기능입니다. 아래 대화 상자에 Request headers 섹션이 없다면 조직에서 아직 이 기능을 사용할 수 없으며, 당분간 그곳에서는 IronFlock을 연결할 수 없습니다. Claude Code는 작동합니다.
- Customize > Connectors를 열고 Add를 선택한 다음 Add custom connector를 선택합니다.
- 이름
IronFlock과 서버 URLhttps://api.ironflock.com/mcp를 입력합니다. - Authentication을 No sign-in으로 설정합니다.
- Request headers에서 헤더
Authorization을 추가하고, 값으로Bearer뒤에 키를 입력합니다. 즉 Bearer라는 단어, 공백 하나, 그리고 키입니다.Bearer가 없으면 IronFlock이 요청을 거부합니다. - Add를 선택합니다.
Team 및 Enterprise 플랜에서는 소유자가 Organization settings > Connectors에서 Add를 선택한 다음 Custom을 선택하여 커넥터를 추가합니다. 요청 헤더는 Advanced 아래에 있을 수 있습니다. 이 커넥터를 사용하는 모든 사람은 소유자가 입력한 하나의 키로 동작하므로, 그 키에는 모든 사용자가 사용해도 되는 스코프와 프로젝트만 부여하십시오.
커넥터의 요청 헤더는 편집할 수 없습니다. 키를 변경하려면 커넥터를 제거하고 다시 추가하십시오. 커넥터는 Anthropic의 서버에서 연결하므로, 주소는 인터넷에서 접근할 수 있어야 합니다. 클라우드는 그렇습니다. 회사 네트워크에서만 접근할 수 있는 어플라이언스는 대개 그곳에서 연결할 수 없지만, 그 네트워크 안의 컴퓨터에서 실행되는 Claude Code는 연결할 수 있습니다.
기타 MCP 클라이언트
Streamable HTTP와 요청 헤더를 지원하는 클라이언트라면 URL과 헤더 Authorization: Bearer <your API key>로 연결합니다. 공유하거나 커밋하는 파일에 키를 넣지 마십시오.
연결 확인
Claude에게 IronFlock 프로젝트 목록을 보여 달라고 한 다음, 그중 한 프로젝트의 디바이스 목록을 요청하십시오. Claude는 읽기만 하는 list_projects와 list_devices를 호출합니다.
도구
서버는 다음 영역에서 33개의 도구를 제공합니다. 대부분은 하나의 프로젝트에서 작동하며, list_projects가 알려 주는 프로젝트의 swarm_key를 받습니다. 무언가를 변경하거나 삭제하는 도구에는 그렇다는 표시가 있어, Claude 같은 클라이언트가 호출하기 전에 사용자에게 물어볼 수 있습니다.
프로젝트
| 도구 | 스코프 | 하는 일 |
|---|---|---|
list_projects | devices:read | 키로 작업할 수 있는 프로젝트 목록 조회 |
디바이스
| 도구 | 스코프 | 하는 일 |
|---|---|---|
list_devices | devices:read | 프로젝트의 디바이스, 각 디바이스에 설치된 앱, 앱의 실행 여부, 디바이스의 온라인 여부 목록 조회 |
create_device | devices:write | 프로젝트에 디바이스를 생성하고 그 키와 이름을 응답 |
delete_device | devices:write | 프로젝트에서 디바이스를 영구 삭제 |
프로젝트의 앱
| 도구 | 스코프 | 하는 일 |
|---|---|---|
list_project_apps | apps:read | 프로젝트에 설치된 앱과 각 앱이 실행 중인 디바이스 수 목록 조회 |
check_app_status | apps:read | 앱이 디바이스에서 실행 중인지, 데이터가 들어오는지 표시 |
install_app | apps:write | 스토어 앱을 프로젝트에, 선택적으로 디바이스에도 설치 |
set_app_state | apps:write | 설치된 앱을 디바이스에서 시작하거나 중지 |
update_app | apps:write | 설치된 앱을 최신 릴리스로 업데이트 |
uninstall_app | apps:write | 디바이스 또는 프로젝트 전체에서 앱 제거 |
App Store 및 비용
| 도구 | 스코프 | 하는 일 |
|---|---|---|
search_apps | apps:read | 기능으로 App Store를 검색하고 일치하는 앱을 가격과 함께 반환 |
get_app_details | apps:read | 스토어 앱 1~3개의 설명, README, 가격 읽기 |
get_install_quote | apps:read | 앱 설치에 드는 비용과 설치를 막는 요인 조회 |
estimate_project_cost | apps:read | 프로젝트 구성의 연간 비용 추정. 구매는 이루어지지 않음 |
sync_app_to_store | apps:write | 어플라이언스 전용: IronFlock 클라우드 스토어의 앱을 어플라이언스 자체 스토어로 복사 |
데이터
| 도구 | 스코프 | 하는 일 |
|---|---|---|
get_schema | data:read | 프로젝트 데이터베이스의 테이블, 뷰, 컬럼 설명 |
execute_sql | data:read | 프로젝트 데이터베이스에서 읽기 전용 SELECT 쿼리 하나 실행 |
list_dashboards | data:read | 프로젝트의 대시보드 목록 조회 |
list_app_files | data:read | 앱이 프로젝트에 저장하는 파일 목록 조회 및 검색 |
read_app_file | data:read | 앱이 저장하는 파일 하나 읽기: 텍스트, 이미지 또는 기타 파일 |
save_transform | data:write | 파생 수치를 보드에 실시간으로 유지하는 사용자 정의 변환 생성 또는 교체 |
delete_transform | data:write | 사용자 정의 변환 영구 삭제 |
알람
| 도구 | 스코프 | 하는 일 |
|---|---|---|
list_alarms | alarms:read | 프로젝트의 알람을 상태, 트리거, 수신자와 함께 목록 조회 |
create_alarm | alarms:write | 앱의 데이터 테이블을 감시하는 알람 생성 |
update_alarm | alarms:write | 알람의 트리거나 수신자 변경, 또는 일시 중지 및 재개 |
delete_alarm | alarms:write | 알람과 그 기록을 영구 삭제 |
로그 및 감사 로그
| 도구 | 스코프 | 하는 일 |
|---|---|---|
get_app_logs | logs:read | 앱이 실행되는 디바이스에서 앱 자체의 로그 출력 읽기 |
get_device_logs | logs:read | 디바이스 자체가 해 온 일 읽기: 앱, 다운로드, 디스크, 네트워크, 에이전트 업데이트 |
query_audit_log | logs:read | 감사 로그에서 읽기 전용 쿼리 하나 실행: 누가 언제 프로젝트, 디바이스, 그룹, 앱을 변경했는지 |
get_appliance_health | devices:read | 어플라이언스 전용: 어플라이언스 자체의 플랫폼 서비스, 디스크, 메모리, 라이선스, 업데이트 상태 확인 |
get_appliance_logs | logs:read | 어플라이언스 전용: 어플라이언스 플랫폼의 한 부분의 로그 읽기 |
앱 도구
앱은 AI 에이전트와 함께 자체 도구를 제공합니다. 이는 디바이스에서 실행되는 앱의 기능으로, 예를 들어 기계의 상태를 읽거나 설정을 변경합니다. 두 개의 도구로 이에 접근합니다.
| 도구 | 스코프 | 하는 일 |
|---|---|---|
list_app_tools | apptools:call | 설치된 앱의 도구를 인수 및 앱 에이전트의 지침과 함께 목록 조회 |
call_app_tool | apptools:call | 그중 하나를 프로젝트의 디바이스 하나에서 실행 |
call_app_tool은 디바이스에서 실행되며, 앱의 도구는 그곳에서 무언가를 변경할 수 있습니다. 디바이스는 키 소유자가 볼 수 있는 프로젝트의 디바이스여야 하며, 소유자는 보드에서 앱을 조작할 때와 마찬가지로 앱의 데이터를 사용할 권한이 있어야 합니다. 앱은 주어진 인수만 정확히 받으며 그 밖의 것은 받지 않습니다. 앱의 개발 버전이 아니라 설치된 릴리스의 도구만 나열됩니다. 도구의 텍스트는 앱 개발자가 작성하며 정해진 길이로 잘립니다.
스코프
각 도구에는 위 표에 표시된 하나의 스코프가 필요합니다. 서버는 클라이언트에 키가 사용할 수 있는 도구만 제공하며, 그 밖의 도구는 존재하지 않는 것처럼 거부합니다. 키가 무엇을 허용하든, 도구는 키 소유자가 IronFlock에서 할 수 있는 일 이상을 하지 않습니다. releases:publish에는 도구가 없습니다. 이 스코프는 릴리스를 빌드하는 REST 작업을 위한 것입니다. 모든 스코프는 스코프를, Studio에서 스코프를 선택하는 방법은 API 키 생성을 참조하십시오.
프로젝트로 제한된 키는 해당 프로젝트만 봅니다. 하나의 앱으로 제한된 키에는 앱에 대해 동작하는 도구만 제공되므로 list_projects는 제공되지 않습니다. 두 경우 모두 하나의 프로젝트를 넘어서는 도구는 제공되지 않습니다. 쿼리가 소유자가 읽을 수 있는 모든 프로젝트의 자산을 지정할 수 있는 query_audit_log, 어떤 프로젝트에도 속하지 않는 두 어플라이언스 도구, 그리고 모든 사용자를 위해 어플라이언스의 스토어를 변경하는 sync_app_to_store가 그렇습니다.
일부 도구에는 추가 규칙이 있습니다:
install_app은 사용자에게 보여 준get_install_quote의 응답을 받으며, 그 견적의 가격이나 다른 내용이 그 사이에 바뀌었으면 아무것도 설치하지 않습니다. 유료 앱을 설치하면 비용이 발생합니다.set_app_state와update_app은 한 번의 호출로 최대 10개의 디바이스를 변경합니다.create_device는 새 디바이스의 키와 이름을 응답하며, 디바이스의 자격 증명을 담은 구성 파일은 절대 응답하지 않습니다. 파일은 Studio의 디바이스 설정에서 유지보수 > 디바이스 구성 파일 > 구성 파일 다운로드로 다운로드하거나, 머신에서ironflock agent install --project <project> --name <name>으로 디바이스를 설정하십시오. 이 명령은 디바이스를 생성하고 파일을 머신에 보관합니다(로그인 및 디바이스 관리).- 프로젝트는 한 번에 하나의 사용자 정의 변환만 저장합니다. 첫 번째
save_transform이 실행되는 동안의 두 번째 호출은 거부됩니다. - 계정은
query_audit_log를 한 번에 하나씩, 1분에 여섯 번까지 실행할 수 있습니다. 그 뒤의 데이터베이스가 공유되기 때문입니다. - 호출 시간 안에 끝나지 않은 변경도 이루어질 수 있습니다. 결과에 그렇게 나오며, 도구는 변경을 반복하지 않습니다.
결과
결과는 JSON이며, 구조화된 콘텐츠와 텍스트 블록 안의 같은 JSON으로 제공됩니다. 긴 목록은 50,000자에 맞게 잘리며, cut 멤버가 몇 개의 항목이 빠졌는지와 이어서 읽는 방법을 알려 줍니다. 이미지(PNG, JPEG, GIF, WebP)는 이미지로, PDF 같은 기타 파일은 미디어 유형이 포함된 임베디드 리소스로 제공됩니다.
도구가 요청받은 일을 할 수 없으면 결과가 오류로 표시되며, 예를 들어 프로젝트가 존재하지 않는다거나 플랫폼이 제때 응답하지 않았다는 이유를 한 문장으로 설명합니다.
한도
API 키마다 적용되는 기본값입니다:
| 한도 | |
|---|---|
| 요청 | 분당 120개, 최대 30개까지 버스트 |
| 동시에 열린 요청 | 8개 |
| 요청 본문 | 1,114,112바이트: 1 MiB의 인수와 이를 둘러싼 메시지 |
| 도구 호출 1회 | 90초 |
| 데이터베이스 쿼리 | 30초. execute_sql은 더 요청하지 않으면 100행을 응답하며, 최대 1,000행 |
| 결과 1개 | 50,000자. call_app_tool의 결과는 45,000자에서 잘림 |
오류
| 응답 | 의미 | 해결 방법 |
|---|---|---|
401 | 키가 없거나, 잘못 입력되었거나 잘렸거나, 삭제되었거나, 만료되었거나, 다른 IronFlock의 키입니다. 커넥터에서는 Bearer 가 빠졌을 수 있습니다 | 연결하려는 IronFlock의 Studio에서 새 키를 생성하고 다시 입력하십시오 |
/mcp에서 404 | 주소에 /mcp가 두 번 들어 있거나, IronFlock API 서비스를 실행하지 않는 어플라이언스처럼 인스턴스가 아직 엔드포인트를 제공하지 않습니다 | 주소를 수정하십시오. 그렇지 않으면 클라우드를 사용하십시오 |
405 | /mcp에 대한 GET 및 DELETE: 서버에는 이벤트 스트림도, 종료할 세션도 없습니다 | POST를 사용하십시오 |
413 | 요청 본문이 너무 큽니다 | 한 번의 호출에서 보내는 양을 줄이십시오 |
429 | 키가 너무 많은 요청을 보냈거나, 동시에 열린 요청이 너무 많습니다. Retry-After 헤더에 기다려야 할 초가 나옵니다 | 그만큼 기다린 다음, 동시 호출 수를 줄여 계속하십시오 |
503 | 플랫폼을 현재 사용할 수 없거나, 서비스가 종료 중입니다 | 1분 후에 다시 시도하십시오 |
504 | 플랫폼이 제때 응답하지 않았습니다 | 1분 후에 다시 시도하십시오 |
요청받은 일을 할 수 없는 도구는 HTTP 오류로 응답하지 않습니다. 그 결과가 오류로 표시되며 무엇이 잘못되었는지 한 문장으로 설명합니다.
키를 안전하게 보관하기
- 채팅에 키를 절대 붙여 넣지 마십시오. 붙여 넣었다면 키는 그 대화의 일부가 됩니다. Studio에서 키를 삭제하고, 새 키를 생성하여 설정에 입력하십시오.
- Studio는 새 키를 생성할 때 한 번만 표시합니다. 바로 클라이언트의 설정에 저장하십시오.
- 키를 사용하는 곳마다 키를 하나씩 사용하여 다른 키에 영향을 주지 않고 하나를 삭제할 수 있도록 하고, 더 이상 사용하지 않는 키는 삭제하십시오. 키는 1년 동안 유효합니다.
- 키에는 Claude에게 필요한 스코프와 프로젝트만 부여하십시오. 내 모든 프로젝트에서 모두를 할 수 있는 키는 Claude가 IronFlock에서 사용자가 할 수 있는 모든 일을 하게 합니다. 무언가를 변경하거나 삭제하는 도구에는 그렇다는 표시가 있어, Claude 같은 클라이언트가 먼저 사용자에게 물어볼 수 있습니다. 동의하기 전에 Claude가 무엇을 변경하려는지 읽어 보십시오.
- 조직이 공유하는 커넥터는 모든 사용자에 대해 하나의 키로 동작합니다. 모든 사용자가 볼 수 있는 것만 볼 수 있는 계정의 키를 사용하십시오.