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（追加）をクリックします。Advanced settings（詳細設定）は空欄のままにしてください。サーバーがClaudeをクライアントとして自動的に登録します。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 インストールリンクを開くため、1 回のクリックで設定が完了します。

手動で設定する場合は、すべてのプロジェクトで使用するには ~/.cursor/mcp.json に、1 つのリポジトリ内で使用するにはそのリポジトリの .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 の Google プロフィールの分析データを、直近2か月で比較してください。"
"create-location エンドポイントの仕様を読んでから、次の拠点を追加してください: ..."

listingsAPIのエージェントスキルを追加する

スキルとは、タスクが条件に合ったときにエージェントが読み込む指示です。エージェントは手順を一から考える代わりに、検証済みのワークフローに従います。スキルはMCPサーバーと連携して動作し、サーバーが呼び出しを実行し、スキルがどの呼び出しをどの順序で行うかを決定します。5つのlistingsAPIスキルが、パブリックなlistingsapi-mcpリポジトリから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

CursorやCodexの場合は-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キーまたは`read`スコープを使用しています	Writeキーで再接続するか、`write`を承認します
`429`が`Retry-After`とともに返されます	エージェントがプランで許可されている頻度を超えて呼び出しを行っています	バッチを小さくして処理するようにエージェントに依頼します。詳しくはレート制限を参照してください
クライアントにサーバーへ接続できないと表示されます	クライアントがstdioまたはSSEにしか対応していません	Streamable HTTPに対応したクライアント、または`/dashboard/mcp`に記載されている`mcp-remote`ブリッジを使用します
ドキュメントに記載されているツールが見つかりません	破壊的な操作を行うツールは公開されていません	アーカイブと削除にはRESTまたはSDKを使用します

次の手順

連携方法を選ぶ：MCPが適している場合と、RESTまたはSDKのほうが適している場合を説明します。
初めてのAPI呼び出しを行う：キーを取得し、ツールが返すレスポンスの構造を学びます。
Webhookでイベントに対応する：ポーリングする代わりに、プラットフォームからエージェントに通知が届くようにします。
アシスタントが報告するコードについては、認証とエラーコードを参照してください。