Conecte agentes de IA ao MCP do listingsAPI

Use Claude, ChatGPT, Cursor ou Gemini no servidor MCP hospedado para ler e atuar em seus locais, listagens e avaliações com as mesmas ferramentas que você.

A Listings API hospeda um servidor Model Context Protocol (MCP) em https://listingsapi.com/mcp. Não é necessário instalar nem executar nada. Um assistente de IA compatível com MCP se conecta a essa URL, descobre uma ferramenta para cada endpoint REST e algumas ferramentas de documentação, e as chama na sua conta. Este guia explica como conectar cada um dos principais clientes e depois verificar a conexão.

1. Saiba a quais ferramentas o agente tem acesso

O servidor disponibiliza pouco mais de 60 ferramentas, cerca de dois terços delas somente para leitura. Os nomes seguem os recursos REST, portanto locations_search, listings_premium, reviews_respond e posts_create_social executam as mesmas operações que os endpoints correspondentes, com os mesmos parâmetros e a mesma estrutura de resposta. Três ferramentas de documentação, search_docs, get_doc e get_endpoint, permitem que o assistente consulte uma página ou o contrato de um endpoint em vez de tentar adivinhar a estrutura de um payload.

Operações destrutivas, como excluir uma publicação ou arquivar um local, não são disponibilizadas como ferramentas. Use a API REST ou um SDK para essas operações, de modo que um assistente não possa remover dados por conta própria.

2. Escolha como o cliente faz login

Cada cliente se autentica de uma de duas formas. Ambas resultam na mesma chave de API no servidor, portanto os limites de requisições e os relatórios de uso são idênticos.

OAuth usa o fluxo de código de autorização com PKCE e registro dinâmico de clientes, portanto o cliente não precisa de credenciais emitidas previamente. Os metadados estão em https://listingsapi.com/.well-known/oauth-authorization-server. Os escopos são read e write; um cliente que não solicita nenhum recebe read. Cada aprovação cria uma chave exclusiva para essa conexão, que você pode revogar em /dashboard/keys como qualquer outra chave.

3. Conecte o Claude

Claude.ai e Claude Desktop. O servidor está listado no diretório de conectores, portanto a forma mais rápida é abrir https://claude.ai/directory/listings-api e clicar em Connect (Conectar). O Claude executa o fluxo OAuth, você aprova os escopos, e as ferramentas ficam disponíveis em qualquer conversa na qual você habilite o conector pelo botão + e depois por Connectors (Conectores).

Se você preferir adicioná-lo pela URL, acesse Customize (Personalizar), depois Connectors (Conectores), clique em + e em Add custom connector (Adicionar conector personalizado), cole https://listingsapi.com/mcp e clique em Add (Adicionar). Deixe Advanced settings (Configurações avançadas) em branco; o servidor registra o Claude como cliente automaticamente. Nos planos Team e Enterprise, um proprietário adiciona o conector em Organization settings (Configurações da organização), depois em Connectors (Conectores), e os membros clicam em Connect (Conectar) nesse conector em seguida. O Claude se conecta a partir dos servidores da Anthropic, e não da sua máquina, por isso a URL hospedada é importante.

Claude Code. Um comando adiciona o servidor com sua chave:

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

Para fazer login pelo navegador, remova a opção --header e execute /mcp dentro do Claude Code. Use --scope project para incluir a configuração do servidor em um arquivo .mcp.json compartilhado por toda a equipe e adicioná-lo ao controle de versão; não inclua uma chave nesse commit.

4. Conecte o ChatGPT

O ChatGPT se conecta a servidores MCP remotos como um conector personalizado quando o Developer mode (modo de desenvolvedor) está ativado. Esse recurso está disponível nos planos Plus, Pro, Business, Enterprise e Edu, mas não no plano gratuito.

1. Abra Settings (configurações) no menu do seu perfil e ative Developer mode (modo de desenvolvedor). Dependendo da versão, essa opção fica em Apps & Connectors (aplicativos e conectores) ou Security and login (segurança e login).
2. Na página de conectores (chamada Plugins (plugins) nas versões atuais), clique em + ou Create (criar).
3. Insira um nome, cole https://listingsapi.com/mcp como URL do servidor e escolha OAuth para autenticação. Salve.
4. O ChatGPT abre a página de login. Aprove read ou read write.
5. Em uma nova conversa, abra o menu de ferramentas, selecione o conector e confirme que ele aparece com suas ferramentas. As ferramentas de escrita continuam exigindo confirmação.

Codex CLI. O agente de terminal da OpenAI lê os servidores MCP de ~/.codex/config.toml. O Codex inicia o OAuth automaticamente para servidores HTTP e respeita os escopos informados, portanto, a linha de cabeçalho é opcional:

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

5. Conecte o Cursor

A página do painel em /dashboard/mcp tem um botão Add to Cursor (adicionar ao Cursor). Ele abre um link de instalação do Cursor com a URL do servidor e sua chave já preenchidas, de modo que um clique conclui a configuração.

