MySQL 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 or plugins, and get_table_schema returns a table's columns.
• Table details: get_table_metadata returns constraints, indexes and estimated size.
• Run SQL: run_query runs SQL with %s placeholders and returns up to 10,000 rows.
• Query plans: explain_query shows EXPLAIN plans, or EXPLAIN ANALYZE on MySQL 8 and later when analyze is requested.
• Health and performance: analyze_db_health reports connections, buffer pool size and reclaimable space, and get_top_queries lists the heaviest queries from performance_schema.

Before you connect

• A database user just for InsightfulPipe with only the privileges agents need, for example SELECT for read-only use. Never reuse root.
• A public hostname or IP address. Private, loopback and link-local addresses are rejected.
• TLS enabled on the server, with a certificate that matches the hostname or a CA certificate you can provide.
• If the database is firewalled, allowlist InsightfulPipe's outbound IP addresses, shown in your workspace settings.

Connect MySQL

1. In the InsightfulPipe app, open Connectors, choose MySQL 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 URI such as mysql://user:[email protected]:3306/mydb?ssl-mode=REQUIRED, or choose Enter fields manually.
4. For manual entry, fill in Host, Port, Database, Username and Password, and pick an SSL mode.
5. If the server uses a private CA or client certificates, open Advanced: client TLS certificates and add the server CA certificate, client certificate and client private key in PEM format.
6. Click Connect MySQL. InsightfulPipe runs one short SELECT 1 to verify the connection before saving it.

Add the MCP server to your AI client

Server URL: https://mysql.insightfulmcp.com/ and server name: mysql-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 mysql-mcp https://mysql.insightfulmcp.com/, then type /mcp, select mysql-mcp and click Authenticate.
• Cursor: in the app, open MCP Servers, choose MySQL and click Install MySQL MCP, click Open Cursor then Install, then click Connect and Open.
• Gemini CLI: run gemini mcp add --transport http mysql-mcp https://mysql.insightfulmcp.com/, then /mcp auth mysql-mcp.
• Codex CLI: run codex mcp add mysql-mcp --url https://mysql.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: MySQL connections have no Read Only or Read + Write choice in InsightfulPipe. The GRANTs on the database user 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, CREATE or DROP, a SELECT that writes INTO a file or variable, 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.
• EXPLAIN ANALYZE runs the statement: explain_query counts as a read action, but with analyze it executes the statement it explains. To stop agents running 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 user that has only SELECT privileges, so MySQL 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, up to 60 seconds, is set with MySQL's MAX_EXECUTION_TIME, which MySQL applies to SELECT statements only. Other statements are not capped by it.
• Query size: query text can be up to 256 KB.
• TLS: the disabled and preferred SSL modes are refused, and connections verify the server certificate and hostname.
• Network: databases on private networks without a public address are not supported.
• Server features: get_top_queries needs performance_schema, and EXPLAIN ANALYZE needs MySQL 8 or later.
• 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 shop schema."
• "What indexes does the orders table have?"
• "Which queries take the most total time?"
• "Which tables have the most reclaimable space?"

Troubleshooting

• The connection test fails: check the host, port and database name, that the host is public, that your firewall allows InsightfulPipe's outbound IP addresses, and that TLS is on with a certificate that matches the hostname or a 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 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.
• MySQL returns an access denied error: the database user lacks that privilege. Grant it on the server, or leave the user read-only on purpose.
• A query times out: add filters or a LIMIT, check the plan with explain_query without analyze, or allow a longer timeout of up to 60 seconds.

FAQ

Does it work with MariaDB?

Yes. The connector works with MySQL or MariaDB servers that meet the same network and TLS requirements.

Which SQL statements can agents run?

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

How do I keep the connection read-only?

Connect with a user that has only SELECT privileges. 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 host with its own name, and each counts toward your plan's connection limit.

Related

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