Listable

Crie diretórios de sites via MCP

Documentação

Servidor MCP Listable

Permita que Claude, Cursor e outros assistentes de IA gerenciem seu site de diretório Listable por meio de conversa natural.

Listable é uma plataforma para criar sites de diretório — guias de restaurantes, diretórios de empresas, listagens de viagens, sites curados de nicho. Seu servidor MCP (Model Context Protocol) expõe cada operação de gerenciamento do site como uma ferramenta estruturada que os assistentes de IA podem chamar.

Pergunte à IA coisas como:

"Adicione 20 restaurantes italianos no Brooklyn ao meu diretório de comida."
"Importe estas listagens do CSV que estou colando."
"Defina o título meta de SEO e a descrição para a página inicial."
"Adicione um menu suspenso de Categorias ao cabeçalho."
"Crie uma página Sobre com nossa missão e uma lista de listagens em destaque."

O que ele pode fazer

~47 ferramentas nestes grupos:

Grupo	Ferramentas
Projetos	listar, obter, descoberta de esquema
Itens (listagens)	listar (paginado, filtrado), obter, criar, atualizar, excluir, bulk_create (até 100/chamada)
Categorias	CRUD completo, árvores de categorias, inspeção de conflitos
Campos personalizados	listar, criar, atualizar, excluir (texto, número, data, url, caixa de seleção, seleção, telefone, endereço, imagem)
Páginas + blocos	listar páginas, obter/atualizar blocos de página, gerenciar áreas de blocos globais (hero da página inicial, principal da página inicial, página de detalhes, páginas de categoria)
Formulários	listar, obter, criar, atualizar, excluir; gerenciar campos de formulário
Configurações	menu, scripts, SEO, estrutura de URL, tema
Redirecionamentos	CRUD completo
Uploads	enviar imagens / arquivos para uso em listagens e páginas

A IA é instruída a chamar get_schema primeiro para que suas edições usem os campos personalizados e tipos de bloco corretos. Operações destrutivas (exclusões, substituições completas de blocos, alterações na estrutura de URL, sobrescritas de scripts) solicitam confirmação antes de serem executadas.

Duas formas de conectar

	OAuth (recomendado)	Chave de API estática (este pacote)
Como funciona a autenticação	O cliente abre um navegador, você faz login no Listable, escolhe quais projetos conceder, pronto	Você cria uma chave no admin, cola-a na configuração do cliente
Funciona com	Claude.ai web, Claude Code, Cursor, qualquer cliente que suporte HTTP MCP + descoberta OAuth	Claude Desktop (sem transporte HTTP), ou qualquer lugar onde você queira uma conexão com token estático
Configuração	Cole uma URL	Instale este pacote + crie + cole uma chave

Se o seu cliente suporta transporte HTTP MCP, pule o shim completamente — veja Configuração OAuth abaixo. O pacote npm (listable-mcp) só é necessário para clientes somente stdio, como Claude Desktop.

Configuração OAuth (sem necessidade de instalação)

O endpoint MCP é:

https://app.get-listable.com/api/v1/external/mcp

Quando um cliente se conecta sem um token de portador, o servidor retorna um 401 mais uma dica de descoberta WWW-Authenticate apontando para /.well-known/oauth-protected-resource. O cliente a segue, redireciona você para fazer login, pede que você aprove os escopos (incluindo quais projetos conceder) e obtém um token automaticamente. Os tokens de acesso expiram após 1 hora e são renovados silenciosamente por 1 mês.

Claude.ai (web)

Configurações → Integrações → Adicionar integração personalizada → cole:

https://app.get-listable.com/api/v1/external/mcp

O Claude.ai redireciona você para o Listable para fazer login e escolher os projetos aos quais a integração pode acessar. Revogue a qualquer momento na página de Chaves de API no seu admin do Listable.

Claude Code

claude mcp add --transport http listable https://app.get-listable.com/api/v1/external/mcp

O Claude Code faz o fluxo OAuth no seu navegador no primeiro uso. Verifique com /mcp dentro de uma sessão.

Cursor

Em Configurações → MCP, adicione um servidor HTTP:

Nome: listable
URL: https://app.get-listable.com/api/v1/external/mcp

