API와 MCP

자체 소프트웨어, AI 어시스턴트 또는 터미널에서 Point11을 사용하세요.

개요#

MCP 서버, API, 명령줄 도구로 대시보드에서 하는 일을 똑같이 할 수 있습니다. 캠페인과 결과를 읽고 같은 작업을 시작하세요.

  • MCP 서버: Claude, ChatGPT 또는 다른 AI 어시스턴트를 연결하세요.
  • API: 자체 코드에서 https://point11.ai/api/v1로 Point11을 호출하세요.
  • CLI: 터미널에서 API를 사용하세요.

로그인해 API 레퍼런스를 여세요. Point11 조직의 멤버가 볼 수 있습니다. 모든 요청과 각 요청이 받는 값과 반환하는 값, 그리고 MCP 서버, API, CLI가 실행할 수 있는 대시보드 작업이 나와 있습니다. 광고와 기타 크리에이티브를 고객의 디지털 트윈으로 테스트하려면 API로 크리에이티브 테스트하기를 참고하세요.

AI 어시스턴트 연결하기#

MCP 서버 URL로 https://point11.ai/api/mcp를 사용하세요. 안내에 따라 Point11에 로그인하고 접근을 승인하세요. 여러 조직에 속해 있다면 사용할 조직을 어시스턴트에 알려 주세요. 대신 API 키로 연결하려면 아래에서 사용하는 클라이언트의 단계를 따르세요.

사용하는 제품만 어시스턴트에 제공하려면 API 키로 연결하고 제품 이름을 소문자로, 쉼표로 구분해 URL에 추가하세요. 예: https://point11.ai/api/mcp?products=discovery,inspector. 도구 목록이 짧을수록 어시스턴트가 작업할 여유가 늘어납니다. 로그인하려면 위의 URL을 /api/mcp 뒤에 아무것도 붙이지 말고 그대로 사용하세요. Point11은 각 도구의 현재 버전만 목록에 표시합니다. 이전 버전을 아직 사용하는 어시스턴트도 계속 작동합니다.

Business와 Alpha는 도구가 가장 많으므로 둘 중 하나의 일부 영역만 추가할 수도 있습니다. 제품, 점, 영역 순으로 적습니다. 예: business.customers. Business에는 profiles, customers, crm, goals, products, measurement, google-ads가 있습니다. Alpha에는 chat, projects, files, workflows, ads, brand-kits, advisor, connectors가 있습니다. 제품과 영역은 원하는 대로 섞어 쓸 수 있습니다. 예: https://point11.ai/api/mcp?products=discovery,business.customers. 필요할 때마다 도구를 검색하는 어시스턴트라면 제품 전체나 서버 전체를 계속 사용할 수 있습니다.

레지스트리와 클라이언트는 https://point11.ai/api/mcp/server-card에서 서버 설명을 읽을 수 있습니다.

웹과 데스크톱의 Claude#

  1. Customize > Connectors를 연 다음 + > Add custom connector를 여세요.
  2. 이름을 Point11로 지정하고 https://point11.ai/api/mcp를 정확히 그대로 입력한 후 Add, 이어서 Connect를 선택하세요.
  3. 대화에서 + > Connectors를 열고 Point11을 활성화하세요.

Team 및 Enterprise 요금제에서는 소유자가 먼저 Organization settings > Connectors에서 커넥터를 추가해야 합니다. Claude 커넥터 가이드를 참고하세요.

Claude Code#

터미널에서 다음을 실행하세요.

bash
claude mcp add --transport http point11 https://point11.ai/api/mcp

그런 다음 Claude Code를 열고 /mcp를 실행한 후 Point11을 선택해 인증하세요. 대신 API 키를 사용하려면 헤더로 추가하세요.

bash
claude mcp add --transport http point11 https://point11.ai/api/mcp \
  --header "Authorization: Bearer $POINT11_API_KEY"

Claude Code MCP 가이드를 참고하세요.

웹의 ChatGPT#

  1. Settings > Security and login을 열고 Developer mode를 활성화하세요.
  2. Plugins > +를 여세요. Point11, 간단한 설명, Connection 아래에 서버 URL을 입력한 다음 연결을 만드세요.
  3. 도구를 검토하고 새 대화를 시작한 후 도구 메뉴에서 Point11을 선택하세요.

