MCP Tools
The DevHub MCP server exposes a fixed catalog of tools an AI client can call. Every tool runs as the authorized user, so it sees only the databases that user can access, honors data-protection redaction, respects the per-database AI caps and approval gate, and is recorded in the audit log.
Tools are the only MCP capability available today. MCP resources, prompts, and subscriptions are not yet exposed.
Read & discovery
Tools that inspect databases, schema, and data without writing.
list_databases
Lists the databases the AI may use: those with AI access enabled that the current user can access. Each database includes the AI-allowed credentials to run as — a credential's id is what run_query needs, and a credential whose reviews_required is greater than 0 means a query run with it is held for peer review instead of returning rows.
This tool takes no parameters.
get_database_schema
Gets the schema of a database — tables and their columns, types, primary and foreign keys, and indexes.
- Name
database_id- Type
- string, required
- Description
The id of the database.
sample_table
Returns a sample of rows from a table. Values are redacted per the user's data-protection policy and the number of rows is capped by the database's AI max-rows setting. If the query requires peer review, no rows are returned until it is approved.
- Name
database_id- Type
- string, required
- Description
The id of the database.
- Name
table- Type
- string, required
- Description
The table name.
- Name
limit- Type
- integer
- Description
Max rows to return; capped by the database's AI max rows.
search_schema
Searches table and column names across all AI-enabled databases the current user can access. Useful for locating where data lives before querying.
- Name
search- Type
- string, required
- Description
Text to match against table and column names.
- Name
database_ids- Type
- array
- Description
Optional list of database ids to restrict the search to.
get_data_protection
Reports which columns of a database are redacted (hidden) or visible for the current user, so the agent knows what data it may and may not see.
- Name
database_id- Type
- string, required
- Description
The id of the database.
Execution
Running SQL through the standard QueryDesk query pipeline.
run_query
Runs SQL through the standard query pipeline using a specific database credential and returns the result. The credential identifies its own database and must be AI-allowed in the database settings. Values are redacted per the user's data-protection policy and the number of rows is capped. A result too large to hold in memory returns an error instead of being returned.
If the credential requires peer review, no rows are returned until the query is approved — you get back a query_id with status pending_approval. Once it is approved, call run_query again with that query_id (and nothing else) to run the exact approved SQL; it cannot be altered after approval. See the approval model for the full flow.
- Name
credential_id- Type
- string
- Description
The id of the AI-allowed database credential to run as.
- Name
sql- Type
- string
- Description
The SQL to execute.
- Name
query_id- Type
- string
- Description
Re-request a query that was returned as pending and has since been approved. Run it alone — the approved SQL is immutable, so
credential_idandsqlmust be omitted.
A call is either credential_id + sql (a fresh query) or query_id alone (re-running an approved query) — not both.
cancel_query
Withdraws a pending query that was submitted for peer review and is no longer wanted. Only a query that has not executed can be withdrawn; once withdrawn it is removed and can no longer be approved or run.
- Name
query_id- Type
- string, required
- Description
The id of the pending query to withdraw.
Saved queries & history
Working with the team's saved queries and past query activity — the same things a person can see, never more.
list_saved_queries
Lists the saved queries available to the current user — the organization's shared queries plus any private queries the user saved themselves. Returns titles and labels only, not the SQL; use get_saved_query to read a query's SQL.
This tool takes no parameters.
get_saved_query
Fetches a single saved query by id, including its SQL. Returns the query only when it belongs to the user's organization and is either shared or saved by the user themselves.
- Name
saved_query_id- Type
- string, required
- Description
The id of the saved query to fetch.
save_query
Saves a SQL query to the organization's query library so it can be reused later. Saved as the current user; mark it private to keep it visible only to them.
- Name
title- Type
- string, required
- Description
A short, human-readable name for the query.
- Name
query- Type
- string, required
- Description
The SQL to save.
- Name
private- Type
- boolean
- Description
When true, only the saving user can see it. Defaults to false.
search_audit_log
Searches executed queries for a database over a date range to see what ran and who ran it — useful for debugging "what changed in prod". Scoped to a database the user can access; returns the SQL plus who ran it, approvals, and review comments — never result rows. The date range is interpreted in the user's configured timezone. Returns at most the 100 most recent matches — narrow the date range or filters to see older activity.
- Name
database_id- Type
- string, required
- Description
The id of the database to search.
- Name
start_date- Type
- string, required
- Description
Inclusive start of the window, ISO-8601 date (YYYY-MM-DD).
- Name
end_date- Type
- string, required
- Description
Inclusive end of the window, ISO-8601 date (YYYY-MM-DD).
- Name
user_id- Type
- string
- Description
Only return queries run by this user.
- Name
query- Type
- string
- Description
Only return queries whose SQL contains this text.
query_history
Lists the current user's own queries executed against a database in a date range (newest first), with whether each query's result is still retained (available), was cleaned up (expired), or was never retained (never). Scoped to a database the user can access; returns the SQL only, never result rows — use get_query_result for an available result.
- Name
database_id- Type
- string, required
- Description
The id of the database whose history to list.
- Name
start_date- Type
- string, required
- Description
Inclusive start of the window, ISO-8601 date (YYYY-MM-DD).
- Name
end_date- Type
- string, required
- Description
Inclusive end of the window, ISO-8601 date (YYYY-MM-DD).
- Name
query- Type
- string
- Description
Only return queries whose SQL contains this text.
get_query_result
Returns the retained result of one of the current user's own past queries, found via query_history. Only queries that asked for their result to be kept have one, and it is dropped once the database's retention period passes. Rows come back exactly as run_query returns them, so they can be passed straight to share_query. The number of rows is capped by the database's AI limit.
- Name
query_id- Type
- string, required
- Description
The id of the query whose retained result to return.
Shared queries
Turning a query and its result into a link the user can open, keep, and pass on. A shared query is only openable by people signed in to the organization — there is no anonymous link.
share_query
Shares a query with the rest of the organization and returns a link. To share the result too, either copy the columns and rows from a run that already happened into result_columns and result_rows, or set rerun to have the tool run the SQL itself. A rerun is refused when the credential requires peer review, and write statements are never rerun — those share the SQL alone and report results_omitted_reason. Results can only be stored when the database allows query results to be retained.
- Name
credential_id- Type
- string, required
- Description
The id of the AI-allowed credential the query belongs to.
- Name
sql- Type
- string, required
- Description
The SQL to share.
- Name
rerun- Type
- boolean
- Description
When true, run the SQL and store its result on the share. Leave it off and pass
result_columnsandresult_rowsinstead when the query has already been run. Defaults to false.
- Name
result_columns- Type
- array
- Description
The columns of an earlier result, copied from
run_queryorget_query_result.
- Name
result_rows- Type
- array
- Description
The rows of an earlier result, copied verbatim from
run_queryorget_query_result.
- Name
expires_in_days- Type
- integer
- Description
Stop the link working after this many days. Omit for a share that never expires.
list_shared_queries
Lists the shared queries the current user can open — the organization's unrestricted shares plus any restricted ones shared with them or created by them. Expired shares are left out. Returns each share's link and SQL, but never its stored result rows.
This tool takes no parameters.
get_shared_query
Reads one shared query: its SQL, link, and expiry. Pass include_results to also return the rows frozen into the share when it was created.
- Name
shared_query_id- Type
- string, required
- Description
The id of the shared query to read.
- Name
include_results- Type
- boolean
- Description
When true, also return the share's stored result rows. Defaults to false.
delete_shared_query
Deletes a shared query, so its link stops working. The current user must have created the share, unless they are an organization super admin.
- Name
shared_query_id- Type
- string, required
- Description
The id of the shared query to delete.