AI 에이전트를 listingsAPI MCP에 연결

Claude, ChatGPT, Cursor 또는 Gemini를 호스팅된 MCP 서버에 연결하면 어시스턴트가 사업장, 등록 정보, 리뷰를 읽고 사용자가 직접 호출하는 것과 동일한 도구로 관련 작업을 수행할 수 있습니다.

Listings API는 https://listingsapi.com/mcp에서 Model Context Protocol(MCP) 서버를 호스팅합니다. 설치하거나 실행할 것은 없습니다. MCP를 지원하는 AI 어시스턴트는 해당 URL에 연결하여 REST 엔드포인트별 도구 1개와 몇 가지 문서 도구를 검색하고, 계정에서 해당 도구를 호출합니다. 이 가이드에서는 주요 클라이언트를 각각 연결한 다음 연결을 확인하는 방법을 설명합니다.

1. 에이전트에 제공되는 기능 확인하기

서버는 60개가 조금 넘는 도구를 제공하며, 그중 약 3분의 2는 읽기 전용입니다. 이름은 REST 리소스를 따르므로 locations_search, listings_premium, reviews_respond, posts_create_social은 해당 엔드포인트와 동일한 매개변수와 응답 구조를 사용하여 동일한 작업을 수행합니다. 어시스턴트는 문서 도구 3개인 search_docs, get_doc, get_endpoint을 사용하여 페이로드 구조를 추측하는 대신 페이지나 엔드포인트 명세를 조회할 수 있습니다.

도구 유형	예시	필요한 권한
사업장	`locations_all`, `locations_search`, `locations_create`, `locations_update`	조회에는 Read, 생성 및 수정에는 Write
등록 정보	`listings_premium`, `listings_duplicates`, `listings_mark_duplicate`	Read, 중복 표시에는 Write
연결된 계정	`connected_accounts_list`, `connected_accounts_listings`, `connected_accounts_connect_listing`	Read, 연결 및 가져오기에는 Write
리뷰	`reviews_list`, `reviews_get`, `reviews_respond`, `reviews_analytics`	Read, 답글 작성에는 Write
게시물	`posts_social_post_view`, `posts_create_social`	Read, 게시에는 Write
분석	`analytics_google`, `analytics_facebook`, `analytics_bing`	Read
계정	`whoami`, `get_usage`, `get_subscription`, `recent_errors`	Read
문서	`search_docs`, `get_doc`, `get_endpoint`, `list_endpoints`	없음

게시물 삭제나 사업장 보관 처리와 같은 파괴적 작업은 도구로 제공하지 않습니다. 어시스턴트가 스스로 데이터를 삭제할 수 없도록 이러한 작업에는 REST API나 SDK를 사용하세요.

2. 클라이언트 로그인 방식 선택하기

모든 클라이언트는 2가지 방식 중 하나로 인증합니다. 두 방식 모두 서버에서는 동일한 API 키 방식으로 처리되므로 요청 빈도 제한과 사용량 보고도 동일합니다.

방식	붙여넣을 내용	적합한 용도
API 키 헤더	`Authorization: API <your key>`을 정적 헤더로 사용	설정 파일을 직접 관리하는 CLI 및 편집기
OAuth 2.0	없습니다. 클라이언트가 브라우저를 열면 로그인하고 `read` 또는 `read write`을 승인합니다	Claude 및 ChatGPT와 같은 호스팅형 어시스턴트 또는 키 원문을 보유해서는 안 되는 사용자

OAuth는 PKCE를 적용한 인증 코드 흐름과 동적 클라이언트 등록을 사용하므로 클라이언트에 미리 발급된 자격 증명이 필요하지 않습니다. 메타데이터는 https://listingsapi.com/.well-known/oauth-authorization-server에 있습니다. 범위는 read과 write이며, 범위를 요청하지 않는 클라이언트에는 read이 부여됩니다. 승인할 때마다 해당 연결 전용 키가 생성되며, 다른 키와 마찬가지로 /dashboard/keys에서 폐기할 수 있습니다.

3. Claude 연결하기

Claude.ai 및 Claude Desktop. 서버가 커넥터 디렉터리에 등록되어 있으므로 가장 빠른 방법은 https://claude.ai/directory/listings-api을 열고 Connect(연결)를 클릭하는 것입니다. Claude가 OAuth 흐름을 실행하고 범위를 승인하면, + 버튼을 누른 다음 Connectors(커넥터)에서 커넥터를 활성화한 모든 채팅에서 도구를 사용할 수 있습니다.