사용 가능 여부는 계정과 워크스페이스 설정에 따라 달라집니다. OpenAI 연결 가이드를 참고하세요.

ChatGPT 데스크톱과 Codex#

데스크톱 앱에서 Settings > MCP servers > Add server를 여세요. 이름을 Point11로 지정하고 Streamable HTTP를 선택한 후 서버 URL을 입력하세요. 저장하고 Restart, 이어서 Authenticate를 선택하세요.

Codex CLI에서는 다음을 실행하세요.

bash
codex mcp add point11 --url https://point11.ai/api/mcp
codex mcp login point11

대신 API 키를 사용하려면 키가 저장된 환경 변수의 이름을 지정하세요.

bash
codex mcp add point11 --url https://point11.ai/api/mcp --bearer-token-env-var POINT11_API_KEY

데스크톱, CLI, IDE 클라이언트는 컴퓨터의 구성을 공유합니다. OpenAI MCP 가이드를 참고하세요.

어시스턴트에서 대시보드 보기#

Brand share(브랜드 점유율), Brand win rate(브랜드 승률), Competitors(경쟁사) 같은 Discovery 대시보드 뷰를 요청하세요. 대화형 앱을 표시하는 어시스턴트는 대시보드에서 보는 것과 같은 카드를 표시하고, Point11에서 열 수 있는 링크도 함께 제공합니다. 다른 어시스턴트는 같은 수치의 간단한 요약과 링크를 받습니다.

로그인 또는 API 키 사용#

  • 로그인하면 본인으로 사용합니다. Point11이 접근 승인을 요청하고, 이후 어시스턴트나 도구는 사용자가 속한 각 조직에서 사용자의 역할로 작동합니다. AI 어시스턴트와 본인의 작업에 사용하세요.
  • API 키는 스크립트나 예약 작업처럼 사용자 없이 작동하는 소프트웨어에 사용하세요. 키는 한 조직을 대신해 작동하며 부여한 접근 권한만 사용할 수 있습니다.

몇 가지 작업에는 항상 사용자가 필요합니다. 본인의 Alpha 대화와 프로젝트, 댓글, Research 연구 초안은 개인에게 속하므로 API 키로는 접근할 수 없습니다. 캠페인을 일시 중지하거나 삭제하거나, 누군가를 초대하거나, 멤버를 제거하려면 먼저 사용자의 승인이 필요합니다. 승인할 때 조직과 변경될 내용을 정확히 확인할 수 있으며, 승인은 해당 요청에만 적용됩니다. 청구, API 키, 멤버 역할은 대시보드에서만 변경할 수 있습니다.

MCP 서버, API, CLI에서 시작한 작업은 대시보드에서와 똑같이 요금제 사용량에 포함됩니다.

각 어시스턴트가 할 수 있는 작업 선택하기#

사용자를 대신해 작동한 모든 AI 어시스턴트나 앱은 Settings(설정) > Security(보안) 페이지의 Connected apps(연결된 앱) 아래에 표시됩니다. 각 앱이 해당 조직에서 할 수 있는 작업을 Full(전체 권한), Read-only(읽기 전용), Blocked(차단됨) 중에서 선택하세요. 소유자와 관리자는 멤버의 어시스턴트가 조직 전체에서 할 수 있는 작업도 Settings(설정) > Security(보안) > Organization(조직) 페이지의 AI clients (MCP)(AI 클라이언트) 항목에서 Allowed(허용), Read-only(읽기 전용), Off(끔) 중에서 선택하고, Members' connected apps(멤버의 연결된 앱) 아래에서 멤버의 앱 접근 권한을 취소할 수 있습니다. 변경 사항은 다음 요청부터 적용되며 API 키에는 영향을 주지 않습니다.

API 키 만들기#

관리자와 소유자는 키를 만들 수 있습니다.

  1. Settings(설정) > API keys(API 키)를 열고 Create key(키 만들기)를 선택하세요.
  2. Name(이름)을 입력하고, 제품별 Access(접근 권한), 만료 시점인 Expires(만료), 키의 소속인 Belongs to(소속)을 선택하세요.
  3. Create(만들기)를 선택한 다음 키를 복사하세요. 키는 한 번만 표시됩니다.

