# MCP server

DBGorilla runs a remote MCP server.  MCP, the Model Context Protocol, lets an AI client such as
Claude Code, Cursor or Codex call tools on an outside service.  An assistant can use it to read your
database's topology, metrics, queries and recommendations, explain a query, and test a change on a
clone.

## Endpoint

| | |
|---|---|
| **URL** | `https://app.dbgorilla.com/mcp/` |
| **Transport** | Streamable HTTP.  There is nothing to install or run locally. |
| **Sign-in** | OAuth in a browser, or an MCP key sent as a header |

A request without credentials gets `401 Unauthorized` and this header.  An OAuth client uses it to
find where to sign in:

```text
WWW-Authenticate: Bearer resource_metadata="https://app.dbgorilla.com/.well-known/oauth-protected-resource/mcp"
```

## Sign in with OAuth

A client that supports MCP's OAuth sign-in needs only the URL.  It registers itself, opens a DBGorilla
sign-in page in your browser, and stores the token it receives.

| | |
|---|---|
| Authorization server metadata | `https://app.dbgorilla.com/.well-known/oauth-authorization-server/mcp` |
| Client registration | Dynamic, at `https://app.dbgorilla.com/mcp/register`.  No client id is required in advance. |
| PKCE | Required, `S256` only |
| Scopes | None.  A token can call every tool the server lists. |
| Access token lifetime | 8 hours, renewed with a refresh token |
| Revocation | `https://app.dbgorilla.com/mcp/revoke` |

The sign-in page names the client and the address it will send you back to, for example "Codex is
requesting access to DBGorilla on your behalf."  Continue only if you started the sign-in.

In Codex:

```sh
codex mcp add dbgorilla --url https://app.dbgorilla.com/mcp/
codex mcp login dbgorilla
```

