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.

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. Each database also has ai_timeout, the seconds an AI query on it runs at, and ai_read_only: when it is true, run_query runs only statements that read data there and refuses any write.

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.

The schema is the one Devhub stored at the database's last schema sync, so the call does not connect to the database. If nothing is stored yet, the tool syncs the database in the same call and returns the database's own error when the sync fails. A database whose default credential requires reviews is synced like any other, because a sync reads table and column names and no rows. A database with no default credential is not connected to, and the tool says why its tables can't be listed.

Each column carries the user's data-protection action: REDACTED means selecting it returns a masked value, never the real one, and REDACTED(JSON) means values are masked within the JSON structure. The policy is the stricter of the user's own policy and the database's AI policy.

  • Name
    database_id
    Type
    string, required
    Description

    The id of the database.

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. Every match carries the data-protection action applied to that column: show returns the real value, hide a masked one, and json masks values within the JSON structure.

  • 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.

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. The query runs at the database's AI timeout (the ai_timeout seconds list_databases shows); a different one can't be asked for. A result too large to hold in memory returns an error instead of being returned. When a policy applied, the result carries a redaction summary counting how many of the referenced columns were masked; get_database_schema names which ones.

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.

On a database whose ai_read_only is true, only statements that read data run. A write is refused with an error saying the database is read-only for AI, before it reaches the database or asks for a review, and the audit log records it as blocked. That holds for a query_id rerun too: a write approved before the database was set to read-only is refused when it is rerun. See what Read only enforces.

The tool's destructiveHint annotation is false only when every database the agent can reach is read-only for AI, and true while one of them allows AI writes. A client reads it when it connects, so reconnect to pick up a change.

  • 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. On a MongoDB database, statements in mongosh syntax.

  • 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_id and sql must be omitted.

  • Name
    retain_results
    Type
    boolean
    Description

    Keep the result so it can be downloaded as CSV, and return a download_url for it. The link expires in 15 minutes and needs no further auth. Requires the database to allow result retention; when it doesn't, download_unavailable says so and the rows still come back inline.

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.

Data protection

request_column_unredaction

Submits a request for a redacted column to be unredacted in the data-protection policies that govern the user, notifying an admin who can approve it. The agent only calls it when the user explicitly asks for access to a column, never on its own because a column is redacted.

  • Name
    database_id
    Type
    string, required
    Description

    The id of the database the column belongs to.

  • Name
    table_name
    Type
    string, required
    Description

    The table, named as get_database_schema lists it: qualified by its schema outside public (billing.invoices), bare in public.

  • Name
    column_name
    Type
    string, required
    Description

    The redacted column to request access to.

  • Name
    note
    Type
    string
    Description

    Why the user needs access, shown to the approving admin.

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. blocked_by_ai_read_only is true for an AI query refused because its database is read-only for AI, so nothing of it ran. 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. A user who is neither a super admin nor an audit log viewer sees only the queries they ran or approved, and a service account without Audit log viewer only the queries it ran.

  • 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_columns and result_rows instead 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_query or get_query_result.

  • Name
    result_rows
    Type
    array
    Description

    The rows of an earlier result, copied verbatim from run_query or get_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.

Was this page helpful?