키는 코드에 넣지 말고 비밀 관리 도구에 보관하세요. 한 조직에는 활성 키를 최대 10개까지 둘 수 있습니다. 키를 중지하려면 Revoke(폐기)를 선택하세요. Rotate(순환)을 선택하면 키에 새 비밀 값이 부여됩니다. Me(나)에 속한 키는 조직을 떠나거나 더 이상 키를 관리할 수 없게 되면 폐기되고, The organization(조직)에 속한 키는 계속 작동합니다.

첫 요청 보내기#

키를 bearer 토큰으로 보내세요.

bash
curl https://point11.ai/api/v1/discovery/campaigns \
  -H "Authorization: Bearer $POINT11_API_KEY"

읽기 요청은 GET을 사용합니다. 무언가를 변경하는 요청은 JSON 본문과 함께 POST를 사용하고, 새 UUID를 담은 Idempotency-Key 헤더를 보냅니다.

bash
curl https://point11.ai/api/v1/inspector/scans/start \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

키 대신 로그인해서 사용한다면 조직 ID를 담은 Point11-Organization도 함께 보내세요. 조직 ID는 Settings(설정) > API keys(API 키)에서 복사하세요.

응답 처리하기#

  • 재시도. 요청을 안전하게 재시도하려면 같은 Idempotency-Key로 다시 보내세요. 생성이나 시작 요청을 재시도하면 첫 번째 응답을 그대로 돌려받으며 두 번 실행되지 않습니다. 그 밖의 변경은 재시도하면 다시 실행되고 그 결과 상태를 응답하므로, 재시도한 삭제가 404를 응답하면 해당 항목은 이미 삭제된 것입니다. 새 요청마다 새 키를 사용하세요. MCP 서버를 통해서는 어시스턴트가 이 키를 idempotencyKey로 보냅니다. 무언가를 생성하거나 시작할 때는 필수이고, 그 밖의 변경에서는 선택 사항이며 키 없이 보낸 요청은 새 요청으로 실행됩니다.
  • 목록. limit는 최대 100까지 전달할 수 있습니다. 다음 페이지를 받으려면 이전 응답의 nextCursor를 cursor로 전달하세요. 마지막 페이지에서는 nextCursor가 null입니다.
  • 오래 걸리는 작업. 스캔이나 캠페인을 시작하면 바로 runId와 함께 202가 반환됩니다. 진행 상황은 GET /api/v1/platform/runs-v2/{runId}로, MCP 서버에서는 platform_runs_get_v2로 확인하세요.
  • 오류. 모든 오류에는 code, message, request_id가 있습니다. code를 보고 대응 방법을 정하고, 도움을 요청할 때 request_id를 함께 알려 주세요.
  • 한도. 각 키에는 요청 한도가 있으며, 로그인하는 각 사용자에게도 사용하는 모든 조직과 어시스턴트를 통틀어 요청 한도가 있습니다. 남은 한도는 RateLimit-Remaining과 RateLimit-Reset 헤더에서 확인할 수 있습니다. 한도를 모두 쓰면 429를 받습니다. Retry-After에 표시된 초만큼 기다린 뒤 다시 시도하세요.

CLI 사용하기#

CLI는 Restish입니다. Restish는 API 레퍼런스를 읽고 각 요청을 discovery-campaigns-list처럼 요청 이름을 딴 명령으로 바꿉니다. Restish는 API 키를 사용합니다. brew install restish 등으로 Restish를 설치하고 키를 POINT11_API_KEY에 넣은 다음 Restish를 Point11에 연결하세요.

bash
restish api connect p11 https://point11.ai --no-discover
restish api set p11 'profiles.default.auth: {type: bearer, params: {token: env:POINT11_API_KEY}}'
restish api set p11 'profiles.default.credentials.apiKey.auth: {type: bearer, params: {token: env:POINT11_API_KEY}}'
restish api sync p11

그런 다음 명령 이름으로 원하는 요청을 실행하세요.

bash
restish p11 discovery-campaigns-list

무언가를 변경하는 요청에서는 Idempotency-Key를 먼저 입력하세요.

bash
restish p11 inspector-scans-start "$(uuidgen)" url: https://example.com

새 요청을 가져오려면 restish api sync p11을 다시 실행하세요.