MCP로 AI 에이전트 연결하기

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. 다음 명령어 하나로 키를 지정해 서버를 추가합니다:

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의 결과를 바탕으로 실제 계정 id와 수치를 답합니다. 키가 잘못되었거나 만료된 경우 도구 목록 조회 시점이 아니라 첫 번째 도구 호출에서 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

또는 이름으로 스킬 하나를 설치하고 -a로 에이전트를 선택합니다:

One skill, for Claude Code

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

Cursor나 Codex에서는 -a cursor 또는 -a codex를 사용하고, 현재 프로젝트 대신 모든 프로젝트에 설치하려면 -g를 추가합니다.

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

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

디렉터리	등록된 항목
Claude 커넥터 디렉터리	Claude 커넥터로 제공되는 MCP 서버입니다. Connect(연결)를 클릭하고 로그인합니다.
공식 MCP Registry	`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 키 또는 `read` 범위	Write 키로 다시 연결하거나 `write`를 승인합니다
`Retry-After`와 함께 `429` 발생	에이전트가 요금제에서 허용하는 속도보다 빠르게 호출하고 있습니다	에이전트에 더 작은 배치로 작업하도록 요청합니다. 요청 빈도 제한을 참조합니다
클라이언트에서 서버에 연결할 수 없다고 표시합니다	클라이언트가 stdio 또는 SSE만 지원합니다	Streamable HTTP를 지원하는 클라이언트 또는 `/dashboard/mcp`에 나와 있는 `mcp-remote` 브리지를 사용합니다
문서에 언급된 도구가 없습니다	파괴적 작업을 수행하는 도구는 노출되지 않습니다	보관 및 삭제에는 REST 또는 SDK를 사용합니다

다음 단계

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