URL로 추가하려면 Customize(사용자 지정)에서 Connectors(커넥터)로 이동하여 +와 Add custom connector(사용자 지정 커넥터 추가)를 클릭하고, https://listingsapi.com/mcp을 붙여넣은 다음 Add(추가)를 클릭하세요. 서버가 Claude를 클라이언트로 자동 등록하므로 Advanced settings(고급 설정)는 비워 두세요. Team 및 Enterprise 요금제에서는 소유자가 Organization settings(조직 설정)의 Connectors(커넥터)에서 커넥터를 추가한 다음, 구성원이 해당 커넥터의 Connect(연결)를 클릭합니다. Claude는 로컬 컴퓨터가 아닌 Anthropic 서버에서 연결하므로 호스팅된 URL이 중요합니다.

Claude Code. 명령어 1개로 키를 사용하여 서버를 추가합니다:

Claude Code

claude mcp add --transport http listingsapi https://listingsapi.com/mcp \--header "Authorization: API $LISTINGSAPI_KEY"

대신 브라우저로 로그인하려면 --header 플래그를 빼고 Claude Code 내에서 /mcp을 실행하세요. --scope project을 사용하여 팀 전체가 공유하는 .mcp.json에 서버 설정을 커밋하되, 키를 함께 커밋하지 마세요.

4. ChatGPT 연결

ChatGPT는 Developer mode(개발자 모드)를 켜면 사용자 지정 커넥터로 원격 MCP 서버에 연결합니다. 이 기능은 Plus, Pro, Business, Enterprise 및 Edu 요금제에서 사용할 수 있으며, 무료 요금제에서는 사용할 수 없습니다.

프로필 메뉴에서 Settings(설정)를 열고 Developer mode(개발자 모드)를 켜세요. 빌드에 따라 Apps & Connectors(앱 및 커넥터) 또는 Security and login(보안 및 로그인) 아래에 있습니다.
커넥터 페이지(현재 빌드에서는 Plugins(플러그인)로 표시됨)에서 + 또는 Create(만들기)를 클릭하세요.
이름을 입력하고, 서버 URL로 https://listingsapi.com/mcp을 붙여넣고, 인증 방식으로 OAuth를 선택하세요. 저장하세요.
ChatGPT가 로그인 페이지를 엽니다. read 또는 read write을 승인하세요.
새 채팅에서 도구 메뉴를 열고 커넥터를 선택한 다음, 커넥터와 해당 도구가 표시되는지 확인하세요. 쓰기 도구를 실행하려면 확인 프롬프트에서 승인을 거쳐야 합니다.

Codex CLI. OpenAI의 터미널 에이전트는 ~/.codex/config.toml에서 MCP 서버 정보를 읽습니다. Codex는 HTTP 서버에 대해 OAuth를 자동으로 시작하고 서버가 알린 범위를 따르므로, 헤더 줄은 선택 사항입니다:

~/.codex/config.toml

[mcp_servers.listingsapi]url = "https://listingsapi.com/mcp"http_headers = { "Authorization" = "API <your key>" }

5. Cursor 연결

/dashboard/mcp의 대시보드 페이지에는 Add to Cursor(Cursor에 추가) 버튼이 있습니다. 이 버튼은 서버 URL과 키가 미리 입력된 Cursor 설치 링크를 열므로, 한 번 클릭하면 설정이 완료됩니다.

수동으로 구성하려면 모든 프로젝트에 적용할 서버를 ~/.cursor/mcp.json에 추가하거나, 한 저장소 안의 .cursor/mcp.json에 서버를 추가하세요:

~/.cursor/mcp.json

{"mcpServers": {  "listingsapi": {    "url": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    }  }}}

대신 OAuth로 로그인하려면 headers 블록을 제거하세요. Cursor는 Settings(설정)의 MCP 아래에 있는 서버 항목에 Connect(연결) 버튼을 표시하고 브라우저에서 인증 절차를 엽니다. 프로젝트 수준의 .cursor/mcp.json에 키를 넣어 커밋하지 마세요. 공유 저장소에서는 전역 파일이나 OAuth를 사용하세요.

6. Gemini 연결

Gemini CLI. Google의 터미널 에이전트는 ~/.gemini/settings.json(또는 프로젝트 내 .gemini/settings.json)에서 원격 서버 설정을 읽습니다. Streamable HTTP 전송 방식을 선택하도록 url이 아닌 httpUrl을 사용하세요:

~/.gemini/settings.json

{"mcpServers": {  "listingsapi": {    "httpUrl": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    },    "timeout": 30000  }}}

