# Connecting an IDE or other MCP client

DBGorilla speaks MCP, the Model Context Protocol, which is the standard way an AI tool talks to an
outside service. That means **any MCP client can connect to it**. All it needs is a URL and a key.

The CLI configures several clients for you natively: Claude Code, Cursor, VS Code, opencode and
Gemini CLI. If you use one of those, one command does the job:

```sh
dbgorilla setup-ide
```

Restart your editor and you are connected. Some clients pick the new server up on their own, but
restarting is the reliable way to be sure.

This page assumes the CLI is installed and you are signed in. If not, start at
[CLI Install and Setup](./cli-install-and-setup.md).

Using a client the CLI does not configure? Go straight to
[Connect any MCP client by hand](#connect-any-mcp-client-by-hand).

## Wire up your editor

```sh
dbgorilla setup-ide
```

With no arguments this finds every supported tool on your machine and configures all of them.

| Tool | Slug | Where the config goes |
|---|---|---|
| Claude Code | `claude-code` | Via `claude mcp add`; falls back to writing the file |
| Cursor | `cursor` | `~/.cursor/mcp.json` |
| VS Code | `vscode` | `.vscode/mcp.json`, in the current project, not your home directory |
| opencode | `opencode` | `~/.config/opencode/opencode.json` |
| Gemini CLI | `gemini` | `~/.gemini/settings.json` |
| Claude Desktop | `claude-desktop` | Not written; prints manual steps |

Claude Desktop is detect-only: remote MCP servers have to be added through **Settings →
Connectors** in the app, so the CLI prints instructions instead of editing anything.

```sh
dbgorilla setup-ide --list-clients        # what is supported, and what is on this machine
dbgorilla setup-ide --client cursor       # target one tool
dbgorilla setup-ide --client cursor,vscode
```

:::danger[Run `setup-ide` with no flags]

Every run of `setup-ide` issues a new MCP key and revokes the old one. You have exactly one key,
and only the newest works.

So anything that narrows what gets written leaves your other editors holding a revoked key. They
stop connecting, and `doctor` still reports them `[ OK ]`, because it checks that the config entry
exists, not that the key inside it still works.

`--dry-run` and `--print-config` mint a key too. Both request one from the server before deciding
not to write anything. They revoke the key your configured editors hold and write the new one
nowhere. **`--dry-run` is not a preview of `setup-ide`.**

Two invocations leave your key alone:

```sh
dbgorilla setup-ide --list-clients
dbgorilla setup-ide --print-admin-allowlist
```

Everything else mints a new one. Run `dbgorilla setup-ide` plain so every editor gets the same
current key in a single pass. If you genuinely have one editor, `--client` is fine.
:::

VS Code is the one to watch: every other tool writes a config in your home directory that applies
everywhere, while VS Code writes into the project you are currently in. `--scope user` or
`--scope project` overrides the default for the tools you selected.

The writes are conservative. MCP servers you already had are kept, and a config containing `//`
comments is refused rather than rewritten. Before modifying a config that already exists, the CLI
copies it to `<path>.backup.<timestamp>`; a file it creates from scratch has nothing to back up.

### Connect any MCP client by hand

You do not have to let the CLI edit your files, and you are not limited to the tools it knows
about. DBGorilla is an ordinary remote MCP server, so anything that speaks the protocol can
connect to it, including clients released after this page was written, and ones you build
yourself.

Four details are all any client needs:

| | Value |
|---|---|
| **Server name** | `dbgorilla` |
| **Server URL** | your deployment with `/mcp/` on the end. On SaaS: `https://app.dbgorilla.com/mcp/` |
| **Transport** | Streamable HTTP (not SSE, not stdio; there is no local process to run) |
| **Authentication** | the HTTP header `Authorization: Bearer <your MCP API key>` |

If your client asks for a command to run, a stdio binary, or a package to install, it is asking
the wrong question. DBGorilla is a hosted endpoint, not a local server. Look for whatever the
client calls a *remote*, *HTTP*, or *custom* MCP server.

Get the key first, then use the entry for your client below, or write the equivalent for a client
that is not listed.

### Getting your MCP key

You have one MCP key at a time, and **every `setup-ide` flag that would print it (`--print-key`,
`--print-config`, even `--dry-run`) issues a new one and revokes the old.** Reach for any of them
to read your key and you break every editor already using it.

**The app shows it to you.** Open your profile in DBGorilla and find the **MCP Server** card: your
current key is there, with a copy button. Reading it there changes nothing. That card is also
where you regenerate or delete the key when you want to.

If you would rather stay in the terminal, copy it out of a config the CLI has already written:

```sh
# whichever of these exists on your machine
grep -o 'Bearer [^"]*' ~/.cursor/mcp.json
grep -o 'Bearer [^"]*' ~/.gemini/settings.json
grep -o 'Bearer [^"]*' ~/.config/opencode/opencode.json
grep -o 'Bearer [^"]*' .vscode/mcp.json
```

Or ask the API. This endpoint returns the existing key and does not rotate it. `GET` reads, only
`POST` regenerates:

```sh
# macOS
TOKEN=$(security find-generic-password -s dbgorilla -a tokens -w | jq -r .access_token)

curl -sH "Authorization: Bearer $TOKEN" \
  https://app.dbgorilla.com/api/v0_1/client_api_keys/mcp-api-access
```

On Linux the CLI stores the same value in the Secret Service keyring. Use `secret-tool lookup
service dbgorilla username tokens` in place of the `security` call.

Both routes put a live credential on your screen, into your shell history, and, for the duration of
the request, into your process list where other users on a shared machine can read it. On a machine
you do not control, prefer copying the key from the app.

:::tip[When a new key is the right answer]

If you have lost the key entirely, or want to invalidate one that leaked, run plain
`dbgorilla setup-ide`. It issues a new key and writes it to every editor it finds in one pass, so
they all end up consistent. The danger is only in the flags that narrow which editors get written.
:::

#### Entries for specific clients

Most clients keep MCP servers in a JSON file under an `mcpServers` object, so the entries below
differ only in details. If yours is not here, copy the closest one and check its documentation for
what it calls the URL field.

**Claude Code**, in `~/.claude.json` or via `claude mcp add`:

```json
{
  "mcpServers": {
    "dbgorilla": {
      "type": "http",
      "url": "https://app.dbgorilla.com/mcp/",
      "headers": { "Authorization": "Bearer <your MCP API key>" }
    }
  }
}
```

**Cursor**, in `~/.cursor/mcp.json` (or `.cursor/mcp.json` for one project). Same shape, without
the `type` field:

```json
{
  "mcpServers": {
    "dbgorilla": {
      "url": "https://app.dbgorilla.com/mcp/",
      "headers": { "Authorization": "Bearer <your MCP API key>" }
    }
  }
}
```

**VS Code**, in `.vscode/mcp.json` for the project, or your user `mcp.json`. The top-level key is
`servers`, **not** `mcpServers`. Using `mcpServers` here silently loads nothing:

```json
{
  "servers": {
    "dbgorilla": {
      "type": "http",
      "url": "https://app.dbgorilla.com/mcp/",
      "headers": { "Authorization": "Bearer <your MCP API key>" }
    }
  }
}
```

**Gemini CLI**, in `~/.gemini/settings.json`. Use `httpUrl`, which selects Streamable HTTP. The
`url` key selects SSE instead, which is not what the DBGorilla endpoint serves:

```json
{
  "mcpServers": {
    "dbgorilla": {
      "httpUrl": "https://app.dbgorilla.com/mcp/",
      "headers": { "Authorization": "Bearer <your MCP API key>" }
    }
  }
}
```

**opencode**, in `~/.config/opencode/opencode.json`. The servers live under `mcp`, not
`mcpServers`, and the entry needs `enabled`:

```json
{
  "mcp": {
    "dbgorilla": {
      "type": "remote",
      "url": "https://app.dbgorilla.com/mcp/",
      "enabled": true,
      "headers": { "Authorization": "Bearer <your MCP API key>" }
    }
  }
}
```

**Claude Desktop** cannot be configured by file at all. Remote MCP servers go through
**Settings → Connectors → Add custom connector**, where you paste
`https://app.dbgorilla.com/mcp/` and complete the OAuth prompt. It authenticates with OAuth rather
than a Bearer token, so the key above does not apply, and the connector flow requires a Pro, Max,
Team or Enterprise plan.

:::caution[Project-scoped config files hold a live credential]

`.vscode/mcp.json` and `.cursor/mcp.json` live inside your repository, and the entry contains your
MCP key in plain text. Commit one and you have published a working credential. Prefer the
user-scoped file (`--scope user`), add the project file to `.gitignore`, or use your client's
support for referencing an environment variable instead of a literal.

If a key does reach a remote branch, replace it: run `dbgorilla setup-ide`, which issues a new key
and revokes the leaked one.
:::

Restart the client afterward. Some reload MCP configuration on their own, some only on startup, so
restarting is the one step that always works.

To check a client the CLI does not know about, ask it to list its MCP tools. A working connection
exposes DBGorilla's tools by name; a broken one usually reports the server as failed to start, or
returns a 401. A 401 means the endpoint rejected the credential: the key may be wrong, replaced by
a later `setup-ide` run, or sent to the wrong URL. Check the key and the URL before assuming it was
rotated. `dbgorilla doctor` only checks
the clients it manages, so it will not report on one you wired up by hand.

### If your organization gates MCP servers

On Claude Team and Enterprise an admin has to allowlist a server first. This prints the details to
send them, and works before you have signed in:

```sh
dbgorilla setup-ide --print-admin-allowlist
```