Documentação
MCP para assistentes de IA
O servidor MCP (Model Context Protocol) da Kondomino deixa um assistente de IA, como o Claude, o Cursor ou o ChatGPT, consultar o catálogo de condomínios como ferramentas: ele busca, abre a ficha e cita a fonte, sem você escrever código. É a mesma API da referência, com as mesmas cotas.
O que é
MCP é o padrão aberto que os assistentes de IA usam para chamar ferramentas externas. Conectado à Kondomino, o assistente recebe quatro ferramentas sobre condomínios publicados no Brasil: listar estados e cidades, buscar condomínios e abrir a ficha completa, com a procedência de cada registro (source_url, data de coleta e confiança).
Ainda não há busca de unidades nem de lotes: o catálogo, por enquanto, só tem os condomínios. A ferramenta entra quando as unidades chegarem.
Endereço
Um único endereço, com o transporte Streamable HTTP e sem sessão:
https://api.kondomino.com.br/mcpSem o cabeçalho Authorization, o servidor responde como a demonstração. Com Authorization: Bearer kd_live_…, ele usa a sua chave. Uma chave inválida ou revogada recebe um erro claro; ela nunca cai na demonstração sem avisar.
Sem chave: a demonstração
Para experimentar, basta o endereço. São 5 consultas por dia por endereço IP, até 10 condomínios por página e 2 páginas por busca — o mesmo saldo do simulador.
Claude Code — no terminal
claude mcp add --transport http kondomino https://api.kondomino.com.br/mcpClaude Desktop — claude_desktop_config.json
{
"mcpServers": {
"kondomino": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.kondomino.com.br/mcp"
]
}
}
}Cursor — ~/.cursor/mcp.json (ou .cursor/mcp.json no projeto)
{
"mcpServers": {
"kondomino": {
"url": "https://api.kondomino.com.br/mcp"
}
}
}No Claude Desktop, o arquivo fica em Configurações → Desenvolvedor → Editar configuração; reinicie o app depois de salvar. O mcp-remote faz a ponte entre o app e o servidor remoto e precisa do Node.js instalado. Nos planos que têm conectores personalizados, também dá para adicionar o endereço em Configurações → Conectores, sem arquivo — mas só na demonstração, porque esse caminho não envia o cabeçalho da chave.
Com chave
Crie uma chave grátis no console e mande-a no cabeçalho Authorization. Troque kd_live_SUA_CHAVE pela sua chave e não a coloque em arquivos versionados.
Claude Code — no terminal
claude mcp add --transport http kondomino https://api.kondomino.com.br/mcp \
--header "Authorization: Bearer kd_live_SUA_CHAVE"Claude Desktop — claude_desktop_config.json
{
"mcpServers": {
"kondomino": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.kondomino.com.br/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer kd_live_SUA_CHAVE"
}
}
}
}Cursor — ~/.cursor/mcp.json (ou .cursor/mcp.json no projeto)
{
"mcpServers": {
"kondomino": {
"url": "https://api.kondomino.com.br/mcp",
"headers": {
"Authorization": "Bearer kd_live_SUA_CHAVE"
}
}
}
}Outros clientes compatíveis com Streamable HTTP (inclusive o ChatGPT, nos planos com conectores) usam o mesmo endereço; os que não enviam cabeçalhos ficam na demonstração.
Ferramentas
| Ferramenta | O que faz | Conta consulta |
|---|---|---|
list_states() | UFs com condomínios publicados e quantos cada uma tem. | não |
list_cities(uf) | Cidades de uma UF com condomínios publicados; o slug é o valor de city na busca. | não |
search_kondos(uf?, city?, neighborhood?, amenity?, property_status?, q?, cursor?) | Busca condomínios publicados. Exige uf ou city. Devolve o resumo de cada um e next_cursor para a página seguinte; cada página conta. | sim |
get_kondo(slug) | Ficha completa: endereço, preço de referência, comodidades, mídia (links da fonte) e procedência com source_url. | sim |
Cada resultado traz o JSON das mesmas projeções da API REST (resumo na busca, ficha completa por slug) e um texto curto em português. O assistente vê quantas consultas restam no dia e quando a cota renova.
Limites
O MCP é outra porta para a mesma cota da API: uma busca pelo MCP e uma pelo REST gastam o mesmo saldo. Na demonstração, 5 consultas por dia por IP; com chave, 50 por dia no Grátis (veja preços). Cada página de search_kondos e cada get_kondo contam uma consulta; list_states e list_cities não contam. A cota renova à meia-noite de São Paulo.
Todas as requisições ao servidor também têm o freio de 30 por minuto (por chave, ou por IP sem chave). Quando a cota acaba, a ferramenta responde com um aviso: na demonstração, para criar uma chave grátis; com chave, para ver os planos.