Document run_sql MCP tool and add warehouse security guidance

- Add Query execution section to MCP docs covering run_metric_query and run_sql tools
- Add custom instructions guidance for when to use run_sql vs run_metric_query
- Add warning about ensuring read-only warehouse credentials
- Update AI overview to mention SQL query capability
- Update FAQ to reflect query execution capabilities

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: charliedowler

guides/ai-overview.mdx

@@ -50,8 +50,8 @@ The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets you co
 **Key features:**
 - Connect Claude, ChatGPT, or custom agents to your Lightdash instance
 - Browse and query your data models
+- Run arbitrary SQL queries against your data warehouse for ad-hoc analysis
 - OAuth authentication with existing permissions
-- Read-only access for security
 
 <Card title="Lightdash Data MCP documentation" icon="plug" href="/references/integrations/lightdash-mcp">
   Set up MCP with your AI assistant

references/integrations/lightdash-mcp.mdx

@@ -245,6 +245,12 @@ Since MCP provides raw tools without built-in intelligence, your AI assistant ne
   - Search for business terms (e.g., "basket total", "partner name") not technical field names
   - Use multiple search queries in one call to find related fields efficiently
   - Look for both dimensions (for grouping) and metrics (for aggregation)
+
+  ### When to Use run_sql vs run_metric_query
+  - **Prefer `run_metric_query`** for standard analysis using defined metrics and dimensions — it leverages the semantic layer and ensures consistent definitions
+  - **Use `run_sql`** for ad-hoc queries, cross-table joins not modeled in explores, or when the user explicitly requests raw SQL
+  - `run_sql` defaults to 500 rows (max 5000) — use the `limit` parameter to control result size
+  - Use the SQL dialect appropriate for the connected warehouse (e.g., PostgreSQL, BigQuery, Snowflake)
   ```
 
   <Info>
@@ -279,6 +285,19 @@ MCP provides AI assistants with powerful tools to interact with your Lightdash d
 - **Find dashboards** - Locate existing dashboards by name or content
 - **Find charts** - Search through saved charts and visualizations
 
+#### Query execution
+
+- **Run metric query** - Execute queries using your semantic layer's metrics and dimensions
+- **Run SQL** - Execute arbitrary SQL queries directly against the project's data warehouse. Useful for ad-hoc analysis or queries that don't fit the explore-based model. Returns up to 500 rows by default (configurable up to 5,000).
+
+<Info>
+  **Run SQL** requires the `manage SqlRunner` permission. The SQL is executed directly against your warehouse, so use the appropriate SQL dialect for your connection (e.g., PostgreSQL, BigQuery, Snowflake).
+</Info>
+
+<Warning>
+  **Security best practice:** Ensure the database credentials configured in your Lightdash connection have **read-only (viewer) access** to your warehouse. Since `run_sql` executes arbitrary SQL, a connection with write permissions could allow AI agents to modify or delete warehouse data.
+</Warning>
+
 ### Example conversations
 
 Here are some examples of how you can interact with AI assistants using MCP:
@@ -389,7 +408,7 @@ A: Yes, each team member can set up their own MCP connection with their individu
 
 **Q: Can MCP modify my data or dashboards?**
 
-A: No, MCP has read-only access. It can search and explore your data models but cannot make any modifications to your Lightdash configuration or underlying data.
+A: No, MCP cannot modify your Lightdash configuration, dashboards, or underlying data. It can search, explore your data models, run metric queries, and execute SQL SELECT queries — but all operations are read-only.
 
 **Q: Claude returns data as text but no visual chart is displayed. What's wrong?**