Skip to Content
IoT 앱 개발IronFlock APIMCP 엔드포인트

MCP 엔드포인트

IronFlock은 MCP 서버입니다. Claude를 비롯해 Model Context Protocol을 지원하는 모든 클라이언트는 API 키가 허용하는 범위 안에서 IronFlock이 제공하는 도구로 프로젝트 목록을 조회하고, 프로젝트의 디바이스, 앱, 데이터를 읽고, 이에 대해 작업할 수 있습니다. 이 엔드포인트는 REST API와 같은 API 서비스의 일부이며, 같은 API 키를 사용합니다.

주소 및 인증

IronFlock 클라우드의 URLhttps://api.ironflock.com/mcp
어플라이언스의 URLhttps://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 탭에서 작동합니다.

  1. Claude Code 세션에서 마켓플레이스를 추가하고 플러그인을 설치합니다:

    /plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock
  2. 설치하면 두 가지 설정이 있는 대화 상자가 열립니다. IronFlock API address는 클라우드의 경우 https://api.ironflock.com이고, 어플라이언스의 경우 https://api. 뒤에 어플라이언스의 도메인을 붙인 주소입니다. 두 경우 모두 /mcp와 끝의 슬래시를 붙이지 않습니다. IronFlock API key는 Studio에서 받은 키입니다. Claude Code는 이 키를 설정 파일이 아니라 시스템의 보안 자격 증명 저장소에 보관합니다.

  3. 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는 작동합니다.

  1. Customize > Connectors를 열고 Add를 선택한 다음 Add custom connector를 선택합니다.
  2. 이름 IronFlock과 서버 URL https://api.ironflock.com/mcp를 입력합니다.
  3. Authentication을 No sign-in으로 설정합니다.
  4. Request headers에서 헤더 Authorization을 추가하고, 값으로 Bearer 뒤에 키를 입력합니다. 즉 Bearer라는 단어, 공백 하나, 그리고 키입니다. Bearer 가 없으면 IronFlock이 요청을 거부합니다.
  5. 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_projectsdevices:read키로 작업할 수 있는 프로젝트 목록 조회

디바이스

도구스코프하는 일
list_devicesdevices:read프로젝트의 디바이스, 각 디바이스에 설치된 앱, 앱의 실행 여부, 디바이스의 온라인 여부 목록 조회
create_devicedevices:write프로젝트에 디바이스를 생성하고 그 키와 이름을 응답
delete_devicedevices:write프로젝트에서 디바이스를 영구 삭제

프로젝트의 앱

도구스코프하는 일
list_project_appsapps:read프로젝트에 설치된 앱과 각 앱이 실행 중인 디바이스 수 목록 조회
check_app_statusapps:read앱이 디바이스에서 실행 중인지, 데이터가 들어오는지 표시
install_appapps:write스토어 앱을 프로젝트에, 선택적으로 디바이스에도 설치
set_app_stateapps:write설치된 앱을 디바이스에서 시작하거나 중지
update_appapps:write설치된 앱을 최신 릴리스로 업데이트
uninstall_appapps:write디바이스 또는 프로젝트 전체에서 앱 제거

App Store 및 비용

도구스코프하는 일
search_appsapps:read기능으로 App Store를 검색하고 일치하는 앱을 가격과 함께 반환
get_app_detailsapps:read스토어 앱 1~3개의 설명, README, 가격 읽기
get_install_quoteapps:read앱 설치에 드는 비용과 설치를 막는 요인 조회
estimate_project_costapps:read프로젝트 구성의 연간 비용 추정. 구매는 이루어지지 않음
sync_app_to_storeapps:write어플라이언스 전용: IronFlock 클라우드 스토어의 앱을 어플라이언스 자체 스토어로 복사

데이터

도구스코프하는 일
get_schemadata:read프로젝트 데이터베이스의 테이블, 뷰, 컬럼 설명
execute_sqldata:read프로젝트 데이터베이스에서 읽기 전용 SELECT 쿼리 하나 실행
list_dashboardsdata:read프로젝트의 대시보드 목록 조회
list_app_filesdata:read앱이 프로젝트에 저장하는 파일 목록 조회 및 검색
read_app_filedata:read앱이 저장하는 파일 하나 읽기: 텍스트, 이미지 또는 기타 파일
save_transformdata:write파생 수치를 보드에 실시간으로 유지하는 사용자 정의 변환 생성 또는 교체
delete_transformdata:write사용자 정의 변환 영구 삭제

알람

도구스코프하는 일
list_alarmsalarms:read프로젝트의 알람을 상태, 트리거, 수신자와 함께 목록 조회
create_alarmalarms:write앱의 데이터 테이블을 감시하는 알람 생성
update_alarmalarms:write알람의 트리거나 수신자 변경, 또는 일시 중지 및 재개
delete_alarmalarms:write알람과 그 기록을 영구 삭제

로그 및 감사 로그

도구스코프하는 일
get_app_logslogs:read앱이 실행되는 디바이스에서 앱 자체의 로그 출력 읽기
get_device_logslogs:read디바이스 자체가 해 온 일 읽기: 앱, 다운로드, 디스크, 네트워크, 에이전트 업데이트
query_audit_loglogs:read감사 로그에서 읽기 전용 쿼리 하나 실행: 누가 언제 프로젝트, 디바이스, 그룹, 앱을 변경했는지
get_appliance_healthdevices:read어플라이언스 전용: 어플라이언스 자체의 플랫폼 서비스, 디스크, 메모리, 라이선스, 업데이트 상태 확인
get_appliance_logslogs:read어플라이언스 전용: 어플라이언스 플랫폼의 한 부분의 로그 읽기

앱 도구

앱은 AI 에이전트와 함께 자체 도구를 제공합니다. 이는 디바이스에서 실행되는 앱의 기능으로, 예를 들어 기계의 상태를 읽거나 설정을 변경합니다. 두 개의 도구로 이에 접근합니다.

도구스코프하는 일
list_app_toolsapptools:call설치된 앱의 도구를 인수 및 앱 에이전트의 지침과 함께 목록 조회
call_app_toolapptools: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가 무엇을 변경하려는지 읽어 보십시오.
  • 조직이 공유하는 커넥터는 모든 사용자에 대해 하나의 키로 동작합니다. 모든 사용자가 볼 수 있는 것만 볼 수 있는 계정의 키를 사용하십시오.
Last updated on