SQL Server MCP connector

What agents can do

The server has 8 actions: 7 read and 1 write.

• Explore the schema: list_schemas lists schemas, list_tables lists tables, views and sequences, and get_table_schema returns a table's columns.
• Table details: get_table_metadata returns constraints, indexes and estimated size.
• Run T-SQL: run_query runs T-SQL with %s placeholders and returns up to 10,000 rows.
• Execution plans: explain_query returns the estimated plan (SHOWPLAN_XML) without running the query, or actual execution statistics when analyze is requested.
• Health and performance: analyze_db_health reports connection state, memory clerks and transaction log reuse, and get_top_queries lists the heaviest queries from sys.dm_exec_query_stats.

Before you connect

• A SQL login and database user just for InsightfulPipe with only the permissions agents need, for example db_datareader membership for read-only use. Never reuse sa.
• SQL authentication. The connector signs in with a login name and password.
• A public hostname or IP address. Private, loopback and link-local addresses are rejected.
• Encryption on the server, with a publicly trusted certificate or a CA certificate you can provide.
• If the server is firewalled, allow InsightfulPipe's outbound IP addresses, shown in your workspace settings. On Azure SQL, add them under Networking → Public access → Firewall rules; on premises, open port 1433 to them.

Connect SQL Server

1. In the InsightfulPipe app, open Connectors, choose SQL Server and click Connect.
2. Enter a Connection name. InsightfulPipe generates the connection's MCP identifier from it.
3. Choose String connection URI and paste a sqlserver:// or mssql:// URI such as sqlserver://user:[email protected]:1433/mydb?encrypt=true&trustServerCertificate=false, or choose Enter fields manually.
4. For manual entry, fill in Host, Port, Database, Username and Password.
5. Keep Encrypt connection (TLS) on. If the server certificate is signed by a private CA, open Advanced: server TLS certificate and add the Server CA certificate (PEM).
6. Click Connect SQL Server. InsightfulPipe runs one SELECT 1 to verify the connection before saving it.

Add the MCP server to your AI client

Server URL: https://mssql.insightfulmcp.com/ and server name: mssql-mcp.

• Claude: open Claude Connectors Settings, scroll to the bottom and click Add custom connector, paste the URL, click Add, then click Connect.
• ChatGPT: in ChatGPT Security Settings turn on Developer mode, click Create on the Connectors page, paste the URL, click Create, then click Connect. Turn the connector on in each new chat with + → More.
• Claude Code: run claude mcp add --transport http mssql-mcp https://mssql.insightfulmcp.com/, then type /mcp, select mssql-mcp and click Authenticate.
• Cursor: in the app, open MCP Servers, choose SQL Server and click Install SQL Server MCP, click Open Cursor then Install, then click Connect and Open.
• Gemini CLI: run gemini mcp add --transport http mssql-mcp https://mssql.insightfulmcp.com/, then /mcp auth mssql-mcp.
• Codex CLI: run codex mcp add mssql-mcp --url https://mssql.insightfulmcp.com/; authorization starts automatically.

Each client opens a browser window where you log in to InsightfulPipe and click Authorize access. Step-by-step guides: Claude, ChatGPT, Claude Code, Cursor, Gemini CLI and Codex CLI. To reach every connected platform through one server, use the unified server.

Permissions and safety

• No Read Only mode: SQL Server connections have no Read Only or Read + Write choice in InsightfulPipe. The permissions of the SQL login decide whether a statement succeeds.
• What counts as a write: a request is a read only when it is a single SELECT statement with no INTO and no data-changing CTE. Anything else, such as INSERT, UPDATE, DELETE, MERGE, CREATE or DROP, a SELECT INTO, or several statements in one request, is a write.
• Where writes run: the read-only query_data tool refuses writes, so they run only through execute_action, and only for members with the Owner, Administrator or Operator role. InsightfulPipe does not limit which statement types run.
• On by default: run_query is enabled on a new connection.
• Actual execution statistics run the statement: explain_query counts as a read action, but with analyze it executes the statement to collect actual statistics. To stop agents running T-SQL, turn off both run_query and explain_query in Configure actions for this account, which leaves schema discovery and health checks.
• Keep it read-only: connect with a login that only has read permissions, such as db_datareader membership, so SQL Server rejects writes.
• Restricted members: members with the User role only get the read actions enabled on databases granted to them.

Limits

• Rows: up to 10,000 rows per query, 1,000 by default.
• Timeout: the timeout setting, up to 60 seconds, is applied as a lock timeout. It limits how long a statement waits for locks, not how long it runs.
• Query size: query text can be up to 256 KB.
• Encryption: encryption is required, and the trust server certificate option is not supported.
• Network: databases on private networks without a public address are not supported.
• System views: get_top_queries and analyze_db_health need permission to read the related system views.
• Lost write responses: if the response to a write is lost, the result is reported as an unknown outcome instead of being retried. Check the database before running the statement again.

Example prompts

• "List the tables in the dbo schema."
• "What indexes and constraints does Sales.Orders have?"
• "Which queries use the most CPU time?"
• "Show the estimated plan for this report query."

Troubleshooting

• The connection test fails: check the host, port and database name, that the host is public, that the Azure SQL firewall rules or port 1433 allow InsightfulPipe's outbound IP addresses, and that the server certificate is publicly trusted or signed by the CA certificate you added.
• "This action modifies data and cannot run through the read-only query_data tool. Send the same body through execute_action instead." The T-SQL is not a single SELECT, so it must run through execute_action.
• "Your role does not have permission to execute write actions. Only operators, admins, and owners can execute write operations." Members with the User role can't run writes. Ask a workspace admin to change your role.
• SQL Server returns a permission error: the login lacks that permission, or can't read the system views that the health and top queries actions use. Grant it on the server, or leave the login read-only on purpose.
• A query is blocked or times out: the timeout counts lock waits, so check for blocking sessions, add filters, or check the estimated plan with explain_query without analyze.

FAQ

Does it work with Azure SQL?

Yes. Connect Azure SQL the same way, and add InsightfulPipe's outbound IP addresses to the server's firewall rules.

Which T-SQL statements can agents run?

Any statement the SQL login is allowed to run. A single SELECT runs as a read. INSERT, UPDATE, DELETE, MERGE, DDL, SELECT INTO and multiple statements are writes, limited to owners, administrators and operators.

How do I keep the connection read-only?

Connect with a login that only has read permissions, such as db_datareader membership. You can also turn off run_query and explain_query for the connection, which leaves schema discovery and health checks.

Can I connect several databases?

Yes. Each connection is one database on one server with its own name, and each counts toward your plan's connection limit.

Related

• SQL Server MCP server
• PostgreSQL, MySQL and BigQuery connectors
• Google Sheets connector
• Roles and permissions
• MCP troubleshooting