Agent Integration

Agent Integration을 켜면 Piko에서 만든 앱의 기능을 ChatGPT, Claude 같은 AI에서 도구로 사용할 수 있습니다. 예를 들어 예약 가능한 시간을 찾고, 고객 목록을 조회하고, 주문 상태를 바꾸는 작업을 AI 대화에서 실행할 수 있습니다.

Piko가 앱의 API를 분석해 원격 MCP 서버를 자동으로 만들기 때문에 별도의 서버를 직접 개발할 필요가 없습니다.

시작하기 전에

앱 소유자만 Agent Integration을 설정할 수 있습니다.
앱이 공개 상태로 게시되어 있어야 합니다.
AI에서 사용할 기능은 앱에 /api/* API로 구현되어 있어야 합니다.
이 기능이 추가되기 전에 만든 앱도 설정을 처음 열면 저장된 소스에서 최초 도구 목록을 자동으로 만듭니다.

1. 앱 게시하기

작업 화면에서 앱을 공개 상태로 게시합니다. 게시가 성공하면 Piko가 앱의 API 경로를 분석하고 AI에 제공할 도구 후보를 만듭니다.

로그인, OAuth, 웹훅, 상태 확인용 API는 자동으로 제외합니다. 조회 도구는 로그인 사용자 권한으로 제안하고, 데이터를 바꾸는 도구는 기본으로 꺼 둡니다. 삭제·일괄 삭제·초기화·취소처럼 결과를 되돌리기 어렵거나 관리자·내보내기·백업처럼 민감한 도구는 높은 위험으로 표시합니다.

2. 도구와 권한 설정하기

프로젝트 화면에서 설정 → Agent Integration을 엽니다.

AI에 노출할 도구만 켭니다.
도구 이름과 설명이 AI가 이해하기 쉬운지 확인합니다.
각 도구의 접근 권한을 선택합니다.
화면 위쪽의 Agent Integration 스위치를 켭니다.
설정 저장을 누릅니다.

접근 권한	누가 사용할 수 있나요
모든 사용자	Piko 로그인 없이 사용
로그인 사용자	Piko 계정으로 승인하고 현재 앱에 접근할 수 있는 사용자만 사용
유료 사용자	현재 활성 유료 플랜이 있는 Piko 사용자만 사용. 결제 상태를 실행 시 다시 확인

기본 권한은 다음 게시에서 새로 발견되는 안전한 도구에 적용됩니다. 이미 설정한 도구의 활성 상태, 권한, 이름, 설명은 앱을 다시 게시해도 유지됩니다.

데이터를 변경하거나 외부로 전송하는 도구를 처음 켜면 위험 내용을 확인하는 창이 나타납니다. 높은 위험 도구는 로그인 없이 공개할 수 없고 앱 소유자 또는 편집자만 실행할 수 있습니다. 관리자 API는 Agent 연결 여부만으로 통과하지 않고 앱 역할까지 확인합니다.

게시할 때 실행되는 보안 검사

Piko는 앱을 게시할 때마다 Agent Integration 전용 검사를 함께 실행합니다.

로그인·토큰·비밀번호·웹훅 경로를 도구 후보에서 제외합니다.
관리자·내부·내보내기 경로와 삭제·초기화·환불 같은 작업을 탐지합니다.
조회가 아닌 작업은 기본 비활성화하고 직접 확인한 뒤에만 켤 수 있게 합니다.
높은 위험 도구의 공개 권한 저장을 서버에서도 차단합니다.
도구 응답은 최대 1MB까지만 읽고 초과하면 즉시 중단합니다.

3. MCP URL 복사하기

같은 설정 화면의 MCP 서버 URL에서 복사를 누릅니다. 주소는 일반적으로 다음 형태입니다.

https://내-앱-주소/mcp

프로젝트 편집 주소가 아니라 설정 화면에 표시된 MCP 서버 URL을 그대로 사용해야 합니다.

4. Claude에 연결하기

Claude의 원격 MCP 커스텀 커넥터를 사용할 수 있는 플랜에서 다음 순서로 연결합니다.

Claude에서 Settings → Connectors를 엽니다.
Add custom connector를 선택합니다.
Piko에서 복사한 MCP 서버 URL을 붙여넣고 추가합니다.
로그인이 필요한 도구가 있으면 Connect를 누르고 Piko 계정으로 승인합니다.
대화의 도구 메뉴에서 연결한 커넥터와 필요한 도구를 켭니다.

Claude의 플랜별 지원 범위와 최신 화면은 Anthropic의 커스텀 커넥터 안내에서 확인할 수 있습니다.

5. ChatGPT에 연결하기

ChatGPT의 커스텀 MCP 앱 또는 개발자 모드를 사용할 수 있는 플랜과 워크스페이스에서 연결합니다.

ChatGPT 설정에서 Apps 또는 워크스페이스의 Apps → Create를 엽니다.
필요한 경우 Developer mode를 켭니다.
새 커스텀 앱의 MCP 서버 주소에 Piko에서 복사한 URL을 입력합니다.
앱을 연결하고 Piko 권한 승인 화면이 나오면 내용을 확인해 승인합니다.
대화에서 해당 앱을 선택하고 도구를 사용합니다.

ChatGPT는 플랜과 워크스페이스 권한에 따라 관리자 승인이 필요하고, 읽기·쓰기 도구의 지원 범위가 다를 수 있습니다. 최신 조건과 메뉴는 OpenAI의 개발자 모드 및 MCP 앱 안내를 확인하세요.

연결 확인하기

AI와 새 대화를 열고 다음처럼 요청합니다.

이 앱에서 사용할 수 있는 도구를 알려줘.

도구가 보이면 먼저 조회 작업을 실행해 결과를 확인합니다. 데이터를 바꾸는 작업은 AI가 보여 주는 도구 이름과 입력값을 검토한 뒤 승인하세요.

다시 게시하면 어떻게 되나요?

앱을 다시 게시할 때 Piko가 API를 다시 분석합니다.

새 API는 새 도구 후보로 추가됩니다.
사라진 API는 도구 목록에서 제거됩니다.
기존 도구에서 직접 바꾼 활성 상태, 권한, 이름, 설명은 유지됩니다.
새로 발견된 안전한 조회 도구의 초기 권한은 설정한 기본 권한을 따릅니다. 쓰기 도구는 로그인 권한·비활성 상태로 추가됩니다.

AI 클라이언트가 이전 도구 목록을 보관하고 있다면 클라이언트의 앱 또는 커넥터 설정에서 도구를 새로고침하거나 다시 연결해야 할 수 있습니다.

문제 해결

증상	확인할 내용
Agent Integration을 켤 수 없음	앱이 공개 상태인지, 발견된 도구가 한 개 이상인지 확인합니다.
도구 목록이 비어 있음	설정을 다시 열어 초기 동기화를 확인하고, 앱에 리터럴 `/api/*` 경로로 구현된 기능이 있는지 확인합니다. 소스를 최근 수정했다면 앱을 다시 게시합니다.
원하는 API가 보이지 않음	로그인·OAuth·웹훅·상태 확인용 경로는 제외됩니다. 민감하거나 위험한 도구는 목록에 있어도 기본으로 꺼져 있을 수 있습니다.
AI에서 로그인 또는 권한 오류가 남	도구에 설정한 접근 권한에 맞는 Piko 계정으로 다시 연결합니다. 계정·유료 상태와 앱 접근 권한은 호출할 때마다 확인하며, 고위험 도구는 소유자·편집자만 실행할 수 있습니다.
앱을 수정했는데 AI의 도구가 그대로임	앱을 다시 게시한 뒤 AI 클라이언트에서 앱 또는 커넥터의 도구 목록을 새로고침합니다.
도구 호출은 되지만 앱에서 거부함	앱의 로그인·권한 규칙이 요청을 허용하는지 확인하고, 필요하면 Piko 채팅에서 해당 API의 Agent Integration 지원을 요청합니다.

문제가 계속되면 프로젝트의 설정 → 오류에서 실행 오류를 확인하고, 앱 주소와 실패한 도구 이름을 함께 전달해 주세요.

연결 해제하기

연결을 즉시 중단하려면 Piko의 설정 → Agent Integration에서 전체 스위치를 끄고 저장합니다. 특정 작업만 막으려면 해당 도구만 끌 수 있습니다. Claude나 ChatGPT에 저장된 연결도 각 서비스의 Apps 또는 Connectors 설정에서 삭제할 수 있습니다.