# Cursor, VS Code e outros clientes

A configuração de cada editor, com a chave em uma variável ou com login.

Guia Somente leitura Chave ou login

**Antes de começar.** Quem conecta precisa poder administrar as chaves de API da imobiliária, um plano Business ou superior (ou acesso aprovado pelo suporte), estar fora do teste grátis e ter o e-mail verificado.

## Escolha: chave ou login

O servidor aceita os dois. Sem cabeçalho, o editor abre o ByDomu para você permitir o acesso (fica em Apps conectados). Com cabeçalho, use uma chave secreta somente leitura ( `Authorization: Bearer domu_sk_live_…`) guardada em uma variável de ambiente. Chaves publicáveis não servem.

[Quais permissões dar à chave](https://developers.bydomu.com/pt/guias/mcp)

## Cursor

```
// ~/.cursor/mcp.json (todos los proyectos) o .cursor/mcp.json (este proyecto)
{
  "mcpServers": {
    "bydomu": {
      "url": "https://mcp.bydomu.com/mcp",
      "headers": { "Authorization": "Bearer ${env:BYDOMU_API_KEY}" }
    }
  }
}
// Sin "headers", Cursor usa el inicio de sesión (OAuth) del servidor.
```

## VS Code (Copilot, modo agente)

```
// .vscode/mcp.json: VS Code pide la clave la primera vez y la guarda cifrada
{
  "servers": {
    "bydomu": {
      "type": "http",
      "url": "https://mcp.bydomu.com/mcp",
      "headers": { "Authorization": "Bearer ${input:bydomu-key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "bydomu-key", "description": "Clave secreta de ByDomu (solo lectura)", "password": true }
  ]
}
// Sin "headers", VS Code usa el inicio de sesión (OAuth). También: comando «MCP: Add Server».
```

O VS Code pede para confiar no servidor antes de iniciá-lo e confirmar as ferramentas; você pode desativar as que não usa em Configure Tools.

## Outros clientes MCP

Qualquer cliente com Streamable HTTP e cabeçalhos próprios (ou OAuth) funciona. Estes estão verificados na documentação deles:

Codex CLI:

```
# Codex CLI: la clave sale de la variable BYDOMU_API_KEY
codex mcp add bydomu --url https://mcp.bydomu.com/mcp --bearer-token-env-var BYDOMU_API_KEY
# o con inicio de sesión:
codex mcp login bydomu
```

Gemini CLI:

```
# Gemini CLI
gemini mcp add --transport http --header "Authorization: Bearer $BYDOMU_API_KEY" bydomu https://mcp.bydomu.com/mcp
# en settings.json: "httpUrl" (Streamable HTTP) + "headers"; sin headers, /mcp auth
```

Zed:

```
// settings.json de Zed. Sin "headers", Zed ofrece el inicio de sesión (OAuth).
"context_servers": {
  "bydomu": {
    "url": "https://mcp.bydomu.com/mcp",
    "headers": { "Authorization": "Bearer domu_sk_live_XXXXXXXX" }
  }
}
```

Inspector:

```
# Para depurar cualquier cliente: el inspector oficial de MCP
npx @modelcontextprotocol/inspector
# Transporte «Streamable HTTP», URL https://mcp.bydomu.com/mcp, encabezado Authorization: Bearer …
```

## Se algo falhar

- **401** A chave falta ou não é válida: confira se a variável existe no ambiente do editor e se o valor leva «Bearer ».
- **403** É uma chave publicável, falta a permissão dessa ferramenta ou o cliente manda um cabeçalho Origin (como um navegador): com chave secreta isso é recusado; use o login.
- **405** O cliente tenta SSE (GET): o servidor só fala Streamable HTTP por POST. Escolha «http» ou «Streamable HTTP».
- **429** Você passou do limite por minuto; o erro diz em quantos segundos tentar de novo.

## O que pode fazer, como revogar e boas práticas

O servidor é somente leitura: a IA pode consultar, mas não cria, muda nem apaga nada, e nunca envia mensagens aos seus clientes. Ela só vê o que estas permissões permitem, com o limite de uma chave secreta (60 requisições por minuto).

Pode Permissão

Buscar e ver imóveis publicados `portal:read`

Buscar e ver contatos `contacts:read`

Agenda e compromissos `appointments:read`

Ler as mensagens de um contato `conversations:read`

Funis e negócios `deals:read`

Tarefas pendentes `tasks:read`

Com uma chave, a IA vê o que essa chave permitir. Para cortar o acesso, pause ou apague a chave em Configurações › API Keys; a próxima chamada responde 401.

- Uma chave por integração, só com as permissões de leitura que usa. Deixe conversations:read de fora se não precisa das mensagens.
- A chave vai em uma variável de ambiente ou no cofre de segredos do cliente, nunca colada num chat, num arquivo do repositório nem numa URL.
- O que o ByDomu devolve inclui texto escrito pelos seus clientes: trate como dados, não como instruções. Não encadeie este conector com ferramentas que enviam e-mails ou mensagens sem aprovação de uma pessoa.
- Revise de vez em quando os Apps conectados e remova o que não se usa mais.