Skip to main content
This document covers mssql_execute_query, the read-only SQL query tool for Microsoft SQL Server exposed through the Agents Platform.

​
Authentication

mssql_execute_query connects to a customer’s own SQL Server (SQL Authentication only — username/password, not Windows/Azure AD auth) via the generic integrations config form. Users configure:
  • host, port (default 1433), database, username, password
  • encrypt — disable, true (TLS required), or strict (TDS 8.0, verify certificate). Default true.
  • trust_server_certificate — trust the server’s TLS certificate without CA verification. Default false. Enable this for an on-prem server with a self-signed certificate (encrypt: true + trust_server_certificate: true); otherwise the connection fails with a certificate-verification error.
  • host_name_in_certificate — optional, only relevant when validating a certificate whose SAN doesn’t match the connection host.
  • schema — optional namespace. Leave empty to use the default dbo schema.
All of these fields are injected by the platform from the stored integration at call time (x-variable-service: "mssql") — they are not entered per run.

​
mssql_execute_query

Executes a read-only SQL query against a SQL Server database and returns the results as structured rows.

​
Inputs

Required:
  • query: SQL query to execute. SELECT statements only — see below.
Optional:
  • max_rows: Maximum rows to return (defaults to 3000 when unset or 0; a caller-supplied value above 3000 is honored as-is, not clamped).

​
SELECT-only enforcement

Only statements starting with SELECT (after trimming whitespace) are accepted; anything else is rejected before a connection is even opened. Use mssql_upsert for writes — its query field accepts arbitrary INSERT/UPDATE/DELETE/MERGE statements when the structured upsert path can’t express what you need.

​
Schema qualification

SQL Server has no search_path equivalent, so unlike some other database connectors this tool never sets a session-level default schema. Reference tables with the schema explicit in the query (SELECT * FROM dbo.orders or SELECT * FROM sales.orders) — the configured schema field only affects credential defaults surfaced elsewhere (e.g. mssql_upsert’s generated statements), not what you write in a raw query here.

​
Output

On success, structured content includes:
  • columns: column names, in result order
  • rows: array of column → value objects
  • row_count: number of rows returned (after truncation)
  • truncated: true if more rows existed than max_rows allowed
  • database, host: the database/host queried
  • max_rows: the effective cap applied

​
Notes

  • A uniqueidentifier column comes back as a standard GUID string (e.g. "01234567-89AB-CDEF-0123-456789ABCDEF"), not raw bytes — the tool decodes SQL Server’s internal mixed-endian byte layout for you.
  • Every query execution emits a HIPAA audit event (external_call, provider mssql) recording the host, latency, and outcome — see SQL Server Upsert for the same on the write path.