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:

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:

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

For Claude Desktop, see 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:

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 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 and Connect an MCP client by hand.

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.

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:

{
  "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.