O Cursor acionará o fluxo OAuth na primeira conexão.

Fallback Stdio (este pacote npm)

Use este caminho para Claude Desktop (que ainda não suporta HTTP MCP) ou qualquer cliente somente stdio. Você precisará criar uma chave de API primeiro:

Abra Chaves de API no seu admin do Listable: https://app.get-listable.com/my-account/api-keys
Clique em Criar uma nova chave de API, dê um nome (ex.: "Claude Desktop") e, opcionalmente, escopá-la para projetos específicos
Copie a chave — ela só é exibida uma vez

Claude Desktop

Abra Configurações → Desenvolvedor → Editar Config (claude_desktop_config.json) e adicione:

{
  "mcpServers": {
    "listable": {
      "command": "npx",
      "args": ["-y", "listable-mcp"],
      "env": {
        "LISTABLE_API_TOKEN": "lst_..."
      }
    }
  }
}

Saia e reinicie completamente o Claude Desktop. As ferramentas do Listable aparecem no menu Pesquisar e ferramentas.

Outros clientes stdio

Qualquer cliente MCP que inicie um subprocesso pode executar npx -y listable-mcp e passar LISTABLE_API_TOKEN no ambiente.

Instalação global (opcional)

Se você preferir não depender da resolução de npx a cada inicialização:

npm install -g listable-mcp

Em seguida, aponte o cliente para o binário listable-mcp diretamente em vez de npx -y listable-mcp.

Configuração

Variável de ambiente	Obrigatória	Padrão	Finalidade
`LISTABLE_API_TOKEN`	sim	—	Chave de API de https://app.get-listable.com/my-account/api-keys
`LISTABLE_MCP_URL`	não	`https://app.get-listable.com/api/v1/external/mcp`	Substituir o endpoint upstream (Listable auto-hospedado ou staging)

Limites de taxa

Plano Growth: 60 requisições/minuto, 750 chamadas de ferramentas/mês
Plano Pro: 300 requisições/minuto, chamadas mensais ilimitadas

Atingir qualquer um dos limites retorna um 429 com retry_after (por minuto) ou quota_reset_at (mensal). Para trabalho em massa, a IA prefere bulk_create_items (até 100 listagens/chamada) em vez de muitas criações individuais.

Segurança

As descrições das ferramentas instruem a IA a:

Descobrir primeiro — chamar get_schema antes de editar para que as alterações usem os campos personalizados e tipos de bloco corretos
Confirmar operações destrutivas — exclusões, substituições completas de blocos de página, alterações na estrutura de URL e sobrescritas de scripts solicitam confirmação explícita
Fazer backup antes de editar — manter o estado anterior no contexto para restaurar se algo der errado
Acrescentar, não substituir — scripts (análises, rastreamento) são acrescentados ao conteúdo existente

Cada chamada de ferramenta é registrada contra o projeto que ela tocou. Veja a linha do tempo em Projeto → API no seu admin do Listable — filtrável por fonte (MCP vs REST) e retida por 30 dias.

Revogando acesso

Concessões OAuth: aparecem na página de Chaves de API junto com chaves criadas manualmente. Revogue lá.
Chaves de API estáticas: revogue na mesma página de Chaves de API. O cliente de IA receberá erros 401 na próxima chamada.

Solução de problemas

Erros "Não autenticado" (shim stdio) — Confirme que LISTABLE_API_TOKEN está definido no mesmo shell ou bloco de configuração que inicia o cliente. No Claude Desktop, o mapa env na configuração JSON deve conter a chave.

Loop OAuth / navegador não redireciona de volta — Certifique-se de que a URL de redirecionamento do cliente esteja acessível. Alguns clientes usam um callback de localhost; cookies ou bloqueadores de pop-up podem interromper o fluxo.

"Ferramenta não disponível" — Reinicie o cliente (Claude Desktop requer sair e reabrir completamente). No Claude Code, execute /mcp para confirmar que o Listable está conectado.

403 em projetos específicos — Seu token é escopado. OAuth: execute novamente a aprovação e selecione mais projetos. Chave estática: crie uma nova sem escopo de projeto.

Licença

MIT — veja LICENSE.