OAuth를 사용하려면 headers 블록을 "oauth": { "enabled": true }로 바꾸고, CLI를 시작한 다음 /mcp auth listingsapi을 실행하세요. 언제든지 /mcp을 실행하면 서버, 연결 상태 및 발견된 도구를 확인할 수 있습니다.

Gemini 앱. 일반 사용자용 Gemini 앱에는 사용자 지정 커넥터 설정이 없습니다. Gemini Enterprise Business 에디션의 팀 관리자는 사용자 지정 MCP 서버를 사용할 수 있습니다. business.gemini.google에서 로그인하고 Settings & help(설정 및 도움말), Manage team(팀 관리), Connected apps(연결된 앱)를 차례로 연 다음 Add MCP Server(MCP 서버 추가)를 클릭하세요. URL로 https://listingsapi.com/mcp을 붙여넣으세요. 양식에는 OAuth 정보를 입력해야 합니다. 인가 URL은 https://listingsapi.com/oauth/authorize, 토큰 URL은 https://listingsapi.com/oauth/token, 범위는 read write입니다. 클라이언트 ID와 클라이언트 시크릿도 입력해야 합니다. 이 서버는 시크릿이 없는 공개 PKCE 클라이언트를 발급하므로, 양식에 표시된 리디렉션 URL로 클라이언트를 등록하고 양식에서 허용하는 경우 시크릿을 비워 두세요:

curl -s https://listingsapi.com/oauth/register \-H "Content-Type: application/json" \-d '{  "client_name": "Gemini Business",  "redirect_uris": ["<redirect URL shown in the Gemini form>"],  "grant_types": ["authorization_code", "refresh_token"],  "token_endpoint_auth_method": "none"}'

응답에는 client_id이 포함됩니다. Gemini 양식에서 시크릿을 필수로 요구하면 위의 Gemini CLI 방식을 사용하거나 Gemini API로 구현하세요.

Gemini API로 개발하기. Gemini API SDK는 MCP 클라이언트 세션을 도구로 받으므로, 스크립트에서 Gemini 모델에 동일한 도구를 제공할 수 있습니다:

gemini_agent.py

import asyncio, osfrom google import genaifrom mcp import ClientSessionfrom mcp.client.streamable_http import streamablehttp_client HEADERS = {"Authorization": "API " + os.environ["LISTINGSAPI_KEY"]} async def main():  gemini = genai.Client()  async with streamablehttp_client("https://listingsapi.com/mcp", headers=HEADERS) as (r, w, _):      async with ClientSession(r, w) as session:          await session.initialize()          reply = await gemini.aio.models.generate_content(              model="gemini-2.5-pro",              contents="Which of my locations have a Google listing that is not live yet?",              config=genai.types.GenerateContentConfig(tools=[session]),          )          print(reply.text) asyncio.run(main())

7. 연결 확인

어시스턴트에 작업을 맡기기 전에 서버가 직접 응답하는지 확인하세요. 도구 검색에는 키가 필요하지 않으므로, URL에 접근할 수 있는 클라이언트라면 이 호출이 성공합니다:

List the tools

curl -s https://listingsapi.com/mcp \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

그런 다음 어시스턴트에서 계정에 실제로 접근해야 처리할 수 있는 작업을 요청하세요:

listingsapi 도구를 사용해 내 요금제를 보여 주고, 내 사업장 수를 집계하고, 이번 달 내 API 사용량을 알려 주세요.

연결이 정상적으로 작동하면 whoami에서 요금제와 접근 상태를, locations_all에서 사업장 데이터를, get_usage에서 사용 횟수를 반환합니다. 키가 잘못되었거나 만료된 경우 도구 검색 시점이 아니라 첫 번째 도구 호출 시점에 Unauthenticated 오류가 반환됩니다.

연결이 작동하면 먼저 시도해 볼 프롬프트입니다:

"등록 정보 오류가 있는 내 사업장 목록을 보여 주고 각 오류를 요약해 주세요."
"지난 7일 동안 받은 리뷰 중 답글이 없는 리뷰를 보여 주고 각 리뷰에 대한 답글 초안을 작성해 주세요. 아직 보내지는 마세요."
"사업장 1800289의 지난 2개월간 Google 프로필 분석 데이터를 월별로 비교해 주세요."
"create-location 엔드포인트 명세를 읽은 다음 이 사업장을 추가해 주세요: ..."

listingsAPI 에이전트 스킬 추가

스킬은 작업이 일치할 때 에이전트가 불러오는 지침으로, 에이전트가 작업 절차를 직접 만드는 대신 검증된 절차를 따르게 합니다. 스킬은 MCP 서버와 함께 작동합니다. 서버는 호출을 실행하고, 스킬은 어떤 호출을 어떤 순서로 실행할지 결정합니다. 공개 listingsapi-mcp 저장소의 listingsAPI 스킬 5개가 skills.sh에 게시되어 있습니다:

