Conecte um agente de IA com MCP

Conecte Claude, ChatGPT, Cursor ou Gemini ao MCP hospedado para ler e agir em seus locais, listagens e avaliações com as ferramentas que você usaria.

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, além de algumas ferramentas de documentação, e as utiliza na sua conta. Este guia explica como conectar cada um dos principais clientes e, em seguida, verificar a conexão.

1. Saiba a que o agente terá acesso

O servidor disponibiliza pouco mais de sessenta ferramentas, cerca de dois terços delas apenas para leitura. Os nomes seguem os recursos REST, portanto locations_search, listings_premium, reviews_respond e posts_create_social fazem o mesmo 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 maneiras. Ambas resultam na mesma chave de API no lado do 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 dedicada àquela 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 o caminho mais rápido é 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 usando o botão + e, em seguida, 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) e, em seguida, Connectors (Conectores), e depois os membros clicam em Connect (Conectar) nesse conector. 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 único comando adiciona o servidor com sua chave:

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

Remova a opção --header e execute /mcp dentro do Claude Code para fazer login pelo navegador. Use --scope project para incluir a configuração do servidor em um arquivo .mcp.json compartilhado por toda a equipe e fazer o commit; não inclua uma chave nesse commit.

4. Conecte o ChatGPT

O ChatGPT se conecta a servidores MCP remotos como um conector personalizado quando 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. Digite 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, escolha 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 por conta própria para servidores HTTP e respeita os escopos anunciados, então 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, então 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 entrar com OAuth: o Cursor mostra um botão Connect (conectar) na entrada do servidor em Settings (configurações) e, em seguida, MCP, e abre o fluxo no navegador. Nunca inclua uma chave em um commit de .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, 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 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: entre 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 detalhes 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 PKCE públicos sem segredo, então registre um com a URL de redirecionamento exibida pelo 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, então um script pode fornecer 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, então 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, dentro do assistente, peça algo que precise acessar sua conta:

Use as ferramentas listingsapi para me dizer a qual conta estou conectado, quantos locais ela tem e qual é meu uso da API neste mês.

Uma conexão correta retorna respostas de whoami, locations_all e get_usage com o id real da sua conta e as contagens reais. Uma chave incorreta ou expirada retorna um erro Unauthenticated na primeira chamada de ferramenta, não na descoberta.

Boas instruções iniciais para o agente quando a conexão estiver funcionando:

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

Adicione as habilidades de agente do listingsAPI

Habilidades são instruções que um agente carrega quando uma tarefa corresponde a elas, para seguir um fluxo de trabalho testado em vez de elaborar um por conta própria. Elas funcionam junto com o servidor MCP: o servidor faz as chamadas, e a habilidade decide quais chamadas fazer e em que ordem. Cinco habilidades do listingsAPI estão publicadas em skills.sh a partir do repositório público listingsapi-mcp:

Instale as cinco habilidades no seu projeto com a CLI Skills:

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 habilidade de agente do listingsAPI. Instale pelo diretório que seu cliente já usa. Todas as entradas do servidor MCP apontam 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 da resposta retornada pelas ferramentas.
• Reaja a eventos com webhooks: faça com que a plataforma notifique seu agente em vez de realizar consultas periódicas.
• Autenticação e Códigos de erro para os códigos que o assistente informará a você.