For Claude Desktop, see [Claude Desktop](/docs/integrations/mcp-client/#claude-desktop).

## Sign in with an MCP key

Any client that can send a header can use a key instead.  Send it with every request in this header:

```text
Authorization: Bearer <your MCP key>
```

Each user has one MCP key at a time. `dbgorilla setup-ide --print-key` prints yours.
`dbgorilla logout` revokes it, as does `dbgorilla setup-ide --rotate-key`, which also issues a
new one. [Getting your MCP key](/docs/integrations/mcp-client/#getting-your-mcp-key) covers the
other ways to find it.

## Connect a client

The CLI writes the entry, including your key, for five clients:

| Client | Command | What you see |
|---|---|---|
| Claude Code | `dbgorilla setup-ide --client claude-code` | `claude mcp list` shows `dbgorilla` as `Connected` |
| Cursor | `dbgorilla setup-ide --client cursor` | Writes `~/.cursor/mcp.json` |
| VS Code | `dbgorilla setup-ide --client vscode` | Writes `.vscode/mcp.json` in the current folder |
| Gemini CLI | `dbgorilla setup-ide --client gemini` | `gemini mcp list` shows `dbgorilla` as `Connected` |
| opencode | `dbgorilla setup-ide --client opencode` | `opencode mcp list` shows `dbgorilla` as `connected` |

Gemini CLI turns MCP servers off in a folder you have not trusted, and `gemini mcp list` shows
`dbgorilla` as `Disabled` there.  Trust the folder and it connects.

For details of each entry, or to write one by hand, see [Connect your editor](/docs/integrations/editor/)
and [Connect an MCP client by hand](/docs/integrations/mcp-client/).

## Tools

The server lists up to 51 tools.  Where hosted databases are not offered, the eight hosted database
and monitoring tools may be missing from the list or may answer "not available".  The tools are grouped here by what they change.  The descriptions are the
ones the server sends to your client, shortened to what the tool does.

### Read DBGorilla's data

These read what DBGorilla has already collected and change nothing.

Start with `get_topology_overview`, which returns the component's identity, its members, its
databases, the class taxonomy, and the recent snapshots.  Four tools require a member id from it:
`run_explain`, `get_correlated_metrics`, `get_session_timeline` and `run_experiment`.

| Tool | What it does |
|---|---|
| `discover_components` | discover database components that are managed by dbgorilla.  Provides the required component_id to call other tools. |
| `get_topology_overview` | Get an overview of the connected component: identity and status, its members (servers) with their member_id, its scopes (databases), the class taxonomy, and recent snapshots. |
| `list_topology_snapshots` | List historical topology snapshots. |
| `compare_topology_snapshots` | List topology objects added, modified, or removed between two snapshots. |
| `inspect_topology_object` | Inspect a topology object at a given path.  Use `include` to request specific sections (payload, children, history). |
| `get_topology_object_history` | Return the change history for a topology object. |
| `search_topology_objects` | Search topology objects. |
| `discover_metrics` | List the raw metrics metadata available for the component or one member, grouped by kind, each with its unit and group_by keys. |
| `get_metric_timeseries` | Fetch one metric's time series. |
| `get_metric_ratio_timeseries` | Fetch numerator / sum(denominator) per bucket as a raw fraction (x100 for a percent). |
| `get_correlated_metrics` | Find metrics that co-moved with an anchor metric over a time range. |
| `list_dashboards` | List metadata for saved user-defined dashboards. |
| `view_dashboard` | View one user-defined dashboard as JSON describing the graphs it contains. |
| `discover_workloads` | List the workload ranking dimensions available. |
| `get_top_workload` | Return the top-N workload items (queries) ranked by a dimension. |
| `search_workloads` | Search workload descriptions (e.g. query text) by substring.  Returns counts plus the top-N matches ranked by a dimension. |
| `investigate_workload` | Drill into a single workload fingerprint: full stats, the query text, and a time-bucketed trend. |
| `compare_workload` | Compare workload stats between two time periods and return the biggest movers. |
| `get_workload_overview` | Time-bucketed workload aggregates summed across all fingerprints.  Use for instance- or database-wide trends. |
| `discover_activity` | List the available group_by dimensions, filters, and connection-count dimensions for the activity tools. |
| `get_activity_breakdown` | Active Session History (ASH) load breakdown.  Returns the top-N groups by average active sessions (AAS) over a window, optionally bucketed into a time series. |
| `get_activity_connections` | Provides detailed connection count data. |
| `get_activity_samples` | Active Session History (ASH) samples: a connection summary (total / active / idle / idle-in-transaction) plus the active, blocked, and idle-in-transaction sessions per snapshot, each with its session_id and query fingerprint. |
| `get_blocking_sessions` | Active Session History (ASH) blocking episodes, collapsed across snapshots. |
| `get_session_timeline` | Active Session History (ASH) per-session drill-down: the ordered snapshot list for a session plus summary stats. |
| `list_recommendations` | List database recommendations generated by DBGorilla.  Pass a query to search them by topic. |
| `view_recommendation` | View one database recommendation's full report including actions to take, and other analysis. |
| `list_investigations` | List historical investigations that have been run. |
| `get_investigation_report` | Get the full text of one investigation's final report. |
| `search_investigations` | Full-text search across historical investigation title + report content. |
| `search_customer_documents` | Searches documents an admin uploaded about this customer's own database: runbooks, schema notes, whatever they keep internally. |
| `search_best_practices` | Semantic search over best practices for this database. |
| `list_dbgorilla_product_documentation` | Lists every page of DBGorilla's product documentation, with a title, path and summary for each. |
| `read_dbgorilla_product_documentation` | Returns one page of DBGorilla's product documentation as Markdown. |
| `list_databases` | List the PostgreSQL databases DBGorilla hosts for this workspace, with their status, size, monitoring state and component_id. |
| `get_database` | Show one hosted database: status (provisioning, ready, suspended or deleting), instances ready, size, and monitoring state (pending, connected, error, not monitored, or paused while suspended). |
| `list_postgres_connections` | List the customer's own PostgreSQL servers that DBGorilla monitors from a connection string, with host, status and component_id. |

`list_recommendations` filters on the same four fields as the table, one value per field, and sorts
on one field at a time.  `view_recommendation` returns one full report.  `investigate_workload`
is a workload tool rather than an investigations one, despite the name.  It returns statistics and
a trend for a single query fingerprint.

### Query your live database, plan only

| Tool | What it does |
|---|---|
| `run_explain` | Run EXPLAIN on the LIVE database and return the query plan.  This hits the real production member directly (no sandbox clone), so it is the cheap way to read a query's current plan and costs.  It is plan-only and never executes the statement. |

`run_explain` returns a plan.

### Run code on a clone

| Tool | What it does |
|---|---|
| `run_experiment` | Run an experiment against a version-matched, ephemeral clone of a database based on a topology snapshot with production statistics, synthetic data, or both injected.  We run the provided python code in an isolated sandbox and return whatever it prints. |

### Change DBGorilla's recommendations

These change records kept in DBGorilla.  None of them touches your database.  Every change except creating one takes the
recommendation's current version, and a change sent with an older version is refused.

| Tool | What it does |
|---|---|
| `create_recommendation` | Create a database recommendation for the component. |
| `update_recommendation` | Revise an open database recommendation in place: its title, description, risk, or category. |
| `update_recommendation_priority` | Manage a database recommendation's priority. |
| `mark_recommendation_complete` | Mark a database recommendation as completed based on an observed change that matches the recommendation's suggested actions. |
| `ignore_recommendation` | Mark a database recommendation as ignored. |
| `reopen_recommendation` | Reopen a database recommendation, returning it to open. |
| `close_recommendation` | Close a database recommendation that is no longer valid or relevant, has been superseded by a newer finding, made moot by a changed workload, or otherwise no longer worth the team's attention. |

### Change what DBGorilla monitors

| Tool | What it does |
|---|---|
| `connect_postgres` | Start monitoring the user's own PostgreSQL server from a connection string.  DBGorilla first tests the connection: TLS, login, the pg_monitor role, and pg_stat_statements in the named database.  If a check fails, nothing is created and the error names the check and how to fix it. |
| `disconnect_postgres` | Stop monitoring one of the user's own PostgreSQL servers and remove its component.  The server itself is not touched. |

### Create or delete databases, or issue a login

| Tool | What it does |
|---|---|
| `create_database` | Create a long-lived PostgreSQL database that DBGorilla hosts and monitors.  There are no backups, so do not use it for data that cannot be recreated. |
| `get_database_credentials` | Issue a short-lived login to a ready hosted database through DBGorilla's access proxy.  The login owns the database.  The password is shown once and is not stored, so give it only to the user who asked for it. |
| `delete_database` | Permanently delete a hosted database, its storage and its monitoring.  There are no backups.  Only call it when the user has asked to delete this database, and pass its exact name as confirm_name. |

Where hosted databases are not available, the hosted database tools return "Hosted databases are
not available in this environment." and the two monitoring tools return "Monitoring Postgres from
a connection string is not available in this environment."

## What the tools can send back

Read tools return what DBGorilla already holds about your database: schema and topology, metrics,
query text and statistics, session activity, recommendations and investigation reports.

`run_explain` reads a plan from the live database and never runs the statement.  A `SELECT
pg_sleep(10)` returns its plan in under a second.

`run_experiment` runs your client's Python code as the `postgres` superuser on a clone.  The clone
has your schema and no rows.  When the experiment loads your production statistics, the code can
read `pg_stats`, and the most common values for each column come back in its output.  In a test,
the output contained real email addresses from a column in a table that had no rows in the clone.
Treat experiment output as containing values from your data.

For details about what the model layer sees and how to turn off the commands run by the collector,
see [How DBGorilla handles your data](/docs/security/faq/).

## What an admin should allow

The server does not yet have a read-only mode.  OAuth offers no scopes, and an MCP key or OAuth
token reaches every tool the server lists.  The tools also have no read-only or destructive annotations, so a client
cannot distinguish reads from writes on its own.

Until then, set permissions by group in the client:

| Group | Allow it for |
|---|---|
| Read DBGorilla's data | Everyone.  These change nothing. |
| Query your live database, plan only | Everyone, if you let the collector run `EXPLAIN` |
| Run code on a clone | People who may see values from your data |
| Change DBGorilla's recommendations | People who manage the recommendations list |
| Change what DBGorilla monitors | Only the people who manage monitoring.  Block it for everyone else. |
| Create or delete databases, or issue a login | Only the people who manage hosted databases.  Block it for everyone else. |

In Claude Code, a deny rule in your settings removes a tool from what the model can see:

```json
{
  "permissions": {
    "deny": [
      "mcp__dbgorilla__delete_database",
      "mcp__dbgorilla__get_database_credentials",
      "mcp__dbgorilla__create_database",
      "mcp__dbgorilla__connect_postgres",
      "mcp__dbgorilla__disconnect_postgres"
    ]
  }
}
```

If your organization gates MCP servers on Claude Team or Enterprise, see
[If your organization gates MCP servers](/docs/integrations/editor/#if-your-organization-gates-mcp-servers).