Servidor MCP

Liga a Pedra ao Claude, ChatGPT, Cursor e qualquer cliente MCP. O servidor oficial Model Context Protocol expõe uma ferramenta por cada endpoint da Pedra — home staging virtual, renovação, melhoria de imagens e vídeos para anúncios — como chamadas que esperam e devolvem o URL final do recurso.

Servidor MCP oficial

De código aberto, com licença MIT e publicado no npm como @pedra-ai/mcp. Expõe uma ferramenta por cada endpoint da API; cada ferramenta é uma única chamada que espera e devolve o(s) URL(s) final(is) do recurso — sem IDs de tarefa para consultar. Internamente é uma camada fina sobre o SDK Node da Pedra.

Usa-o no Claude (web, telemóvel e desktop)

No Claude, abre Definições → Conectores → Adicionar conector personalizado, cola o URL acima e clica em Ligar — inicias sessão na Pedra uma vez e autorizas o acesso. Sem chave API para copiar. Funciona no Claude na web, no telemóvel e no desktop, e usa os créditos da tua conta.

No ChatGPT: a Pedra é um plugin oficial do ChatGPT. Abre Plugins na barra lateral do ChatGPT, pesquisa Pedra e clica em Install plugin. Vê como fazer um vídeo imobiliário com ChatGPT ou Claude.

O que podes fazer

Depois de ligado, pede ao teu assistente em linguagem natural — escolhe a ferramenta certa e devolve o URL da imagem ou vídeo final:

«Usa a Pedra para fazer home staging virtual de https://example.com/empty-living-room.jpg como uma sala minimalista.»

«Esvazia este quarto mobilado para mostrar a divisão vazia: https://example.com/bedroom.jpg»

«Renova esta cozinha antiquada num estilo escandinavo: https://example.com/kitchen.jpg»

«Adiciona uma planta grande ao canto desta sala: https://example.com/living.jpg»

«Clareia e endireita a foto que acabei de anexar.»

«Troca o céu cinzento desta foto exterior por um azul limpo: https://example.com/facade.jpg»

«Desfoca os rostos e as matrículas nesta foto virada para a rua: https://example.com/street.jpg»

«Cria um vídeo de anúncio com estas 8 fotos, com música e a legenda '3 quartos · 2 WC'.»

«Cria um tour virtual da Calle Mayor 12 com as minhas fotos 360° e dá-me o código para incorporar.»

«Quantos créditos da Pedra me restam?»

Fotos a partir do chat

As fotos que já estão na tua conta Pedra são a fonte mais fácil — basta pedir, p. ex. «cria um vídeo com as fotos do meu anúncio da Calle Mayor», e o assistente lista os teus imóveis, lê os URLs das imagens e renderiza o vídeo. Uma foto na web também serve: indica o URL e o servidor descarrega-a. Para as fotos que tens contigo:

• ChatGPT: anexa-as. As fotos anexadas ao chat chegam diretamente às ferramentas. Anexa uma foto e diz «mobila esta sala»: as nove ferramentas de uma só foto (pedra_furnish, pedra_enhance, pedra_empty_room e as restantes) recebem-na como imageFile em vez de imageUrl, e pedra_add_images_to_property recebe várias como files.
• Claude, ou fotos que ainda estão no telemóvel: um link de carregamento. O Claude não passa os anexos do chat às ferramentas, por isso o assistente chama pedra_create_upload_link e dá-te um link sem login, válido 24 horas. Abre-o no telemóvel (as HEIC do iPhone funcionam) ou envia-o ao fotógrafo, larga lá as fotos e diz ao assistente quando terminares. Ele lista-as com pedra_list_property_images e continua — edições, pedra_create_video ou pedra_create_virtual_tour. Por predefinição o link aceita fotos normais e fotos 360° (type: "any"); vê create_upload_link.

As fotos que entram de fora da app contam para um limite diário de carregamento (30 por dia no plano gratuito, 500 nos planos pagos).

Novo na Pedra?

Não é preciso ter conta antes. Ao ligar a Pedra no ChatGPT ou no Claude abre-se um separador de início de sessão da Pedra, e os utilizadores novos podem criar a conta aí mesmo. Outros agentes — Claude Code, scripts, o servidor MCP local — podem obter uma conta e uma chave API para o seu utilizador por email com agent_signup.

Outros clientes e configuração local (Cursor, scripts, config do Claude Desktop)

Para o Claude, usa o conector alojado acima. Para o Cursor, scripts locais ou para editar diretamente o ficheiro de configuração do Claude Desktop, executa o pacote npm sobre stdio — lança-se com npx (sem instalação global) e lê a tua chave da variável de ambiente PEDRA_API_KEY.

