# Cursor, VS Code and other clients

Each editor’s configuration, with the key in a variable or with sign-in.

Guide Read-only Key or sign-in

**Before you start.** Whoever connects needs to be able to manage the agency’s API keys, a Business plan or higher (or support-approved access), to be past the free trial and to have a verified email.

## Choose: key or sign-in

The server accepts both. Without a header, the editor opens ByDomu so you allow access (it shows up in Connected apps). With a header, use a read-only secret key ( `Authorization: Bearer domu_sk_live_…`) kept in an environment variable. Publishable keys don’t work.

[Which permissions to give the key](https://developers.bydomu.com/en/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, agent mode)

```
// .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».
```

VS Code asks you to trust the server before starting it and to confirm tools; you can turn off the ones you don’t use in Configure Tools.

## Other MCP clients

Any client with Streamable HTTP and custom headers (or OAuth) works. These are verified in their docs:

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 …
```

## If something fails

- **401** The key is missing or invalid: check the variable exists where the editor runs and that the value includes “Bearer ”.
- **403** It’s a publishable key, it lacks that tool’s permission, or the client sends an Origin header (like a browser): that’s rejected with a secret key; use sign-in.
- **405** The client tries SSE (GET): the server only speaks Streamable HTTP over POST. Choose “http” or “Streamable HTTP”.
- **429** You went over the per-minute limit; the error says how many seconds to wait.

## What it can do, how to revoke it and good practices

The server is read-only: the AI can query, but it doesn’t create, change or delete anything, and it never messages your customers. It only sees what these permissions allow, with a secret key’s limit (60 requests per minute).

It can Permission

Search and view published listings `portal:read`

Search and view contacts `contacts:read`

Calendar and appointments `appointments:read`

Read a contact’s messages `conversations:read`

Pipelines and deals `deals:read`

Pending tasks `tasks:read`

With a key, the AI sees whatever that key allows. To cut access, pause or delete the key in Settings › API Keys; the next call returns 401.

- One key per integration, with only the read permissions it uses. Leave conversations:read out if you don’t need messages.
- The key goes in an environment variable or the client’s secret store, never pasted into a chat, a repository file or a URL.
- What ByDomu returns includes text your customers wrote: treat it as data, not instructions. Don’t chain this connector with tools that send emails or messages without a person approving it.
- Review Connected apps now and then and remove what’s no longer used.