스킬	기능
`listingsapi-integration`	REST 또는 SDK 코드로 애플리케이션에 Listings API를 추가합니다. 인증, 첫 조회, 사업장, 게시 플랫폼 연결 및 동기화 상태를 다룹니다.
`listingsapi-listing-audit`	사업장과 해당 등록 정보의 동기화 상태, 실제 등록 정보 링크, 중복 의심 항목을 확인한 다음 수정 사항을 제안합니다. 수정 사항을 승인하기 전까지는 읽기 전용으로 작동합니다.
`listingsapi-review-management`	리뷰 대기열을 만들고, 답글이 없는 리뷰를 우선 배치하며, 답글 초안을 작성하고, 승인한 답글만 게시합니다.
`listingsapi-multi-location-posting`	선택한 사업장들의 Google Business Profile과 Facebook에 공지, 이벤트, 혜택을 준비하여 게시한 다음 각 결과를 확인합니다.
`listingsapi-performance-reporting`	여러 사업장의 실적 및 리뷰에 대한 읽기 전용 보고서를 생성합니다.

Skills CLI로 프로젝트에 스킬 5개를 모두 설치하세요:

All skills

npx skills add listings-api/listingsapi-mcp

또는 이름으로 스킬 1개를 설치하고 -a로 에이전트를 선택하세요:

One skill, for Claude Code

npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-code

해당 에이전트에는 -a cursor 또는 -a codex을 사용하고, 현재 프로젝트 대신 모든 프로젝트에 설치하려면 -g를 추가하세요.

AI 도구 디렉터리에서 listingsAPI 찾기

동일한 서버가 listingsAPI 에이전트 스킬과 함께 다음 디렉터리에 등록되어 있습니다. 클라이언트에서 이미 사용하는 디렉터리를 통해 설치하세요. 모든 MCP 서버 항목은 https://listingsapi.com/mcp을 가리킵니다.

디렉터리	등록된 항목
Claude 커넥터 디렉터리	Claude 커넥터로 제공되는 MCP 서버입니다. Connect(연결)를 클릭하고 로그인하세요.
공식 MCP 레지스트리	`com.listingsapi/mcp`로 등록된 MCP 서버입니다.
Cursor Directory	Cursor 플러그인으로 제공되는 MCP 서버입니다.
Glama	MCP 서버입니다.
Smithery	MCP 서버입니다.
MCP.so	MCP 서버입니다.
mcpservers.org	MCP 서버입니다.
ClawHub (OpenClaw)	listingsAPI 에이전트 스킬입니다.
skills.sh	listingsAPI 에이전트 스킬입니다.

문제 해결

증상	원인	해결 방법
첫 도구 호출에서 `401` 발생	키를 잘못 입력했거나 키가 폐기되었거나, 헤더에 정확히 `API`라는 단어와 그 뒤의 공백이 없습니다	`/dashboard/keys`에서 키를 다시 생성하고 `API <key>` 형식으로 붙여넣으세요
쓰기 작업에서 `SY90016` 발생	읽기 키 또는 `read` 범위	쓰기 키로 다시 연결하거나 `write`를 승인하세요
`Retry-After`과 함께 `429` 발생	에이전트가 요금제에서 허용하는 빈도보다 빠르게 호출하고 있습니다	한 번에 처리하는 작업 수를 줄이도록 요청하세요. 요청 빈도 제한을 참조하세요
클라이언트에 서버에 연결할 수 없다는 메시지가 표시됩니다	클라이언트가 stdio 또는 SSE만 지원합니다	Streamable HTTP를 지원하는 클라이언트를 사용하거나 `/dashboard/mcp`에 나와 있는 `mcp-remote` 브리지를 사용하세요
문서에 언급된 도구가 없습니다	파괴적 작업을 수행하는 도구는 노출되지 않습니다	보관 및 삭제 작업에는 REST 또는 SDK를 사용하세요

다음 단계

통합 방식 선택: MCP가 적합한 경우와 REST 또는 SDK가 더 나은 선택인 경우를 설명합니다.
첫 API 호출 실행: 키를 발급받고 도구가 반환하는 응답 구조를 알아보세요.
웹훅으로 이벤트에 대응: 폴링하는 대신 플랫폼이 에이전트에 알림을 보내도록 설정하세요.
어시스턴트가 보고하는 코드는 인증 및 오류 코드를 참조하세요.