{
  "mcpServers": {
    "pedra": {
      "command": "npx",
      "args": ["-y", "@pedra-ai/mcp"],
      "env": { "PEDRA_API_KEY": "your-api-key" }
    }
  }
}

No Claude Desktop, abre Definições → Programador → Editar configuração e adiciona a entrada pedra. No Cursor, usa ~/.cursor/mcp.json (ou .cursor/mcp.json num projeto). Reinicia o cliente depois de guardar.

Autenticação

O servidor lê a tua chave de PEDRA_API_KEY. Obtém uma registando-te em app.pedra.ai e abrindo Definições → API. Vê Autenticação para detalhes.

Ferramentas

Uma ferramenta por cada endpoint, todas devolvem URLs finais:

• pedra_furnish, pedra_empty_room, pedra_renovation, pedra_edit_via_prompt, pedra_remove_object — vê Home staging virtual.
• pedra_enhance, pedra_enhance_and_correct_perspective, pedra_sky_blue, pedra_blur — vê Melhoria de imagens.
• pedra_create_video, pedra_update_video, pedra_generate_voice_script, pedra_generate_voice, pedra_music_library, além de pedra_credits e pedra_feedback — vê Vídeo e Créditos.
• pedra_list_properties, pedra_list_property_images, pedra_create_property, pedra_add_images_to_property — explora a tua biblioteca e adiciona fotos para que qualquer ferramenta as possa usar.
• pedra_create_upload_link, pedra_create_virtual_tour, pedra_get_virtual_tour, pedra_list_virtual_tours, pedra_update_virtual_tour, pedra_add_virtual_tour_scenes — cria e edita tours virtuais 360° alojados; vê Tours virtuais. Eliminar um tour só é possível pela API (/api/delete_virtual_tour), de propósito.
• pedra_social_accounts, pedra_social_post, pedra_social_list_posts, pedra_social_cancel_post: publica ou agenda um vídeo no Instagram, Facebook, TikTok e YouTube (Pedra Pro). Por agora só no servidor remoto; o pacote npm ainda não as tem. Vê Redes sociais.

A maioria das ferramentas de imagem recebe um imageUrl — um URL público, um URI data: ou um caminho absoluto para um ficheiro local (lido e incorporado automaticamente). Mais alguns parâmetros opcionais — o teu cliente mostra o esquema de entrada de cada ferramenta. No ChatGPT, uma foto anexada chega à ferramenta como imageFile; no Claude, uma imagem colada no chat não é enviada à ferramenta — indica um caminho ou usa um link de carregamento (vê Fotos a partir do chat). Todas as ferramentas de imagem e vídeo também aceitam um propertyId opcional: indica-o e o resultado é guardado na galeria dessa propriedade — visível e editável a partir da app — em vez de ser apenas devolvido como URL. Vê Propriedades.

Criar um tour virtual a partir do chat

As fotos 360° estão normalmente num telemóvel ou numa câmara 360°, e um chat não consegue passar ficheiros grandes a uma ferramenta. Por isso o assistente dá-te um link de carregamento — pede algo como «Cria um tour virtual da Calle Mayor 12 com as minhas fotos 360°» e ele faz o seguinte:

1. pedra_create_upload_link — recebes um link sem login, válido 24 horas. Abre-o no telemóvel (ou envia-o ao fotógrafo) e larga lá as fotos.
2. pedra_create_virtual_tour com esse propertyId — quando dizes que terminaste, cria o tour com todas as fotos carregadas, pela ordem do nome do ficheiro.
3. pedra_get_virtual_tour — a construção é o único fluxo assíncrono, por isso o assistente volta a verificar até o tour estar ready (cerca de 10 segundos por divisão).
4. Partilha o tourUrl e o iframe embedCode. Pede alterações por palavras tuas — «muda o nome do segundo quarto para Escritório», «começa o tour na sala» — e ele chama pedra_update_virtual_tour.

Se as fotos 360° já estiverem online, dispensa o link de carregamento: dá os URLs e o assistente passa-os diretamente a pedra_create_virtual_tour como scenes.

Como funciona

Uma camada fina sobre o SDK Node da Pedra. Cada endpoint espera e devolve o(s) URL(s) final(is) na resposta — mesmo pedra_create_video, que pode demorar até ~10 minutos (a API mantém a ligação viva com um heartbeat). Os erros da API — créditos insuficientes, uma imagem inválida — voltam como erros de ferramenta MCP legíveis, não como crashes.

Código & suporte

O servidor tem licença MIT e é desenvolvido de forma aberta em github.com/pedra-ai/pedra-mcp. Sabe mais sobre o protocolo em modelcontextprotocol.io, e envia email para felix@pedra.ai para ajuda com integração, quotas mais altas ou condições enterprise.

Perguntas frequentes