Para configurar manualmente, adicione o servidor a ~/.cursor/mcp.json para todos os projetos ou a .cursor/mcp.json dentro de um repositório:

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

Remova o bloco headers para fazer login com OAuth: o Cursor exibe um botão Connect (conectar) na entrada do servidor em Settings (configurações), depois MCP, e abre o fluxo no navegador. Nunca inclua em um commit uma chave dentro de um .cursor/mcp.json no nível do projeto; use o arquivo global ou OAuth para repositórios compartilhados.

6. Conecte o Gemini

Gemini CLI. O agente de terminal do Google aceita servidores remotos em ~/.gemini/settings.json (ou .gemini/settings.json em um projeto). Use httpUrl, e não url, para que ele selecione o transporte Streamable HTTP:

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

Para usar OAuth, substitua o bloco headers por "oauth": { "enabled": true }, inicie a CLI e execute /mcp auth listingsapi. Execute /mcp a qualquer momento para listar o servidor, seu estado de conexão e as ferramentas que ele descobriu.

Aplicativo Gemini. O aplicativo Gemini para consumidores não tem uma configuração de conector personalizado. Servidores MCP personalizados estão disponíveis para administradores de equipe da edição Gemini Enterprise Business: faça login em business.gemini.google, abra Settings & help (configurações e ajuda), depois Manage team (gerenciar equipe) e Connected apps (aplicativos conectados), e clique em Add MCP Server (adicionar servidor MCP). Cole https://listingsapi.com/mcp como URL. O formulário solicita os dados de OAuth: a URL de autorização é https://listingsapi.com/oauth/authorize, a URL de token é https://listingsapi.com/oauth/token e os escopos são read write. Ele também solicita um ID de cliente e um segredo de cliente. Este servidor emite clientes públicos PKCE sem segredo, portanto, registre um com a URL de redirecionamento exibida no formulário e deixe o segredo em branco se o formulário permitir:

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"}'

A resposta contém client_id. Se o formulário do Gemini exigir um segredo, use o procedimento com a Gemini CLI acima ou desenvolva com a Gemini API.

Desenvolvimento com a Gemini API. O SDK da Gemini API aceita uma sessão de cliente MCP como ferramenta, permitindo que um script disponibilize as mesmas ferramentas a um modelo Gemini:

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. Verifique a conexão

Antes de confiar no assistente, confirme que o servidor responde diretamente a você. A descoberta de ferramentas não exige chave, portanto, esta chamada funciona com qualquer cliente que consiga acessar a URL:

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

Depois, no assistente, peça algo que precise acessar sua conta:

Use as ferramentas listingsapi para mostrar meu plano, contar meus locais e informar meu uso da API neste mês.

Uma conexão que funciona retorna seu plano e status de acesso de whoami, os dados dos locais de locations_all e as contagens de uso de get_usage. Uma chave incorreta ou expirada resulta em um erro Unauthenticated na primeira chamada de ferramenta, e não na descoberta.

Instruções para o agente que você pode usar primeiro, assim que a conexão funcionar:

• "Liste meus locais que têm erros de listagem e resuma cada erro."
• "Mostre as avaliações recebidas nos últimos 7 dias que estão sem resposta e elabore uma resposta para cada uma. Ainda não envie as respostas."
• "Compare as métricas do perfil do Google para o local 1800289 entre os últimos 2 meses."
• "Leia o contrato do endpoint create-location e depois adicione este local: ..."

Adicione as skills de listingsAPI para agentes

Skills são instruções que um agente carrega quando correspondem a uma tarefa, para seguir um fluxo de trabalho testado em vez de criar um por conta própria. Elas funcionam em conjunto com o servidor MCP: o servidor executa as chamadas, e a skill determina quais chamadas fazer e em que ordem. Cinco skills de listingsAPI estão publicadas em skills.sh a partir do repositório público listingsapi-mcp:

Instale as cinco no seu projeto com a Skills CLI:

npx skills add listings-api/listingsapi-mcp

Ou instale uma pelo nome e escolha o agente com -a:

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

Use -a cursor ou -a codex para esses agentes e adicione -g para instalar para todos os projetos em vez de apenas para o projeto atual.

Encontre listingsAPI em diretórios de ferramentas de IA

O mesmo servidor está listado nestes diretórios, junto com a skill de listingsAPI para agentes. Instale pelo diretório que seu cliente já usa. Cada entrada do servidor MCP aponta para https://listingsapi.com/mcp.

Solução de problemas

Próximos passos

• Escolha como integrar: quando MCP é adequado e quando REST ou um SDK é a melhor opção.
• Faça sua primeira chamada à API: obtenha uma chave e conheça a estrutura das respostas retornadas pelas ferramentas.
• Reaja a eventos com webhooks: configure a plataforma para notificar seu agente em vez de fazer consultas periódicas.
• Autenticação e Códigos de erro para consultar os códigos que o assistente informará a você.