# Table of Contents - [Documentation | MCP Toolbox for Databases](#documentation-mcp-toolbox-for-databases) - [Getting Started | MCP Toolbox for Databases](#getting-started-mcp-toolbox-for-databases) - [Introduction | MCP Toolbox for Databases](#introduction-mcp-toolbox-for-databases) - [Getting Started | MCP Toolbox for Databases](#getting-started-mcp-toolbox-for-databases) - [Getting Started | MCP Toolbox for Databases](#getting-started-mcp-toolbox-for-databases) - [Introduction | MCP Toolbox for Databases](#introduction-mcp-toolbox-for-databases) - [Introduction | MCP Toolbox for Databases](#introduction-mcp-toolbox-for-databases) - [Python Quickstart (Local) | MCP Toolbox for Databases](#python-quickstart-local-mcp-toolbox-for-databases) - [Introduction | MCP Toolbox for Databases](#introduction-mcp-toolbox-for-databases) - [Introduction | MCP Toolbox for Databases](#introduction-mcp-toolbox-for-databases) - [Python Quickstart (Local) | MCP Toolbox for Databases](#python-quickstart-local-mcp-toolbox-for-databases) - [Getting Started | MCP Toolbox for Databases](#getting-started-mcp-toolbox-for-databases) - [Getting Started | MCP Toolbox for Databases](#getting-started-mcp-toolbox-for-databases) - [Python Quickstart (Local) | MCP Toolbox for Databases](#python-quickstart-local-mcp-toolbox-for-databases) - [Introduction | MCP Toolbox for Databases](#introduction-mcp-toolbox-for-databases) - [Introduction | MCP Toolbox for Databases](#introduction-mcp-toolbox-for-databases) - [Python Quickstart (Local) | MCP Toolbox for Databases](#python-quickstart-local-mcp-toolbox-for-databases) - [Python Quickstart (Local) | MCP Toolbox for Databases](#python-quickstart-local-mcp-toolbox-for-databases) - [Python Quickstart (Local) | MCP Toolbox for Databases](#python-quickstart-local-mcp-toolbox-for-databases) - [JS Quickstart (Local) | MCP Toolbox for Databases](#js-quickstart-local-mcp-toolbox-for-databases) - [JS Quickstart (Local) | MCP Toolbox for Databases](#js-quickstart-local-mcp-toolbox-for-databases) - [JS Quickstart (Local) | MCP Toolbox for Databases](#js-quickstart-local-mcp-toolbox-for-databases) - [Python Quickstart (Local) | MCP Toolbox for Databases](#python-quickstart-local-mcp-toolbox-for-databases) - [JS Quickstart (Local) | MCP Toolbox for Databases](#js-quickstart-local-mcp-toolbox-for-databases) - [Go Quickstart (Local) | MCP Toolbox for Databases](#go-quickstart-local-mcp-toolbox-for-databases) - [Go Quickstart (Local) | MCP Toolbox for Databases](#go-quickstart-local-mcp-toolbox-for-databases) - [Prompts using Gemini CLI | MCP Toolbox for Databases](#prompts-using-gemini-cli-mcp-toolbox-for-databases) - [Prompts using Gemini CLI | MCP Toolbox for Databases](#prompts-using-gemini-cli-mcp-toolbox-for-databases) - [Go Quickstart (Local) | MCP Toolbox for Databases](#go-quickstart-local-mcp-toolbox-for-databases) - [JS Quickstart (Local) | MCP Toolbox for Databases](#js-quickstart-local-mcp-toolbox-for-databases) - [Prompts using Gemini CLI | MCP Toolbox for Databases](#prompts-using-gemini-cli-mcp-toolbox-for-databases) - [Quickstart (MCP) | MCP Toolbox for Databases](#quickstart-mcp-mcp-toolbox-for-databases) - [JS Quickstart (Local) | MCP Toolbox for Databases](#js-quickstart-local-mcp-toolbox-for-databases) - [Go Quickstart (Local) | MCP Toolbox for Databases](#go-quickstart-local-mcp-toolbox-for-databases) - [Go Quickstart (Local) | MCP Toolbox for Databases](#go-quickstart-local-mcp-toolbox-for-databases) - [Quickstart (MCP) | MCP Toolbox for Databases](#quickstart-mcp-mcp-toolbox-for-databases) - [Prompts using Gemini CLI | MCP Toolbox for Databases](#prompts-using-gemini-cli-mcp-toolbox-for-databases) - [Configuration | MCP Toolbox for Databases](#configuration-mcp-toolbox-for-databases) - [Configuration | MCP Toolbox for Databases](#configuration-mcp-toolbox-for-databases) - [JS Quickstart (Local) | MCP Toolbox for Databases](#js-quickstart-local-mcp-toolbox-for-databases) - [Quickstart (MCP) | MCP Toolbox for Databases](#quickstart-mcp-mcp-toolbox-for-databases) - [Quickstart (MCP) | MCP Toolbox for Databases](#quickstart-mcp-mcp-toolbox-for-databases) - [Prompts using Gemini CLI | MCP Toolbox for Databases](#prompts-using-gemini-cli-mcp-toolbox-for-databases) - [Configuration | MCP Toolbox for Databases](#configuration-mcp-toolbox-for-databases) - [Concepts | MCP Toolbox for Databases](#concepts-mcp-toolbox-for-databases) - [Concepts | MCP Toolbox for Databases](#concepts-mcp-toolbox-for-databases) - [Prompts using Gemini CLI | MCP Toolbox for Databases](#prompts-using-gemini-cli-mcp-toolbox-for-databases) - [Go Quickstart (Local) | MCP Toolbox for Databases](#go-quickstart-local-mcp-toolbox-for-databases) - [Quickstart (MCP) | MCP Toolbox for Databases](#quickstart-mcp-mcp-toolbox-for-databases) - [Go Quickstart (Local) | MCP Toolbox for Databases](#go-quickstart-local-mcp-toolbox-for-databases) - [Concepts | MCP Toolbox for Databases](#concepts-mcp-toolbox-for-databases) - [Telemetry | MCP Toolbox for Databases](#telemetry-mcp-toolbox-for-databases) - [Prompts using Gemini CLI | MCP Toolbox for Databases](#prompts-using-gemini-cli-mcp-toolbox-for-databases) - [Configuration | MCP Toolbox for Databases](#configuration-mcp-toolbox-for-databases) - [Telemetry | MCP Toolbox for Databases](#telemetry-mcp-toolbox-for-databases) - [Quickstart (MCP) | MCP Toolbox for Databases](#quickstart-mcp-mcp-toolbox-for-databases) - [Telemetry | MCP Toolbox for Databases](#telemetry-mcp-toolbox-for-databases) - [Quickstart (MCP) | MCP Toolbox for Databases](#quickstart-mcp-mcp-toolbox-for-databases) - [How-to | MCP Toolbox for Databases](#how-to-mcp-toolbox-for-databases) - [Concepts | MCP Toolbox for Databases](#concepts-mcp-toolbox-for-databases) - [How-to | MCP Toolbox for Databases](#how-to-mcp-toolbox-for-databases) - [How-to | MCP Toolbox for Databases](#how-to-mcp-toolbox-for-databases) - [Configuration | MCP Toolbox for Databases](#configuration-mcp-toolbox-for-databases) - [Telemetry | MCP Toolbox for Databases](#telemetry-mcp-toolbox-for-databases) - [Configuration | MCP Toolbox for Databases](#configuration-mcp-toolbox-for-databases) - [Concepts | MCP Toolbox for Databases](#concepts-mcp-toolbox-for-databases) - [Telemetry | MCP Toolbox for Databases](#telemetry-mcp-toolbox-for-databases) - [Concepts | MCP Toolbox for Databases](#concepts-mcp-toolbox-for-databases) - [Concepts | MCP Toolbox for Databases](#concepts-mcp-toolbox-for-databases) - [Connect from your IDE | MCP Toolbox for Databases](#connect-from-your-ide-mcp-toolbox-for-databases) - [How-to | MCP Toolbox for Databases](#how-to-mcp-toolbox-for-databases) - [Connect from your IDE | MCP Toolbox for Databases](#connect-from-your-ide-mcp-toolbox-for-databases) - [Telemetry | MCP Toolbox for Databases](#telemetry-mcp-toolbox-for-databases) - [How-to | MCP Toolbox for Databases](#how-to-mcp-toolbox-for-databases) - [Telemetry | MCP Toolbox for Databases](#telemetry-mcp-toolbox-for-databases) - [Connect from your IDE | MCP Toolbox for Databases](#connect-from-your-ide-mcp-toolbox-for-databases) - [Connect from your IDE | MCP Toolbox for Databases](#connect-from-your-ide-mcp-toolbox-for-databases) - [Style Guide | MCP Toolbox for Databases](#style-guide-mcp-toolbox-for-databases) - [AlloyDB Admin API using MCP | MCP Toolbox for Databases](#alloydb-admin-api-using-mcp-mcp-toolbox-for-databases) - [Style Guide | MCP Toolbox for Databases](#style-guide-mcp-toolbox-for-databases) - [Connect from your IDE | MCP Toolbox for Databases](#connect-from-your-ide-mcp-toolbox-for-databases) - [AlloyDB Admin API using MCP | MCP Toolbox for Databases](#alloydb-admin-api-using-mcp-mcp-toolbox-for-databases) - [Configuration | MCP Toolbox for Databases](#configuration-mcp-toolbox-for-databases) - [How-to | MCP Toolbox for Databases](#how-to-mcp-toolbox-for-databases) - [AlloyDB Admin API using MCP | MCP Toolbox for Databases](#alloydb-admin-api-using-mcp-mcp-toolbox-for-databases) - [How-to | MCP Toolbox for Databases](#how-to-mcp-toolbox-for-databases) - [AlloyDB Admin API using MCP | MCP Toolbox for Databases](#alloydb-admin-api-using-mcp-mcp-toolbox-for-databases) - [AlloyDB Admin API using MCP | MCP Toolbox for Databases](#alloydb-admin-api-using-mcp-mcp-toolbox-for-databases) - [AlloyDB using MCP | MCP Toolbox for Databases](#alloydb-using-mcp-mcp-toolbox-for-databases) - [AlloyDB using MCP | MCP Toolbox for Databases](#alloydb-using-mcp-mcp-toolbox-for-databases) - [Connect from your IDE | MCP Toolbox for Databases](#connect-from-your-ide-mcp-toolbox-for-databases) - [Connect from your IDE | MCP Toolbox for Databases](#connect-from-your-ide-mcp-toolbox-for-databases) - [AlloyDB using MCP | MCP Toolbox for Databases](#alloydb-using-mcp-mcp-toolbox-for-databases) - [AlloyDB using MCP | MCP Toolbox for Databases](#alloydb-using-mcp-mcp-toolbox-for-databases) - [AlloyDB using MCP | MCP Toolbox for Databases](#alloydb-using-mcp-mcp-toolbox-for-databases) - [AlloyDB Admin API using MCP | MCP Toolbox for Databases](#alloydb-admin-api-using-mcp-mcp-toolbox-for-databases) - [AlloyDB Admin API using MCP | MCP Toolbox for Databases](#alloydb-admin-api-using-mcp-mcp-toolbox-for-databases) - [BigQuery using MCP | MCP Toolbox for Databases](#bigquery-using-mcp-mcp-toolbox-for-databases) - [BigQuery using MCP | MCP Toolbox for Databases](#bigquery-using-mcp-mcp-toolbox-for-databases) - [BigQuery using MCP | MCP Toolbox for Databases](#bigquery-using-mcp-mcp-toolbox-for-databases) - [BigQuery using MCP | MCP Toolbox for Databases](#bigquery-using-mcp-mcp-toolbox-for-databases) - [BigQuery using MCP | MCP Toolbox for Databases](#bigquery-using-mcp-mcp-toolbox-for-databases) - [AlloyDB using MCP | MCP Toolbox for Databases](#alloydb-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-using-mcp-mcp-toolbox-for-databases) - [AlloyDB using MCP | MCP Toolbox for Databases](#alloydb-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-using-mcp-mcp-toolbox-for-databases) - [BigQuery using MCP | MCP Toolbox for Databases](#bigquery-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for Postgres using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgres-using-mcp-mcp-toolbox-for-databases) - [BigQuery using MCP | MCP Toolbox for Databases](#bigquery-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for Postgres using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgres-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for Postgres using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgres-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for Postgres using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgres-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for Postgres using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgres-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-using-mcp-mcp-toolbox-for-databases) - [Firestore using MCP | MCP Toolbox for Databases](#firestore-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for Postgres using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgres-using-mcp-mcp-toolbox-for-databases) - [Firestore using MCP | MCP Toolbox for Databases](#firestore-using-mcp-mcp-toolbox-for-databases) - [Firestore using MCP | MCP Toolbox for Databases](#firestore-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for Postgres using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgres-using-mcp-mcp-toolbox-for-databases) - [Firestore using MCP | MCP Toolbox for Databases](#firestore-using-mcp-mcp-toolbox-for-databases) - [Firestore using MCP | MCP Toolbox for Databases](#firestore-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-using-mcp-mcp-toolbox-for-databases) - [Looker using MCP | MCP Toolbox for Databases](#looker-using-mcp-mcp-toolbox-for-databases) - [Looker using MCP | MCP Toolbox for Databases](#looker-using-mcp-mcp-toolbox-for-databases) - [Looker using MCP | MCP Toolbox for Databases](#looker-using-mcp-mcp-toolbox-for-databases) - [Looker using MCP | MCP Toolbox for Databases](#looker-using-mcp-mcp-toolbox-for-databases) - [Looker using MCP | MCP Toolbox for Databases](#looker-using-mcp-mcp-toolbox-for-databases) - [Firestore using MCP | MCP Toolbox for Databases](#firestore-using-mcp-mcp-toolbox-for-databases) - [Firestore using MCP | MCP Toolbox for Databases](#firestore-using-mcp-mcp-toolbox-for-databases) - [MySQL using MCP | MCP Toolbox for Databases](#mysql-using-mcp-mcp-toolbox-for-databases) - [MySQL using MCP | MCP Toolbox for Databases](#mysql-using-mcp-mcp-toolbox-for-databases) - [MySQL using MCP | MCP Toolbox for Databases](#mysql-using-mcp-mcp-toolbox-for-databases) - [MySQL using MCP | MCP Toolbox for Databases](#mysql-using-mcp-mcp-toolbox-for-databases) - [MySQL using MCP | MCP Toolbox for Databases](#mysql-using-mcp-mcp-toolbox-for-databases) - [Looker using MCP | MCP Toolbox for Databases](#looker-using-mcp-mcp-toolbox-for-databases) - [Looker using MCP | MCP Toolbox for Databases](#looker-using-mcp-mcp-toolbox-for-databases) - [Neo4j using MCP | MCP Toolbox for Databases](#neo4j-using-mcp-mcp-toolbox-for-databases) - [Neo4j using MCP | MCP Toolbox for Databases](#neo4j-using-mcp-mcp-toolbox-for-databases) - [Neo4j using MCP | MCP Toolbox for Databases](#neo4j-using-mcp-mcp-toolbox-for-databases) - [Neo4j using MCP | MCP Toolbox for Databases](#neo4j-using-mcp-mcp-toolbox-for-databases) - [MySQL using MCP | MCP Toolbox for Databases](#mysql-using-mcp-mcp-toolbox-for-databases) - [Neo4j using MCP | MCP Toolbox for Databases](#neo4j-using-mcp-mcp-toolbox-for-databases) - [PostgreSQL using MCP | MCP Toolbox for Databases](#postgresql-using-mcp-mcp-toolbox-for-databases) - [PostgreSQL using MCP | MCP Toolbox for Databases](#postgresql-using-mcp-mcp-toolbox-for-databases) - [MySQL using MCP | MCP Toolbox for Databases](#mysql-using-mcp-mcp-toolbox-for-databases) - [PostgreSQL using MCP | MCP Toolbox for Databases](#postgresql-using-mcp-mcp-toolbox-for-databases) - [Spanner using MCP | MCP Toolbox for Databases](#spanner-using-mcp-mcp-toolbox-for-databases) - [PostgreSQL using MCP | MCP Toolbox for Databases](#postgresql-using-mcp-mcp-toolbox-for-databases) - [PostgreSQL using MCP | MCP Toolbox for Databases](#postgresql-using-mcp-mcp-toolbox-for-databases) - [Spanner using MCP | MCP Toolbox for Databases](#spanner-using-mcp-mcp-toolbox-for-databases) - [Spanner using MCP | MCP Toolbox for Databases](#spanner-using-mcp-mcp-toolbox-for-databases) - [Spanner using MCP | MCP Toolbox for Databases](#spanner-using-mcp-mcp-toolbox-for-databases) - [Neo4j using MCP | MCP Toolbox for Databases](#neo4j-using-mcp-mcp-toolbox-for-databases) - [Spanner using MCP | MCP Toolbox for Databases](#spanner-using-mcp-mcp-toolbox-for-databases) - [Neo4j using MCP | MCP Toolbox for Databases](#neo4j-using-mcp-mcp-toolbox-for-databases) - [PostgreSQL using MCP | MCP Toolbox for Databases](#postgresql-using-mcp-mcp-toolbox-for-databases) - [SQL Server using MCP | MCP Toolbox for Databases](#sql-server-using-mcp-mcp-toolbox-for-databases) - [SQL Server using MCP | MCP Toolbox for Databases](#sql-server-using-mcp-mcp-toolbox-for-databases) - [SQLite using MCP | MCP Toolbox for Databases](#sqlite-using-mcp-mcp-toolbox-for-databases) - [SQLite using MCP | MCP Toolbox for Databases](#sqlite-using-mcp-mcp-toolbox-for-databases) - [Oracle using MCP | MCP Toolbox for Databases](#oracle-using-mcp-mcp-toolbox-for-databases) - [SQL Server using MCP | MCP Toolbox for Databases](#sql-server-using-mcp-mcp-toolbox-for-databases) - [SQL Server using MCP | MCP Toolbox for Databases](#sql-server-using-mcp-mcp-toolbox-for-databases) - [SQL Server using MCP | MCP Toolbox for Databases](#sql-server-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgresql-admin-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-admin-using-mcp-mcp-toolbox-for-databases) - [SQLite using MCP | MCP Toolbox for Databases](#sqlite-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgresql-admin-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-admin-using-mcp-mcp-toolbox-for-databases) - [Spanner using MCP | MCP Toolbox for Databases](#spanner-using-mcp-mcp-toolbox-for-databases) - [SQLite using MCP | MCP Toolbox for Databases](#sqlite-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-admin-using-mcp-mcp-toolbox-for-databases) - [Connect via Gemini CLI Extensions | MCP Toolbox for Databases](#connect-via-gemini-cli-extensions-mcp-toolbox-for-databases) - [Connect via MCP Client | MCP Toolbox for Databases](#connect-via-mcp-client-mcp-toolbox-for-databases) - [Toolbox UI | MCP Toolbox for Databases](#toolbox-ui-mcp-toolbox-for-databases) - [SQLite using MCP | MCP Toolbox for Databases](#sqlite-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgresql-admin-using-mcp-mcp-toolbox-for-databases) - [Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases](#deploy-adk-agent-and-mcp-toolbox-mcp-toolbox-for-databases) - [Connect via MCP Client | MCP Toolbox for Databases](#connect-via-mcp-client-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-admin-using-mcp-mcp-toolbox-for-databases) - [Deploy to Cloud Run | MCP Toolbox for Databases](#deploy-to-cloud-run-mcp-toolbox-for-databases) - [Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgresql-admin-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-admin-using-mcp-mcp-toolbox-for-databases) - [Connect via Gemini CLI Extensions | MCP Toolbox for Databases](#connect-via-gemini-cli-extensions-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-admin-using-mcp-mcp-toolbox-for-databases) - [Toolbox UI | MCP Toolbox for Databases](#toolbox-ui-mcp-toolbox-for-databases) - [Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-admin-using-mcp-mcp-toolbox-for-databases) - [Toolbox UI | MCP Toolbox for Databases](#toolbox-ui-mcp-toolbox-for-databases) - [Deploy to Kubernetes | MCP Toolbox for Databases](#deploy-to-kubernetes-mcp-toolbox-for-databases) - [Connect via MCP Client | MCP Toolbox for Databases](#connect-via-mcp-client-mcp-toolbox-for-databases) - [Connect via Gemini CLI Extensions | MCP Toolbox for Databases](#connect-via-gemini-cli-extensions-mcp-toolbox-for-databases) - [Deploy to Cloud Run | MCP Toolbox for Databases](#deploy-to-cloud-run-mcp-toolbox-for-databases) - [Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases](#deploy-adk-agent-and-mcp-toolbox-mcp-toolbox-for-databases) - [PostgreSQL using MCP | MCP Toolbox for Databases](#postgresql-using-mcp-mcp-toolbox-for-databases) - [Deploy to Cloud Run | MCP Toolbox for Databases](#deploy-to-cloud-run-mcp-toolbox-for-databases) - [Deploy to Kubernetes | MCP Toolbox for Databases](#deploy-to-kubernetes-mcp-toolbox-for-databases) - [Deploy using Docker Compose | MCP Toolbox for Databases](#deploy-using-docker-compose-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-admin-using-mcp-mcp-toolbox-for-databases) - [Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases](#deploy-adk-agent-and-mcp-toolbox-mcp-toolbox-for-databases) - [Toolbox UI | MCP Toolbox for Databases](#toolbox-ui-mcp-toolbox-for-databases) - [Connect via MCP Client | MCP Toolbox for Databases](#connect-via-mcp-client-mcp-toolbox-for-databases) - [Connect via Gemini CLI Extensions | MCP Toolbox for Databases](#connect-via-gemini-cli-extensions-mcp-toolbox-for-databases) - [SQL Server using MCP | MCP Toolbox for Databases](#sql-server-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgresql-admin-using-mcp-mcp-toolbox-for-databases) - [Export Telemetry | MCP Toolbox for Databases](#export-telemetry-mcp-toolbox-for-databases) - [Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases](#deploy-adk-agent-and-mcp-toolbox-mcp-toolbox-for-databases) - [Deploy to Cloud Run | MCP Toolbox for Databases](#deploy-to-cloud-run-mcp-toolbox-for-databases) - [Deploy using Docker Compose | MCP Toolbox for Databases](#deploy-using-docker-compose-mcp-toolbox-for-databases) - [Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-admin-using-mcp-mcp-toolbox-for-databases) - [Deploy to Kubernetes | MCP Toolbox for Databases](#deploy-to-kubernetes-mcp-toolbox-for-databases) - [Spanner using MCP | MCP Toolbox for Databases](#spanner-using-mcp-mcp-toolbox-for-databases) - [Resources | MCP Toolbox for Databases](#resources-mcp-toolbox-for-databases) - [Export Telemetry | MCP Toolbox for Databases](#export-telemetry-mcp-toolbox-for-databases) - [Deploy to Kubernetes | MCP Toolbox for Databases](#deploy-to-kubernetes-mcp-toolbox-for-databases) - [Deploy using Docker Compose | MCP Toolbox for Databases](#deploy-using-docker-compose-mcp-toolbox-for-databases) - [Export Telemetry | MCP Toolbox for Databases](#export-telemetry-mcp-toolbox-for-databases) - [SQL Server using MCP | MCP Toolbox for Databases](#sql-server-using-mcp-mcp-toolbox-for-databases) - [Google Sign-In | MCP Toolbox for Databases](#google-sign-in-mcp-toolbox-for-databases) - [AlloyDB Admin | MCP Toolbox for Databases](#alloydb-admin-mcp-toolbox-for-databases) - [Resources | MCP Toolbox for Databases](#resources-mcp-toolbox-for-databases) - [Sources | MCP Toolbox for Databases](#sources-mcp-toolbox-for-databases) - [Bigtable | MCP Toolbox for Databases](#bigtable-mcp-toolbox-for-databases) - [AlloyDB for PostgreSQL | MCP Toolbox for Databases](#alloydb-for-postgresql-mcp-toolbox-for-databases) - [Cassandra | MCP Toolbox for Databases](#cassandra-mcp-toolbox-for-databases) - [AuthServices | MCP Toolbox for Databases](#authservices-mcp-toolbox-for-databases) - [ClickHouse | MCP Toolbox for Databases](#clickhouse-mcp-toolbox-for-databases) - [Connect via MCP Client | MCP Toolbox for Databases](#connect-via-mcp-client-mcp-toolbox-for-databases) - [BigQuery | MCP Toolbox for Databases](#bigquery-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-admin-using-mcp-mcp-toolbox-for-databases) - [Resources | MCP Toolbox for Databases](#resources-mcp-toolbox-for-databases) - [Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgresql-admin-using-mcp-mcp-toolbox-for-databases) - [SQLite using MCP | MCP Toolbox for Databases](#sqlite-using-mcp-mcp-toolbox-for-databases) - [Connect via Gemini CLI Extensions | MCP Toolbox for Databases](#connect-via-gemini-cli-extensions-mcp-toolbox-for-databases) - [Google Sign-In | MCP Toolbox for Databases](#google-sign-in-mcp-toolbox-for-databases) - [Toolbox UI | MCP Toolbox for Databases](#toolbox-ui-mcp-toolbox-for-databases) - [AlloyDB Admin | MCP Toolbox for Databases](#alloydb-admin-mcp-toolbox-for-databases) - [Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-admin-using-mcp-mcp-toolbox-for-databases) - [Export Telemetry | MCP Toolbox for Databases](#export-telemetry-mcp-toolbox-for-databases) - [Deploy using Docker Compose | MCP Toolbox for Databases](#deploy-using-docker-compose-mcp-toolbox-for-databases) - [Sources | MCP Toolbox for Databases](#sources-mcp-toolbox-for-databases) - [Bigtable | MCP Toolbox for Databases](#bigtable-mcp-toolbox-for-databases) - [Connect via MCP Client | MCP Toolbox for Databases](#connect-via-mcp-client-mcp-toolbox-for-databases) - [AuthServices | MCP Toolbox for Databases](#authservices-mcp-toolbox-for-databases) - [AlloyDB for PostgreSQL | MCP Toolbox for Databases](#alloydb-for-postgresql-mcp-toolbox-for-databases) - [Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-postgresql-admin-using-mcp-mcp-toolbox-for-databases) - [SQLite using MCP | MCP Toolbox for Databases](#sqlite-using-mcp-mcp-toolbox-for-databases) - [Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases](#deploy-adk-agent-and-mcp-toolbox-mcp-toolbox-for-databases) - [AlloyDB Admin | MCP Toolbox for Databases](#alloydb-admin-mcp-toolbox-for-databases) - [Google Sign-In | MCP Toolbox for Databases](#google-sign-in-mcp-toolbox-for-databases) - [Cassandra | MCP Toolbox for Databases](#cassandra-mcp-toolbox-for-databases) - [ClickHouse | MCP Toolbox for Databases](#clickhouse-mcp-toolbox-for-databases) - [Sources | MCP Toolbox for Databases](#sources-mcp-toolbox-for-databases) - [Bigtable | MCP Toolbox for Databases](#bigtable-mcp-toolbox-for-databases) - [BigQuery | MCP Toolbox for Databases](#bigquery-mcp-toolbox-for-databases) - [Cloud Healthcare API | MCP Toolbox for Databases](#cloud-healthcare-api-mcp-toolbox-for-databases) - [Toolbox UI | MCP Toolbox for Databases](#toolbox-ui-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-admin-using-mcp-mcp-toolbox-for-databases) - [Deploy to Cloud Run | MCP Toolbox for Databases](#deploy-to-cloud-run-mcp-toolbox-for-databases) - [Connect via Gemini CLI Extensions | MCP Toolbox for Databases](#connect-via-gemini-cli-extensions-mcp-toolbox-for-databases) - [AlloyDB for PostgreSQL | MCP Toolbox for Databases](#alloydb-for-postgresql-mcp-toolbox-for-databases) - [AuthServices | MCP Toolbox for Databases](#authservices-mcp-toolbox-for-databases) - [Cassandra | MCP Toolbox for Databases](#cassandra-mcp-toolbox-for-databases) - [ClickHouse | MCP Toolbox for Databases](#clickhouse-mcp-toolbox-for-databases) - [Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-mysql-admin-using-mcp-mcp-toolbox-for-databases) - [Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases](#cloud-sql-for-sql-server-admin-using-mcp-mcp-toolbox-for-databases) --- # Documentation | MCP Toolbox for Databases Documentation ============= A complete documentation guide for MCP Toolbox * * * ##### [Introduction](https://mcp-toolbox.dev/documentation/introduction/) An introduction to MCP Toolbox for Databases. ##### [Getting Started](https://mcp-toolbox.dev/documentation/getting-started/) Understand the core concepts of MCP Toolbox, explore integration strategies, and learn how to architect your AI agent connections. ##### [Configuration](https://mcp-toolbox.dev/documentation/configuration/) How to configure Toolbox’s tools.yaml file. ##### [Connect to Toolbox](https://mcp-toolbox.dev/documentation/connect-to/) Learn how to connect your applications, AI agents, CLIs, and IDEs to MCP Toolbox. ##### [Deploy Toolbox](https://mcp-toolbox.dev/documentation/deploy-to/) Learn how to deploy the MCP Toolbox server to production environments. ##### [Monitoring & Observability](https://mcp-toolbox.dev/documentation/monitoring/) Learn how to monitor, log, and trace the internal state of the MCP Toolbox. * * * Feedback -------- Was this page helpful? Yes No Glad to hear it! Please [tell us how we can improve](https://github.com/googleapis/mcp-toolbox/issues/new) . Sorry to hear that. Please [tell us how we can improve](https://github.com/googleapis/mcp-toolbox/issues/new) . Last modified April 13, 2026: [chore(main): release 1.1.0 (#3024) (da6f5f8)](https://github.com/googleapis/mcp-toolbox/commit/da6f5f8a15400d8b14e54c01a23f51601a584b7f) --- # Getting Started | MCP Toolbox for Databases Getting Started =============== How to get started with Toolbox. * * * ##### [Introduction](https://mcp-toolbox.dev/v0.24.0/getting-started/introduction/) An introduction to MCP Toolbox for Databases. ##### [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.24.0/getting-started/local_quickstart/) How to get started running Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . ##### [JS Quickstart (Local)](https://mcp-toolbox.dev/v0.24.0/getting-started/local_quickstart_js/) How to get started running Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . ##### [Go Quickstart (Local)](https://mcp-toolbox.dev/v0.24.0/getting-started/local_quickstart_go/) How to get started running Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . ##### [Prompts using Gemini CLI](https://mcp-toolbox.dev/v0.24.0/getting-started/prompts_quickstart_gemini_cli/) How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . ##### [Quickstart (MCP)](https://mcp-toolbox.dev/v0.24.0/getting-started/mcp_quickstart/) How to get started running Toolbox locally with MCP Inspector. ##### [Configuration](https://mcp-toolbox.dev/v0.24.0/getting-started/configure/) How to configure Toolbox’s tools.yaml file. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Introduction | MCP Toolbox for Databases Introduction ============ An introduction to MCP Toolbox for Databases. MCP Toolbox for Databases is an open source MCP server for databases. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more. Note This solution was originally named “Gen AI Toolbox for Databases” as its initial development predated MCP, but was renamed to align with recently added MCP compatibility. Why Toolbox? ------------ Toolbox helps you build Gen AI tools that let your agents access data in your database. Toolbox provides: * **Simplified development**: Integrate tools to your agent in less than 10 lines of code, reuse tools between multiple agents or frameworks, and deploy new versions of tools more easily. * **Better performance**: Best practices such as connection pooling, authentication, and more. * **Enhanced security**: Integrated auth for more secure access to your data * **End-to-end observability**: Out of the box metrics and tracing with built-in support for OpenTelemetry. **⚡ Supercharge Your Workflow with an AI Database Assistant ⚡** Stop context-switching and let your AI assistant become a true co-developer. By [connecting your IDE to your databases with MCP Toolbox](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/) , you can delegate complex and time-consuming database tasks, allowing you to build faster and focus on what matters. This isn’t just about code completion; it’s about giving your AI the context it needs to handle the entire development lifecycle. Here’s how it will save you time: * **Query in Plain English**: Interact with your data using natural language right from your IDE. Ask complex questions like, _“How many orders were delivered in 2024, and what items were in them?”_ without writing any SQL. * **Automate Database Management**: Simply describe your data needs, and let the AI assistant manage your database for you. It can handle generating queries, creating tables, adding indexes, and more. * **Generate Context-Aware Code**: Empower your AI assistant to generate application code and tests with a deep understanding of your real-time database schema. This accelerates the development cycle by ensuring the generated code is directly usable. * **Slash Development Overhead**: Radically reduce the time spent on manual setup and boilerplate. MCP Toolbox helps streamline lengthy database configurations, repetitive code, and error-prone schema migrations. Learn [how to connect your AI tools (IDEs) to Toolbox using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/) . General Architecture -------------------- Toolbox sits between your application’s orchestration framework and your database, providing a control plane that is used to modify, distribute, or invoke tools. It simplifies the management of your tools by providing you with a centralized location to store and update tools, allowing you to share tools between agents and applications and update those tools without necessarily redeploying your application. ![architecture](https://mcp-toolbox.dev/v0.24.0/getting-started/introduction/architecture.png) Getting Started --------------- ### (Non-production) Running Toolbox You can run Toolbox directly with a [configuration file](https://mcp-toolbox.dev/v0.24.0/getting-started/configure/) : npx @toolbox-sdk/server --tools-file tools.yaml This runs the latest version of the toolbox server with your configuration file. Note This method should only be used for non-production use cases such as experimentation. For any production use-cases, please consider [Installing the server](https://mcp-toolbox.dev/v0.24.0/#installing-the-server) and then [running it](https://mcp-toolbox.dev/v0.24.0/#running-the-server) . ### Installing the server For the latest version, check the [releases page](https://github.com/googleapis/genai-toolbox/releases) and use the following instructions for your OS and CPU architecture. * Binary * Container image * Homebrew * Compile from source * Linux (AMD64) * macOS (Apple Silicon) * macOS (Intel) * Windows (Command Prompt) * Windows (PowerShell) To install Toolbox as a binary on Linux (AMD64): # see releases page for other versions export VERSION=0.24.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Apple Silicon): # see releases page for other versions export VERSION=0.24.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Intel): # see releases page for other versions export VERSION=0.24.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on Windows (Command Prompt): :: see releases page for other versions set VERSION=0.24.0 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe" To install Toolbox as a binary on Windows (PowerShell): # see releases page for other versions $VERSION = "0.24.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe" You can also install Toolbox as a container: # see releases page for other versions export VERSION=0.24.0 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION To install Toolbox using Homebrew on macOS or Linux: brew install mcp-toolbox To install from source, ensure you have the latest version of [Go installed](https://go.dev/doc/install) , and then run the following command: go install github.com/googleapis/[email protected] ### Running the server [Configure](https://mcp-toolbox.dev/v0.24.0/getting-started/configure/) a `tools.yaml` to define your tools, and then execute `toolbox` to start the server: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. #### Launching Toolbox UI To launch Toolbox’s interactive UI, use the `--ui` flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit [Toolbox UI](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/) . ./toolbox --ui #### Homebrew Users If you installed Toolbox using Homebrew, the `toolbox` binary is available in your system path. You can start the server with the same command: toolbox --tools-file "tools.yaml" You can use `toolbox help` for a full list of flags! To stop the server, send a terminate signal (`ctrl+c` on most platforms). For more detailed documentation on deploying to different environments, check out the resources in the [How-to section](https://mcp-toolbox.dev/v0.24.0/how-to/) ### Integrating your application Once your server is up and running, you can load the tools into your application. See below the list of Client SDKs for using various frameworks: #### Python * Core * LangChain * Llamaindex Once you’ve installed the [Toolbox Core SDK](https://pypi.org/project/toolbox-core/) , you can load tools: from toolbox_core import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = await client.load_toolset("toolset_name") For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) . Once you’ve installed the [Toolbox LangChain SDK](https://pypi.org/project/toolbox-langchain/) , you can load tools: from toolbox_langchain import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset() For more detailed instructions on using the Toolbox LangChain SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) . Once you’ve installed the [Toolbox Llamaindex SDK](https://github.com/googleapis/genai-toolbox-llamaindex-python) , you can load tools: from toolbox_llamaindex import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application tools = client.load_toolset() For more detailed instructions on using the Toolbox Llamaindex SDK, see the [project’s README](https://github.com/googleapis/genai-toolbox-llamaindex-python/blob/main/README.md) . #### Javascript/Typescript Once you’ve installed the [Toolbox Core SDK](https://www.npmjs.com/package/@toolbox-sdk/core) , you can load tools: * Core * LangChain/Langraph * Genkit * LlamaIndex * ADK TS import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(currTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); // Use these tools in your Langchain/Langraph applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { genkit } from 'genkit'; // Initialise genkit const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => ai.defineTool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }, toolboxTool) // Use these tools in your Genkit applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { tool } from "llamaindex"; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool });; // Use these tools in your LlamaIndex applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/adk'; // Replace with the actual URL where your Toolbox service is running const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const tools = await client.loadToolset(); // Use the client and tools as per requirement For detailed samples on using the Toolbox JS SDK with ADK JS, see the [project’s README.](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main/packages/toolbox-adk/README.md) #### Go Once you’ve installed the [Toolbox Go SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: * Core * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" ) func main() { // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tools tools, err := client.LoadToolset("toolsetName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } } package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with LangChainGo langChainTool := llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with LangChain Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "encoding/json" "log" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/invopop/jsonschema" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() g, err := genkit.Init(ctx) client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Convert the tool using the tbgenkit package // Use this tool with Genkit Go genkitTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } } For end-to-end samples on using the Toolbox Go SDK with Genkit Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit/samples) package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var schema *genai.Schema _ = json.Unmarshal(inputschema, &schema) funcDeclaration := &genai.FunctionDeclaration{ Name: tool.Name(), Description: tool.Description(), Parameters: schema, } // Use this tool with Go GenAI genAITool := &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } For end-to-end samples on using the Toolbox Go SDK with Go GenAI, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema openai.FunctionParameters _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with OpenAI Go openAITool := openai.ChatCompletionToolParam{ Function: openai.FunctionDefinitionParam{ Name: tool.Name(), Description: openai.String(tool.Description()), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with OpenAI Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "fmt" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := tbadk.NewToolboxClient(URL) if err != nil { return fmt.Sprintln("Could not start Toolbox Client", err) } // Use this tool with ADK Go tool, err := client.LoadTool("toolName", ctx) if err != nil { return fmt.Sprintln("Could not load Toolbox Tool", err) } } For end-to-end samples on using the Toolbox Go SDK with ADK Go, see the [project’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbadk/samples) For more detailed instructions on using the Toolbox Go SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md) . Last modified December 19, 2025: [chore(main): release 0.24.0 (#2162) (f520b4ed8ae)](https://github.com/googleapis/genai-toolbox/commit/f520b4ed8aedc28147777bdb673a576092a53513) --- # Getting Started | MCP Toolbox for Databases Getting Started =============== How to get started with Toolbox. * * * ##### [Introduction](https://mcp-toolbox.dev/v0.26.0/getting-started/introduction/) An introduction to MCP Toolbox for Databases. ##### [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.26.0/getting-started/local_quickstart/) How to get started running Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . ##### [JS Quickstart (Local)](https://mcp-toolbox.dev/v0.26.0/getting-started/local_quickstart_js/) How to get started running Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . ##### [Go Quickstart (Local)](https://mcp-toolbox.dev/v0.26.0/getting-started/local_quickstart_go/) How to get started running Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . ##### [Prompts using Gemini CLI](https://mcp-toolbox.dev/v0.26.0/getting-started/prompts_quickstart_gemini_cli/) How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . ##### [Quickstart (MCP)](https://mcp-toolbox.dev/v0.26.0/getting-started/mcp_quickstart/) How to get started running Toolbox locally with MCP Inspector. ##### [Configuration](https://mcp-toolbox.dev/v0.26.0/getting-started/configure/) How to configure Toolbox’s tools.yaml file. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Getting Started | MCP Toolbox for Databases Getting Started =============== How to get started with Toolbox. * * * ##### [Introduction](https://mcp-toolbox.dev/v0.27.0/getting-started/introduction/) An introduction to MCP Toolbox for Databases. ##### [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.27.0/getting-started/local_quickstart/) How to get started running Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . ##### [JS Quickstart (Local)](https://mcp-toolbox.dev/v0.27.0/getting-started/local_quickstart_js/) How to get started running Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . ##### [Go Quickstart (Local)](https://mcp-toolbox.dev/v0.27.0/getting-started/local_quickstart_go/) How to get started running Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . ##### [Prompts using Gemini CLI](https://mcp-toolbox.dev/v0.27.0/getting-started/prompts_quickstart_gemini_cli/) How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . ##### [Quickstart (MCP)](https://mcp-toolbox.dev/v0.27.0/getting-started/mcp_quickstart/) How to get started running Toolbox locally with MCP Inspector. ##### [Configuration](https://mcp-toolbox.dev/v0.27.0/getting-started/configure/) How to configure Toolbox’s tools.yaml file. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Introduction | MCP Toolbox for Databases Introduction ============ An introduction to MCP Toolbox for Databases. MCP Toolbox for Databases is an open source MCP server for databases. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more. Note This solution was originally named “Gen AI Toolbox for Databases” as its initial development predated MCP, but was renamed to align with recently added MCP compatibility. Why Toolbox? ------------ Toolbox helps you build Gen AI tools that let your agents access data in your database. Toolbox provides: * **Simplified development**: Integrate tools to your agent in less than 10 lines of code, reuse tools between multiple agents or frameworks, and deploy new versions of tools more easily. * **Better performance**: Best practices such as connection pooling, authentication, and more. * **Enhanced security**: Integrated auth for more secure access to your data * **End-to-end observability**: Out of the box metrics and tracing with built-in support for OpenTelemetry. **⚡ Supercharge Your Workflow with an AI Database Assistant ⚡** Stop context-switching and let your AI assistant become a true co-developer. By [connecting your IDE to your databases with MCP Toolbox](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/) , you can delegate complex and time-consuming database tasks, allowing you to build faster and focus on what matters. This isn’t just about code completion; it’s about giving your AI the context it needs to handle the entire development lifecycle. Here’s how it will save you time: * **Query in Plain English**: Interact with your data using natural language right from your IDE. Ask complex questions like, _“How many orders were delivered in 2024, and what items were in them?”_ without writing any SQL. * **Automate Database Management**: Simply describe your data needs, and let the AI assistant manage your database for you. It can handle generating queries, creating tables, adding indexes, and more. * **Generate Context-Aware Code**: Empower your AI assistant to generate application code and tests with a deep understanding of your real-time database schema. This accelerates the development cycle by ensuring the generated code is directly usable. * **Slash Development Overhead**: Radically reduce the time spent on manual setup and boilerplate. MCP Toolbox helps streamline lengthy database configurations, repetitive code, and error-prone schema migrations. Learn [how to connect your AI tools (IDEs) to Toolbox using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/) . General Architecture -------------------- Toolbox sits between your application’s orchestration framework and your database, providing a control plane that is used to modify, distribute, or invoke tools. It simplifies the management of your tools by providing you with a centralized location to store and update tools, allowing you to share tools between agents and applications and update those tools without necessarily redeploying your application. ![architecture](https://mcp-toolbox.dev/v0.25.0/getting-started/introduction/architecture.png) Getting Started --------------- ### (Non-production) Running Toolbox You can run Toolbox directly with a [configuration file](https://mcp-toolbox.dev/v0.25.0/getting-started/configure/) : npx @toolbox-sdk/server --tools-file tools.yaml This runs the latest version of the toolbox server with your configuration file. Note This method should only be used for non-production use cases such as experimentation. For any production use-cases, please consider [Installing the server](https://mcp-toolbox.dev/v0.25.0/#installing-the-server) and then [running it](https://mcp-toolbox.dev/v0.25.0/#running-the-server) . ### Installing the server For the latest version, check the [releases page](https://github.com/googleapis/genai-toolbox/releases) and use the following instructions for your OS and CPU architecture. * Binary * Container image * Homebrew * Compile from source * Linux (AMD64) * macOS (Apple Silicon) * macOS (Intel) * Windows (Command Prompt) * Windows (PowerShell) To install Toolbox as a binary on Linux (AMD64): # see releases page for other versions export VERSION=0.25.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Apple Silicon): # see releases page for other versions export VERSION=0.25.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Intel): # see releases page for other versions export VERSION=0.25.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on Windows (Command Prompt): :: see releases page for other versions set VERSION=0.25.0 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe" To install Toolbox as a binary on Windows (PowerShell): # see releases page for other versions $VERSION = "0.25.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe" You can also install Toolbox as a container: # see releases page for other versions export VERSION=0.25.0 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION To install Toolbox using Homebrew on macOS or Linux: brew install mcp-toolbox To install from source, ensure you have the latest version of [Go installed](https://go.dev/doc/install) , and then run the following command: go install github.com/googleapis/[email protected] ### Running the server [Configure](https://mcp-toolbox.dev/v0.25.0/getting-started/configure/) a `tools.yaml` to define your tools, and then execute `toolbox` to start the server: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. #### Launching Toolbox UI To launch Toolbox’s interactive UI, use the `--ui` flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit [Toolbox UI](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/) . ./toolbox --ui #### Homebrew Users If you installed Toolbox using Homebrew, the `toolbox` binary is available in your system path. You can start the server with the same command: toolbox --tools-file "tools.yaml" You can use `toolbox help` for a full list of flags! To stop the server, send a terminate signal (`ctrl+c` on most platforms). For more detailed documentation on deploying to different environments, check out the resources in the [How-to section](https://mcp-toolbox.dev/v0.25.0/how-to/) ### Integrating your application Once your server is up and running, you can load the tools into your application. See below the list of Client SDKs for using various frameworks: #### Python * Core * LangChain * Llamaindex Once you’ve installed the [Toolbox Core SDK](https://pypi.org/project/toolbox-core/) , you can load tools: from toolbox_core import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = await client.load_toolset("toolset_name") For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) . Once you’ve installed the [Toolbox LangChain SDK](https://pypi.org/project/toolbox-langchain/) , you can load tools: from toolbox_langchain import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset() For more detailed instructions on using the Toolbox LangChain SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) . Once you’ve installed the [Toolbox Llamaindex SDK](https://github.com/googleapis/genai-toolbox-llamaindex-python) , you can load tools: from toolbox_llamaindex import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application tools = client.load_toolset() For more detailed instructions on using the Toolbox Llamaindex SDK, see the [project’s README](https://github.com/googleapis/genai-toolbox-llamaindex-python/blob/main/README.md) . #### Javascript/Typescript Once you’ve installed the [Toolbox Core SDK](https://www.npmjs.com/package/@toolbox-sdk/core) , you can load tools: * Core * LangChain/Langraph * Genkit * LlamaIndex * ADK TS import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(currTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); // Use these tools in your Langchain/Langraph applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { genkit } from 'genkit'; // Initialise genkit const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => ai.defineTool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }, toolboxTool) // Use these tools in your Genkit applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { tool } from "llamaindex"; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool });; // Use these tools in your LlamaIndex applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/adk'; // Replace with the actual URL where your Toolbox service is running const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const tools = await client.loadToolset(); // Use the client and tools as per requirement For detailed samples on using the Toolbox JS SDK with ADK JS, see the [project’s README.](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main/packages/toolbox-adk/README.md) #### Go Once you’ve installed the [Toolbox Go SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: * Core * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" ) func main() { // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tools tools, err := client.LoadToolset("toolsetName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } } package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with LangChainGo langChainTool := llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with LangChain Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "encoding/json" "log" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/invopop/jsonschema" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() g, err := genkit.Init(ctx) client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Convert the tool using the tbgenkit package // Use this tool with Genkit Go genkitTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } } For end-to-end samples on using the Toolbox Go SDK with Genkit Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit/samples) package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var schema *genai.Schema _ = json.Unmarshal(inputschema, &schema) funcDeclaration := &genai.FunctionDeclaration{ Name: tool.Name(), Description: tool.Description(), Parameters: schema, } // Use this tool with Go GenAI genAITool := &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } For end-to-end samples on using the Toolbox Go SDK with Go GenAI, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema openai.FunctionParameters _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with OpenAI Go openAITool := openai.ChatCompletionToolParam{ Function: openai.FunctionDefinitionParam{ Name: tool.Name(), Description: openai.String(tool.Description()), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with OpenAI Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "fmt" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := tbadk.NewToolboxClient(URL) if err != nil { return fmt.Sprintln("Could not start Toolbox Client", err) } // Use this tool with ADK Go tool, err := client.LoadTool("toolName", ctx) if err != nil { return fmt.Sprintln("Could not load Toolbox Tool", err) } } For end-to-end samples on using the Toolbox Go SDK with ADK Go, see the [project’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbadk/samples) For more detailed instructions on using the Toolbox Go SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md) . Last modified January 8, 2026: [chore(main): release 0.25.0 (#2218) (41b518b955a)](https://github.com/googleapis/genai-toolbox/commit/41b518b955af8710c5b9b1aacddcfab63ff505bd) --- # Introduction | MCP Toolbox for Databases Introduction ============ An introduction to MCP Toolbox for Databases. MCP Toolbox for Databases is an open source MCP server for databases. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more. Note This solution was originally named “Gen AI Toolbox for Databases” as its initial development predated MCP, but was renamed to align with recently added MCP compatibility. Why Toolbox? ------------ Toolbox helps you build Gen AI tools that let your agents access data in your database. Toolbox provides: * **Simplified development**: Integrate tools to your agent in less than 10 lines of code, reuse tools between multiple agents or frameworks, and deploy new versions of tools more easily. * **Better performance**: Best practices such as connection pooling, authentication, and more. * **Enhanced security**: Integrated auth for more secure access to your data * **End-to-end observability**: Out of the box metrics and tracing with built-in support for OpenTelemetry. **⚡ Supercharge Your Workflow with an AI Database Assistant ⚡** Stop context-switching and let your AI assistant become a true co-developer. By [connecting your IDE to your databases with MCP Toolbox](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/) , you can delegate complex and time-consuming database tasks, allowing you to build faster and focus on what matters. This isn’t just about code completion; it’s about giving your AI the context it needs to handle the entire development lifecycle. Here’s how it will save you time: * **Query in Plain English**: Interact with your data using natural language right from your IDE. Ask complex questions like, _“How many orders were delivered in 2024, and what items were in them?”_ without writing any SQL. * **Automate Database Management**: Simply describe your data needs, and let the AI assistant manage your database for you. It can handle generating queries, creating tables, adding indexes, and more. * **Generate Context-Aware Code**: Empower your AI assistant to generate application code and tests with a deep understanding of your real-time database schema. This accelerates the development cycle by ensuring the generated code is directly usable. * **Slash Development Overhead**: Radically reduce the time spent on manual setup and boilerplate. MCP Toolbox helps streamline lengthy database configurations, repetitive code, and error-prone schema migrations. Learn [how to connect your AI tools (IDEs) to Toolbox using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/) . General Architecture -------------------- Toolbox sits between your application’s orchestration framework and your database, providing a control plane that is used to modify, distribute, or invoke tools. It simplifies the management of your tools by providing you with a centralized location to store and update tools, allowing you to share tools between agents and applications and update those tools without necessarily redeploying your application. ![architecture](https://mcp-toolbox.dev/v0.26.0/getting-started/introduction/architecture.png) Getting Started --------------- ### (Non-production) Running Toolbox You can run Toolbox directly with a [configuration file](https://mcp-toolbox.dev/v0.26.0/getting-started/configure/) : npx @toolbox-sdk/server --tools-file tools.yaml This runs the latest version of the toolbox server with your configuration file. Note This method should only be used for non-production use cases such as experimentation. For any production use-cases, please consider [Installing the server](https://mcp-toolbox.dev/v0.26.0/#installing-the-server) and then [running it](https://mcp-toolbox.dev/v0.26.0/#running-the-server) . ### Installing the server For the latest version, check the [releases page](https://github.com/googleapis/genai-toolbox/releases) and use the following instructions for your OS and CPU architecture. * Binary * Container image * Homebrew * Compile from source * Linux (AMD64) * macOS (Apple Silicon) * macOS (Intel) * Windows (Command Prompt) * Windows (PowerShell) To install Toolbox as a binary on Linux (AMD64): # see releases page for other versions export VERSION=0.26.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Apple Silicon): # see releases page for other versions export VERSION=0.26.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Intel): # see releases page for other versions export VERSION=0.26.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on Windows (Command Prompt): :: see releases page for other versions set VERSION=0.26.0 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe" To install Toolbox as a binary on Windows (PowerShell): # see releases page for other versions $VERSION = "0.26.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe" You can also install Toolbox as a container: # see releases page for other versions export VERSION=0.26.0 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION To install Toolbox using Homebrew on macOS or Linux: brew install mcp-toolbox To install from source, ensure you have the latest version of [Go installed](https://go.dev/doc/install) , and then run the following command: go install github.com/googleapis/[email protected] ### Running the server [Configure](https://mcp-toolbox.dev/v0.26.0/getting-started/configure/) a `tools.yaml` to define your tools, and then execute `toolbox` to start the server: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. #### Launching Toolbox UI To launch Toolbox’s interactive UI, use the `--ui` flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit [Toolbox UI](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/) . ./toolbox --ui #### Homebrew Users If you installed Toolbox using Homebrew, the `toolbox` binary is available in your system path. You can start the server with the same command: toolbox --tools-file "tools.yaml" You can use `toolbox help` for a full list of flags! To stop the server, send a terminate signal (`ctrl+c` on most platforms). For more detailed documentation on deploying to different environments, check out the resources in the [How-to section](https://mcp-toolbox.dev/v0.26.0/how-to/) ### Integrating your application Once your server is up and running, you can load the tools into your application. See below the list of Client SDKs for using various frameworks: #### Python * Core * LangChain * Llamaindex Once you’ve installed the [Toolbox Core SDK](https://pypi.org/project/toolbox-core/) , you can load tools: from toolbox_core import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = await client.load_toolset("toolset_name") For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) . Once you’ve installed the [Toolbox LangChain SDK](https://pypi.org/project/toolbox-langchain/) , you can load tools: from toolbox_langchain import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset() For more detailed instructions on using the Toolbox LangChain SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) . Once you’ve installed the [Toolbox Llamaindex SDK](https://github.com/googleapis/genai-toolbox-llamaindex-python) , you can load tools: from toolbox_llamaindex import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application tools = client.load_toolset() For more detailed instructions on using the Toolbox Llamaindex SDK, see the [project’s README](https://github.com/googleapis/genai-toolbox-llamaindex-python/blob/main/README.md) . #### Javascript/Typescript Once you’ve installed the [Toolbox Core SDK](https://www.npmjs.com/package/@toolbox-sdk/core) , you can load tools: * Core * LangChain/Langraph * Genkit * LlamaIndex * ADK TS import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(currTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); // Use these tools in your Langchain/Langraph applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { genkit } from 'genkit'; // Initialise genkit const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => ai.defineTool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }, toolboxTool) // Use these tools in your Genkit applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { tool } from "llamaindex"; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool });; // Use these tools in your LlamaIndex applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/adk'; // Replace with the actual URL where your Toolbox service is running const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const tools = await client.loadToolset(); // Use the client and tools as per requirement For detailed samples on using the Toolbox JS SDK with ADK JS, see the [project’s README.](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main/packages/toolbox-adk/README.md) #### Go Once you’ve installed the [Toolbox Go SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: * Core * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" ) func main() { // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tools tools, err := client.LoadToolset("toolsetName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } } package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with LangChainGo langChainTool := llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with LangChain Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "encoding/json" "log" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/invopop/jsonschema" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() g, err := genkit.Init(ctx) client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Convert the tool using the tbgenkit package // Use this tool with Genkit Go genkitTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } } For end-to-end samples on using the Toolbox Go SDK with Genkit Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit/samples) package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var schema *genai.Schema _ = json.Unmarshal(inputschema, &schema) funcDeclaration := &genai.FunctionDeclaration{ Name: tool.Name(), Description: tool.Description(), Parameters: schema, } // Use this tool with Go GenAI genAITool := &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } For end-to-end samples on using the Toolbox Go SDK with Go GenAI, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema openai.FunctionParameters _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with OpenAI Go openAITool := openai.ChatCompletionToolParam{ Function: openai.FunctionDefinitionParam{ Name: tool.Name(), Description: openai.String(tool.Description()), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with OpenAI Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "fmt" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := tbadk.NewToolboxClient(URL) if err != nil { return fmt.Sprintln("Could not start Toolbox Client", err) } // Use this tool with ADK Go tool, err := client.LoadTool("toolName", ctx) if err != nil { return fmt.Sprintln("Could not load Toolbox Tool", err) } } For end-to-end samples on using the Toolbox Go SDK with ADK Go, see the [project’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbadk/samples) For more detailed instructions on using the Toolbox Go SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md) . Last modified January 22, 2026: [chore(main): release 0.26.0 (#2286) (86bf7bf8d06)](https://github.com/googleapis/genai-toolbox/commit/86bf7bf8d068f00adccd7223dd113743aed83ab5) --- # Python Quickstart (Local) | MCP Toolbox for Databases Python Quickstart (Local) ========================= How to get started running Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/getting-started/colab_quickstart.ipynb) Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Python 3.10+](https://wiki.python.org/moin/BeginnersGuide/Download) (including [pip](https://pip.pypa.io/en/stable/installation/) and your preferred virtual environment tool for managing dependencies e.g. [venv](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) ). 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. Tip If you prefer to experiment within a Google Colab environment, you can connect to a [local runtime](https://research.google.com/colaboratory/local-runtimes.html) . 1. In a new terminal, install the SDK package. * ADK * Langchain * LlamaIndex * Core pip install toolbox-core pip install toolbox-langchain pip install toolbox-llamaindex pip install toolbox-core 2. Install other required dependencies: * ADK * Langchain * LlamaIndex * Core pip install google-adk # TODO(developer): replace with correct package if needed pip install langgraph langchain-google-vertexai # pip install langchain-google-genai # pip install langchain-anthropic # TODO(developer): replace with correct package if needed pip install llama-index-llms-google-genai # pip install llama-index-llms-anthropic pip install google-genai 3. Create the agent: * ADK * LangChain * LlamaIndex * Core 1. Create a new agent project. This will create a new directory named `my_agent` with a file `agent.py`. adk create my_agent 2. Update `my_agent/agent.py` with the following content to connect to Toolbox: from google.adk import Agent from google.adk.apps import App from toolbox_core import ToolboxSyncClient # TODO(developer): update the TOOLBOX_URL to your toolbox endpoint client = ToolboxSyncClient("http://127.0.0.1:5000") root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=client.load_toolset(), ) app = App(root_agent=root_agent, name="my_agent") 3. Create a `.env` file with your Google API key: echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env Create a new file named `agent.py` and copy the following code: import asyncio from langgraph.prebuilt import create_react_agent # TODO(developer): replace this with another import if needed from langchain_google_vertexai import ChatVertexAI # from langchain_google_genai import ChatGoogleGenerativeAI # from langchain_anthropic import ChatAnthropic from langgraph.checkpoint.memory import MemorySaver from toolbox_langchain import ToolboxClient prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed model = ChatVertexAI(model_name="gemini-2.0-flash-001") # model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001") # model = ChatAnthropic(model="claude-3-5-sonnet-20240620") # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = create_react_agent(model, tools, checkpointer=MemorySaver()) config = {"configurable": {"thread_id": "thread-1"}} for query in queries: inputs = {"messages": [("user", prompt + query)]} response = agent.invoke(inputs, stream_mode="values", config=config) print(response["messages"][-1].content) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from llama_index.core.agent.workflow import AgentWorkflow from llama_index.core.workflow import Context # TODO(developer): replace this with another import if needed from llama_index.llms.google_genai import GoogleGenAI # from llama_index.llms.anthropic import Anthropic from toolbox_llamaindex import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed llm = GoogleGenAI( model="gemini-2.0-flash-001", vertexai_config={"project": project, "location": "us-central1"}, ) # llm = GoogleGenAI( # api_key=os.getenv("GOOGLE_API_KEY"), # model="gemini-2.0-flash-001", # ) # llm = Anthropic( # model="claude-3-7-sonnet-latest", # api_key=os.getenv("ANTHROPIC_API_KEY") # ) # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = AgentWorkflow.from_tools_or_functions( tools, llm=llm, system_prompt=prompt, ) ctx = Context(agent) for query in queries: response = await agent.run(user_msg=query, ctx=ctx) print(f"---- {query} ----") print(str(response)) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from google import genai from google.genai.types import ( Content, FunctionDeclaration, GenerateContentConfig, Part, Tool, ) from toolbox_core import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Please book the hotel Hilton Basel for me.",\ "This is too expensive. Please cancel it.",\ "Please book Hyatt Regency for me",\ "My check in dates for my booking would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): async with ToolboxClient("http://127.0.0.1:5000") as toolbox_client: # The toolbox_tools list contains Python callables (functions/methods) designed for LLM tool-use # integration. While this example uses Google's genai client, these callables can be adapted for # various function-calling or agent frameworks. For easier integration with supported frameworks # (https://github.com/googleapis/mcp-toolbox-python-sdk/tree/main/packages), use the # provided wrapper packages, which handle framework-specific boilerplate. toolbox_tools = await toolbox_client.load_toolset("my-toolset") genai_client = genai.Client( vertexai=True, project=project, location="us-central1" ) genai_tools = [\ Tool(\ function_declarations=[\ FunctionDeclaration.from_callable_with_api_option(callable=tool)\ ]\ )\ for tool in toolbox_tools\ ] history = [] for query in queries: user_prompt_content = Content( role="user", parts=[Part.from_text(text=query)], ) history.append(user_prompt_content) response = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( system_instruction=prompt, tools=genai_tools, ), ) history.append(response.candidates[0].content) function_response_parts = [] if response.function_calls: for function_call in response.function_calls: fn_name = function_call.name # The tools are sorted alphabetically if fn_name == "search-hotels-by-name": function_result = await toolbox_tools[3](**function_call.args) elif fn_name == "search-hotels-by-location": function_result = await toolbox_tools[2](**function_call.args) elif fn_name == "book-hotel": function_result = await toolbox_tools[0](**function_call.args) elif fn_name == "update-hotel": function_result = await toolbox_tools[4](**function_call.args) elif fn_name == "cancel-hotel": function_result = await toolbox_tools[1](**function_call.args) else: raise ValueError(f"Function name {fn_name} not present.") function_response = {"result": function_result} function_response_part = Part.from_function_response( name=function_call.name, response=function_response, ) function_response_parts.append(function_response_part) if function_response_parts: tool_response_content = Content(role="tool", parts=function_response_parts) history.append(tool_response_content) response2 = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( tools=genai_tools, ), ) final_model_response_content = response2.candidates[0].content history.append(final_model_response_content) print(response2.text) else: print(response.text) asyncio.run(main()) * ADK * Langchain * LlamaIndex * Core To learn more about Agent Development Kit, check out the [ADK Documentation](https://google.github.io/adk-docs/get-started/python/) . To learn more about Agents in LangChain, check out the [LangGraph Agent Documentation](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) . To learn more about Agents in LlamaIndex, check out the [LlamaIndex AgentWorkflow Documentation](https://docs.llamaindex.ai/en/stable/examples/agent/agent_workflow_basic/) . To learn more about tool calling with Google GenAI, check out the [Google GenAI Documentation](https://github.com/googleapis/python-genai?tab=readme-ov-file#manually-declare-and-invoke-a-function-for-function-calling) . 4. Run your agent, and observe the results: * ADK * Langchain * LlamaIndex * Core Run your agent locally for testing: adk run my_agent Alternatively, serve it via a web interface: adk web --port 8000 For more information, refer to the ADK documentation on [Running Agents](https://google.github.io/adk-docs/get-started/python/#run-your-agent) and [Deploying to Cloud](https://google.github.io/adk-docs/deploy/) . python agent.py python agent.py python agent.py Info For more information, visit the [Python SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-python) . Last modified November 26, 2025: [docs: Improve and simplify ADK Python Quickstart (#1962) (923479034fa)](https://github.com/googleapis/genai-toolbox/commit/923479034fa26241309887c88f956985293a4a42) --- # Introduction | MCP Toolbox for Databases Introduction ============ An introduction to MCP Toolbox for Databases. MCP Toolbox for Databases is an open source MCP server for databases. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more. Note This solution was originally named “Gen AI Toolbox for Databases” as its initial development predated MCP, but was renamed to align with recently added MCP compatibility. Note This document has been updated to support the configuration file v2 format. To view documentation with configuration file v1 format, please navigate to the top-right menu and select versions v0.26.0 or older. Why Toolbox? ------------ Toolbox helps you build Gen AI tools that let your agents access data in your database. Toolbox provides: * **Simplified development**: Integrate tools to your agent in less than 10 lines of code, reuse tools between multiple agents or frameworks, and deploy new versions of tools more easily. * **Better performance**: Best practices such as connection pooling, authentication, and more. * **Enhanced security**: Integrated auth for more secure access to your data * **End-to-end observability**: Out of the box metrics and tracing with built-in support for OpenTelemetry. **⚡ Supercharge Your Workflow with an AI Database Assistant ⚡** Stop context-switching and let your AI assistant become a true co-developer. By [connecting your IDE to your databases with MCP Toolbox](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/) , you can delegate complex and time-consuming database tasks, allowing you to build faster and focus on what matters. This isn’t just about code completion; it’s about giving your AI the context it needs to handle the entire development lifecycle. Here’s how it will save you time: * **Query in Plain English**: Interact with your data using natural language right from your IDE. Ask complex questions like, _“How many orders were delivered in 2024, and what items were in them?”_ without writing any SQL. * **Automate Database Management**: Simply describe your data needs, and let the AI assistant manage your database for you. It can handle generating queries, creating tables, adding indexes, and more. * **Generate Context-Aware Code**: Empower your AI assistant to generate application code and tests with a deep understanding of your real-time database schema. This accelerates the development cycle by ensuring the generated code is directly usable. * **Slash Development Overhead**: Radically reduce the time spent on manual setup and boilerplate. MCP Toolbox helps streamline lengthy database configurations, repetitive code, and error-prone schema migrations. Learn [how to connect your AI tools (IDEs) to Toolbox using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/) . General Architecture -------------------- Toolbox sits between your application’s orchestration framework and your database, providing a control plane that is used to modify, distribute, or invoke tools. It simplifies the management of your tools by providing you with a centralized location to store and update tools, allowing you to share tools between agents and applications and update those tools without necessarily redeploying your application. ![architecture](https://mcp-toolbox.dev/v0.27.0/getting-started/introduction/architecture.png) Getting Started --------------- ### Quickstart: Running Toolbox using NPX You can run Toolbox directly with a [configuration file](https://mcp-toolbox.dev/v0.27.0/getting-started/configure/) : npx @toolbox-sdk/server --tools-file tools.yaml This runs the latest version of the toolbox server with your configuration file. Note This method should only be used for non-production use cases such as experimentation. For any production use-cases, please consider [Installing the server](https://mcp-toolbox.dev/v0.27.0/#installing-the-server) and then [running it](https://mcp-toolbox.dev/v0.27.0/#running-the-server) . ### Installing the server For the latest version, check the [releases page](https://github.com/googleapis/genai-toolbox/releases) and use the following instructions for your OS and CPU architecture. * Binary * Container image * Homebrew * Compile from source * Linux (AMD64) * macOS (Apple Silicon) * macOS (Intel) * Windows (Command Prompt) * Windows (PowerShell) To install Toolbox as a binary on Linux (AMD64): # see releases page for other versions export VERSION=0.27.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Apple Silicon): # see releases page for other versions export VERSION=0.27.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Intel): # see releases page for other versions export VERSION=0.27.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on Windows (Command Prompt): :: see releases page for other versions set VERSION=0.27.0 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe" To install Toolbox as a binary on Windows (PowerShell): # see releases page for other versions $VERSION = "0.27.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe" You can also install Toolbox as a container: # see releases page for other versions export VERSION=0.27.0 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION To install Toolbox using Homebrew on macOS or Linux: brew install mcp-toolbox To install from source, ensure you have the latest version of [Go installed](https://go.dev/doc/install) , and then run the following command: go install github.com/googleapis/[email protected] ### Running the server [Configure](https://mcp-toolbox.dev/v0.27.0/getting-started/configure/) a `tools.yaml` to define your tools, and then execute `toolbox` to start the server: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. #### Launching Toolbox UI To launch Toolbox’s interactive UI, use the `--ui` flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit [Toolbox UI](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/) . ./toolbox --ui #### Homebrew Users If you installed Toolbox using Homebrew, the `toolbox` binary is available in your system path. You can start the server with the same command: toolbox --tools-file "tools.yaml" You can use `toolbox help` for a full list of flags! To stop the server, send a terminate signal (`ctrl+c` on most platforms). For more detailed documentation on deploying to different environments, check out the resources in the [How-to section](https://mcp-toolbox.dev/v0.27.0/how-to/) ### Integrating your application Once your server is up and running, you can load the tools into your application. See below the list of Client SDKs for using various frameworks: #### Python * Core * LangChain * Llamaindex Once you’ve installed the [Toolbox Core SDK](https://pypi.org/project/toolbox-core/) , you can load tools: from toolbox_core import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = await client.load_toolset("toolset_name") For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) . Once you’ve installed the [Toolbox LangChain SDK](https://pypi.org/project/toolbox-langchain/) , you can load tools: from toolbox_langchain import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset() For more detailed instructions on using the Toolbox LangChain SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) . Once you’ve installed the [Toolbox Llamaindex SDK](https://github.com/googleapis/genai-toolbox-llamaindex-python) , you can load tools: from toolbox_llamaindex import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application tools = client.load_toolset() For more detailed instructions on using the Toolbox Llamaindex SDK, see the [project’s README](https://github.com/googleapis/genai-toolbox-llamaindex-python/blob/main/README.md) . #### Javascript/Typescript Once you’ve installed the [Toolbox Core SDK](https://www.npmjs.com/package/@toolbox-sdk/core) , you can load tools: * Core * LangChain/Langraph * Genkit * LlamaIndex * ADK TS import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(currTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); // Use these tools in your Langchain/Langraph applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { genkit } from 'genkit'; // Initialise genkit const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => ai.defineTool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }, toolboxTool) // Use these tools in your Genkit applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { tool } from "llamaindex"; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool });; // Use these tools in your LlamaIndex applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/adk'; // Replace with the actual URL where your Toolbox service is running const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const tools = await client.loadToolset(); // Use the client and tools as per requirement For detailed samples on using the Toolbox JS SDK with ADK JS, see the [project’s README.](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main/packages/toolbox-adk/README.md) #### Go Once you’ve installed the [Toolbox Go SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: * Core * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" ) func main() { // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tools tools, err := client.LoadToolset("toolsetName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } } package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with LangChainGo langChainTool := llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with LangChain Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "encoding/json" "log" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/invopop/jsonschema" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() g, err := genkit.Init(ctx) client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Convert the tool using the tbgenkit package // Use this tool with Genkit Go genkitTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } } For end-to-end samples on using the Toolbox Go SDK with Genkit Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit/samples) package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var schema *genai.Schema _ = json.Unmarshal(inputschema, &schema) funcDeclaration := &genai.FunctionDeclaration{ Name: tool.Name(), Description: tool.Description(), Parameters: schema, } // Use this tool with Go GenAI genAITool := &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } For end-to-end samples on using the Toolbox Go SDK with Go GenAI, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema openai.FunctionParameters _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with OpenAI Go openAITool := openai.ChatCompletionToolParam{ Function: openai.FunctionDefinitionParam{ Name: tool.Name(), Description: openai.String(tool.Description()), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with OpenAI Go, see the \[project's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) package main import ( "context" "fmt" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := tbadk.NewToolboxClient(URL) if err != nil { return fmt.Sprintln("Could not start Toolbox Client", err) } // Use this tool with ADK Go tool, err := client.LoadTool("toolName", ctx) if err != nil { return fmt.Sprintln("Could not load Toolbox Tool", err) } } For end-to-end samples on using the Toolbox Go SDK with ADK Go, see the [project’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbadk/samples) For more detailed instructions on using the Toolbox Go SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md) . Last modified February 12, 2026: [chore(main): release 0.27.0 (#2363) (c5524d32f58)](https://github.com/googleapis/genai-toolbox/commit/c5524d32f580fed81c8b90448e2f17e719710ff9) --- # Introduction | MCP Toolbox for Databases Introduction ============ An introduction to MCP Toolbox for Databases. MCP Toolbox for Databases is an open source MCP server for databases. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more. Note This solution was originally named “Gen AI Toolbox for Databases” as its initial development predated MCP, but was renamed to align with recently added MCP compatibility. Note This document has been updated to support the configuration file v2 format. To view documentation with configuration file v1 format, please navigate to the top-right menu and select versions v0.26.0 or older. Why Toolbox? ------------ Toolbox helps you build Gen AI tools that let your agents access data in your database. Toolbox provides: * **Simplified development**: Integrate tools to your agent in less than 10 lines of code, reuse tools between multiple agents or frameworks, and deploy new versions of tools more easily. * **Better performance**: Best practices such as connection pooling, authentication, and more. * **Enhanced security**: Integrated auth for more secure access to your data * **End-to-end observability**: Out of the box metrics and tracing with built-in support for OpenTelemetry. **⚡ Supercharge Your Workflow with an AI Database Assistant ⚡** Stop context-switching and let your AI assistant become a true co-developer. By [connecting your IDE to your databases with MCP Toolbox](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/) , you can delegate complex and time-consuming database tasks, allowing you to build faster and focus on what matters. This isn’t just about code completion; it’s about giving your AI the context it needs to handle the entire development lifecycle. Here’s how it will save you time: * **Query in Plain English**: Interact with your data using natural language right from your IDE. Ask complex questions like, _“How many orders were delivered in 2024, and what items were in them?”_ without writing any SQL. * **Automate Database Management**: Simply describe your data needs, and let the AI assistant manage your database for you. It can handle generating queries, creating tables, adding indexes, and more. * **Generate Context-Aware Code**: Empower your AI assistant to generate application code and tests with a deep understanding of your real-time database schema. This accelerates the development cycle by ensuring the generated code is directly usable. * **Slash Development Overhead**: Radically reduce the time spent on manual setup and boilerplate. MCP Toolbox helps streamline lengthy database configurations, repetitive code, and error-prone schema migrations. Learn [how to connect your AI tools (IDEs) to Toolbox using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/) . General Architecture -------------------- Toolbox sits between your application’s orchestration framework and your database, providing a control plane that is used to modify, distribute, or invoke tools. It simplifies the management of your tools by providing you with a centralized location to store and update tools, allowing you to share tools between agents and applications and update those tools without necessarily redeploying your application. ![architecture](https://mcp-toolbox.dev/v0.28.0/getting-started/introduction/architecture.png) Getting Started --------------- ### Quickstart: Running Toolbox using NPX You can run Toolbox directly with a [configuration file](https://mcp-toolbox.dev/v0.28.0/getting-started/configure/) : npx @toolbox-sdk/server --tools-file tools.yaml This runs the latest version of the toolbox server with your configuration file. Note This method should only be used for non-production use cases such as experimentation. For any production use-cases, please consider [Installing the server](https://mcp-toolbox.dev/v0.28.0/#installing-the-server) and then [running it](https://mcp-toolbox.dev/v0.28.0/#running-the-server) . ### Installing the server For the latest version, check the [releases page](https://github.com/googleapis/genai-toolbox/releases) and use the following instructions for your OS and CPU architecture. * Binary * Container image * Homebrew * Compile from source * Linux (AMD64) * macOS (Apple Silicon) * macOS (Intel) * Windows (Command Prompt) * Windows (PowerShell) To install Toolbox as a binary on Linux (AMD64): # see releases page for other versions export VERSION=0.28.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Apple Silicon): # see releases page for other versions export VERSION=0.28.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Intel): # see releases page for other versions export VERSION=0.28.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on Windows (Command Prompt): :: see releases page for other versions set VERSION=0.28.0 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe" To install Toolbox as a binary on Windows (PowerShell): # see releases page for other versions $VERSION = "0.28.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe" You can also install Toolbox as a container: # see releases page for other versions export VERSION=0.28.0 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION To install Toolbox using Homebrew on macOS or Linux: brew install mcp-toolbox To install from source, ensure you have the latest version of [Go installed](https://go.dev/doc/install) , and then run the following command: go install github.com/googleapis/[email protected] ### Running the server [Configure](https://mcp-toolbox.dev/v0.28.0/getting-started/configure/) a `tools.yaml` to define your tools, and then execute `toolbox` to start the server: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. #### Launching Toolbox UI To launch Toolbox’s interactive UI, use the `--ui` flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit [Toolbox UI](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/) . ./toolbox --ui #### Homebrew Users If you installed Toolbox using Homebrew, the `toolbox` binary is available in your system path. You can start the server with the same command: toolbox --tools-file "tools.yaml" You can use `toolbox help` for a full list of flags! To stop the server, send a terminate signal (`ctrl+c` on most platforms). For more detailed documentation on deploying to different environments, check out the resources in the [How-to section](https://mcp-toolbox.dev/v0.28.0/how-to/) ### Integrating your application Once your server is up and running, you can load the tools into your application. See below the list of Client SDKs for using various frameworks: #### Python * Core * LangChain * Llamaindex Once you’ve installed the [Toolbox Core SDK](https://pypi.org/project/toolbox-core/) , you can load tools: from toolbox_core import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = await client.load_toolset("toolset_name") For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) . Once you’ve installed the [Toolbox LangChain SDK](https://pypi.org/project/toolbox-langchain/) , you can load tools: from toolbox_langchain import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset() For more detailed instructions on using the Toolbox LangChain SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) . Once you’ve installed the [Toolbox Llamaindex SDK](https://github.com/googleapis/genai-toolbox-llamaindex-python) , you can load tools: from toolbox_llamaindex import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application tools = client.load_toolset() For more detailed instructions on using the Toolbox Llamaindex SDK, see the [project’s README](https://github.com/googleapis/genai-toolbox-llamaindex-python/blob/main/README.md) . #### Javascript/Typescript Once you’ve installed the [Toolbox Core SDK](https://www.npmjs.com/package/@toolbox-sdk/core) , you can load tools: * Core * LangChain/Langraph * Genkit * LlamaIndex * ADK TS import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(currTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); // Use these tools in your Langchain/Langraph applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { genkit } from 'genkit'; // Initialise genkit const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => ai.defineTool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }, toolboxTool) // Use these tools in your Genkit applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { tool } from "llamaindex"; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool });; // Use these tools in your LlamaIndex applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/adk'; // Replace with the actual URL where your Toolbox service is running const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const tools = await client.loadToolset(); // Use the client and tools as per requirement For detailed samples on using the Toolbox JS SDK with ADK JS, see the [project’s README.](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main/packages/toolbox-adk/README.md) #### Go * Core * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" ) func main() { // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tools tools, err := client.LoadToolset("toolsetName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } } Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with LangChainGo langChainTool := llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with LangChain Go, see the [module’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go TBGenkit SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/invopop/jsonschema" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() g, err := genkit.Init(ctx) client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Convert the tool using the tbgenkit package // Use this tool with Genkit Go genkitTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } } For end-to-end samples on using the Toolbox Go SDK with Genkit Go, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit/samples) Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var schema *genai.Schema _ = json.Unmarshal(inputschema, &schema) funcDeclaration := &genai.FunctionDeclaration{ Name: tool.Name(), Description: tool.Description(), Parameters: schema, } // Use this tool with Go GenAI genAITool := &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } For end-to-end samples on using the Toolbox Go SDK with Go GenAI, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema openai.FunctionParameters _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with OpenAI Go openAITool := openai.ChatCompletionToolParam{ Function: openai.FunctionDefinitionParam{ Name: tool.Name(), Description: openai.String(tool.Description()), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with OpenAI Go, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go TBADK SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/tbadk) , you can load tools: package main import ( "context" "fmt" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := tbadk.NewToolboxClient(URL) if err != nil { return fmt.Sprintln("Could not start Toolbox Client", err) } // Use this tool with ADK Go tool, err := client.LoadTool("toolName", ctx) if err != nil { return fmt.Sprintln("Could not load Toolbox Tool", err) } } For end-to-end samples on using the Toolbox Go SDK with ADK Go, see the [module’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbadk/samples) For more detailed instructions on using the Toolbox Go SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md) . Last modified March 2, 2026: [chore(main): release 0.28.0 (#2472) (81253a0bd70)](https://github.com/googleapis/genai-toolbox/commit/81253a0bd7049a2e2681ef13631a768cb402040e) --- # Python Quickstart (Local) | MCP Toolbox for Databases Python Quickstart (Local) ========================= How to get started running Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/getting-started/colab_quickstart.ipynb) Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Python 3.10+](https://wiki.python.org/moin/BeginnersGuide/Download) (including [pip](https://pip.pypa.io/en/stable/installation/) and your preferred virtual environment tool for managing dependencies e.g. [venv](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) ). 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. Tip If you prefer to experiment within a Google Colab environment, you can connect to a [local runtime](https://research.google.com/colaboratory/local-runtimes.html) . 1. In a new terminal, install the SDK package. * ADK * Langchain * LlamaIndex * Core pip install toolbox-core pip install toolbox-langchain pip install toolbox-llamaindex pip install toolbox-core 2. Install other required dependencies: * ADK * Langchain * LlamaIndex * Core pip install google-adk # TODO(developer): replace with correct package if needed pip install langgraph langchain-google-vertexai # pip install langchain-google-genai # pip install langchain-anthropic # TODO(developer): replace with correct package if needed pip install llama-index-llms-google-genai # pip install llama-index-llms-anthropic pip install google-genai 3. Create the agent: * ADK * LangChain * LlamaIndex * Core 1. Create a new agent project. This will create a new directory named `my_agent` with a file `agent.py`. adk create my_agent 2. Update `my_agent/agent.py` with the following content to connect to Toolbox: from google.adk import Agent from google.adk.apps import App from toolbox_core import ToolboxSyncClient # TODO(developer): update the TOOLBOX_URL to your toolbox endpoint client = ToolboxSyncClient("http://127.0.0.1:5000") root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=client.load_toolset(), ) app = App(root_agent=root_agent, name="my_agent") 3. Create a `.env` file with your Google API key: echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env Create a new file named `agent.py` and copy the following code: import asyncio from langgraph.prebuilt import create_react_agent # TODO(developer): replace this with another import if needed from langchain_google_vertexai import ChatVertexAI # from langchain_google_genai import ChatGoogleGenerativeAI # from langchain_anthropic import ChatAnthropic from langgraph.checkpoint.memory import MemorySaver from toolbox_langchain import ToolboxClient prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed model = ChatVertexAI(model_name="gemini-2.0-flash-001") # model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001") # model = ChatAnthropic(model="claude-3-5-sonnet-20240620") # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = create_react_agent(model, tools, checkpointer=MemorySaver()) config = {"configurable": {"thread_id": "thread-1"}} for query in queries: inputs = {"messages": [("user", prompt + query)]} response = agent.invoke(inputs, stream_mode="values", config=config) print(response["messages"][-1].content) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from llama_index.core.agent.workflow import AgentWorkflow from llama_index.core.workflow import Context # TODO(developer): replace this with another import if needed from llama_index.llms.google_genai import GoogleGenAI # from llama_index.llms.anthropic import Anthropic from toolbox_llamaindex import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed llm = GoogleGenAI( model="gemini-2.0-flash-001", vertexai_config={"project": project, "location": "us-central1"}, ) # llm = GoogleGenAI( # api_key=os.getenv("GOOGLE_API_KEY"), # model="gemini-2.0-flash-001", # ) # llm = Anthropic( # model="claude-3-7-sonnet-latest", # api_key=os.getenv("ANTHROPIC_API_KEY") # ) # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = AgentWorkflow.from_tools_or_functions( tools, llm=llm, system_prompt=prompt, ) ctx = Context(agent) for query in queries: response = await agent.run(user_msg=query, ctx=ctx) print(f"---- {query} ----") print(str(response)) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from google import genai from google.genai.types import ( Content, FunctionDeclaration, GenerateContentConfig, Part, Tool, ) from toolbox_core import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Please book the hotel Hilton Basel for me.",\ "This is too expensive. Please cancel it.",\ "Please book Hyatt Regency for me",\ "My check in dates for my booking would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): async with ToolboxClient("http://127.0.0.1:5000") as toolbox_client: # The toolbox_tools list contains Python callables (functions/methods) designed for LLM tool-use # integration. While this example uses Google's genai client, these callables can be adapted for # various function-calling or agent frameworks. For easier integration with supported frameworks # (https://github.com/googleapis/mcp-toolbox-python-sdk/tree/main/packages), use the # provided wrapper packages, which handle framework-specific boilerplate. toolbox_tools = await toolbox_client.load_toolset("my-toolset") genai_client = genai.Client( vertexai=True, project=project, location="us-central1" ) genai_tools = [\ Tool(\ function_declarations=[\ FunctionDeclaration.from_callable_with_api_option(callable=tool)\ ]\ )\ for tool in toolbox_tools\ ] history = [] for query in queries: user_prompt_content = Content( role="user", parts=[Part.from_text(text=query)], ) history.append(user_prompt_content) response = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( system_instruction=prompt, tools=genai_tools, ), ) history.append(response.candidates[0].content) function_response_parts = [] if response.function_calls: for function_call in response.function_calls: fn_name = function_call.name # The tools are sorted alphabetically if fn_name == "search-hotels-by-name": function_result = await toolbox_tools[3](**function_call.args) elif fn_name == "search-hotels-by-location": function_result = await toolbox_tools[2](**function_call.args) elif fn_name == "book-hotel": function_result = await toolbox_tools[0](**function_call.args) elif fn_name == "update-hotel": function_result = await toolbox_tools[4](**function_call.args) elif fn_name == "cancel-hotel": function_result = await toolbox_tools[1](**function_call.args) else: raise ValueError(f"Function name {fn_name} not present.") function_response = {"result": function_result} function_response_part = Part.from_function_response( name=function_call.name, response=function_response, ) function_response_parts.append(function_response_part) if function_response_parts: tool_response_content = Content(role="tool", parts=function_response_parts) history.append(tool_response_content) response2 = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( tools=genai_tools, ), ) final_model_response_content = response2.candidates[0].content history.append(final_model_response_content) print(response2.text) else: print(response.text) asyncio.run(main()) * ADK * Langchain * LlamaIndex * Core To learn more about Agent Development Kit, check out the [ADK Documentation](https://google.github.io/adk-docs/get-started/python/) . To learn more about Agents in LangChain, check out the [LangGraph Agent Documentation](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) . To learn more about Agents in LlamaIndex, check out the [LlamaIndex AgentWorkflow Documentation](https://docs.llamaindex.ai/en/stable/examples/agent/agent_workflow_basic/) . To learn more about tool calling with Google GenAI, check out the [Google GenAI Documentation](https://github.com/googleapis/python-genai?tab=readme-ov-file#manually-declare-and-invoke-a-function-for-function-calling) . 4. Run your agent, and observe the results: * ADK * Langchain * LlamaIndex * Core Run your agent locally for testing: adk run my_agent Alternatively, serve it via a web interface: adk web --port 8000 For more information, refer to the ADK documentation on [Running Agents](https://google.github.io/adk-docs/get-started/python/#run-your-agent) and [Deploying to Cloud](https://google.github.io/adk-docs/deploy/) . python agent.py python agent.py python agent.py Info For more information, visit the [Python SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-python) . Last modified November 26, 2025: [docs: Improve and simplify ADK Python Quickstart (#1962) (923479034fa)](https://github.com/googleapis/genai-toolbox/commit/923479034fa26241309887c88f956985293a4a42) --- # Getting Started | MCP Toolbox for Databases Getting Started =============== How to get started with Toolbox. * * * ##### [Introduction](https://mcp-toolbox.dev/v0.29.0/getting-started/introduction/) An introduction to MCP Toolbox for Databases. ##### [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.29.0/getting-started/local_quickstart/) How to get started running MCP Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . ##### [JS Quickstart (Local)](https://mcp-toolbox.dev/v0.29.0/getting-started/local_quickstart_js/) How to get started running MCP Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . ##### [Go Quickstart (Local)](https://mcp-toolbox.dev/v0.29.0/getting-started/local_quickstart_go/) How to get started running MCP Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . ##### [Prompts using Gemini CLI](https://mcp-toolbox.dev/v0.29.0/getting-started/prompts_quickstart_gemini_cli/) How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . ##### [Quickstart (MCP)](https://mcp-toolbox.dev/v0.29.0/getting-started/mcp_quickstart/) How to get started running Toolbox locally with MCP Inspector. ##### [Configuration](https://mcp-toolbox.dev/v0.29.0/getting-started/configure/) How to configure Toolbox’s tools.yaml file. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Getting Started | MCP Toolbox for Databases Getting Started =============== How to get started with Toolbox. * * * ##### [Introduction](https://mcp-toolbox.dev/v0.30.0/getting-started/introduction/) An introduction to MCP Toolbox for Databases. ##### [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.30.0/getting-started/local_quickstart/) How to get started running MCP Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . ##### [JS Quickstart (Local)](https://mcp-toolbox.dev/v0.30.0/getting-started/local_quickstart_js/) How to get started running MCP Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . ##### [Go Quickstart (Local)](https://mcp-toolbox.dev/v0.30.0/getting-started/local_quickstart_go/) How to get started running MCP Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . ##### [Prompts using Gemini CLI](https://mcp-toolbox.dev/v0.30.0/getting-started/prompts_quickstart_gemini_cli/) How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . ##### [Quickstart (MCP)](https://mcp-toolbox.dev/v0.30.0/getting-started/mcp_quickstart/) How to get started running Toolbox locally with MCP Inspector. ##### [Configuration](https://mcp-toolbox.dev/v0.30.0/getting-started/configure/) How to configure Toolbox’s tools.yaml file. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Python Quickstart (Local) | MCP Toolbox for Databases Python Quickstart (Local) ========================= How to get started running Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/getting-started/colab_quickstart.ipynb) Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Python 3.10+](https://wiki.python.org/moin/BeginnersGuide/Download) (including [pip](https://pip.pypa.io/en/stable/installation/) and your preferred virtual environment tool for managing dependencies e.g. [venv](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) ). 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. Tip If you prefer to experiment within a Google Colab environment, you can connect to a [local runtime](https://research.google.com/colaboratory/local-runtimes.html) . 1. In a new terminal, install the SDK package. * ADK * Langchain * LlamaIndex * Core pip install toolbox-core pip install toolbox-langchain pip install toolbox-llamaindex pip install toolbox-core 2. Install other required dependencies: * ADK * Langchain * LlamaIndex * Core pip install google-adk # TODO(developer): replace with correct package if needed pip install langgraph langchain-google-vertexai # pip install langchain-google-genai # pip install langchain-anthropic # TODO(developer): replace with correct package if needed pip install llama-index-llms-google-genai # pip install llama-index-llms-anthropic pip install google-genai 3. Create the agent: * ADK * LangChain * LlamaIndex * Core 1. Create a new agent project. This will create a new directory named `my_agent` with a file `agent.py`. adk create my_agent 2. Update `my_agent/agent.py` with the following content to connect to Toolbox: from google.adk import Agent from google.adk.apps import App from toolbox_core import ToolboxSyncClient # TODO(developer): update the TOOLBOX_URL to your toolbox endpoint client = ToolboxSyncClient("http://127.0.0.1:5000") root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=client.load_toolset(), ) app = App(root_agent=root_agent, name="my_agent") 3. Create a `.env` file with your Google API key: echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env Create a new file named `agent.py` and copy the following code: import asyncio from langgraph.prebuilt import create_react_agent # TODO(developer): replace this with another import if needed from langchain_google_vertexai import ChatVertexAI # from langchain_google_genai import ChatGoogleGenerativeAI # from langchain_anthropic import ChatAnthropic from langgraph.checkpoint.memory import MemorySaver from toolbox_langchain import ToolboxClient prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed model = ChatVertexAI(model_name="gemini-2.0-flash-001") # model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001") # model = ChatAnthropic(model="claude-3-5-sonnet-20240620") # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = create_react_agent(model, tools, checkpointer=MemorySaver()) config = {"configurable": {"thread_id": "thread-1"}} for query in queries: inputs = {"messages": [("user", prompt + query)]} response = agent.invoke(inputs, stream_mode="values", config=config) print(response["messages"][-1].content) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from llama_index.core.agent.workflow import AgentWorkflow from llama_index.core.workflow import Context # TODO(developer): replace this with another import if needed from llama_index.llms.google_genai import GoogleGenAI # from llama_index.llms.anthropic import Anthropic from toolbox_llamaindex import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed llm = GoogleGenAI( model="gemini-2.0-flash-001", vertexai_config={"project": project, "location": "us-central1"}, ) # llm = GoogleGenAI( # api_key=os.getenv("GOOGLE_API_KEY"), # model="gemini-2.0-flash-001", # ) # llm = Anthropic( # model="claude-3-7-sonnet-latest", # api_key=os.getenv("ANTHROPIC_API_KEY") # ) # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = AgentWorkflow.from_tools_or_functions( tools, llm=llm, system_prompt=prompt, ) ctx = Context(agent) for query in queries: response = await agent.run(user_msg=query, ctx=ctx) print(f"---- {query} ----") print(str(response)) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from google import genai from google.genai.types import ( Content, FunctionDeclaration, GenerateContentConfig, Part, Tool, ) from toolbox_core import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Please book the hotel Hilton Basel for me.",\ "This is too expensive. Please cancel it.",\ "Please book Hyatt Regency for me",\ "My check in dates for my booking would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): async with ToolboxClient("http://127.0.0.1:5000") as toolbox_client: # The toolbox_tools list contains Python callables (functions/methods) designed for LLM tool-use # integration. While this example uses Google's genai client, these callables can be adapted for # various function-calling or agent frameworks. For easier integration with supported frameworks # (https://github.com/googleapis/mcp-toolbox-python-sdk/tree/main/packages), use the # provided wrapper packages, which handle framework-specific boilerplate. toolbox_tools = await toolbox_client.load_toolset("my-toolset") genai_client = genai.Client( vertexai=True, project=project, location="us-central1" ) genai_tools = [\ Tool(\ function_declarations=[\ FunctionDeclaration.from_callable_with_api_option(callable=tool)\ ]\ )\ for tool in toolbox_tools\ ] history = [] for query in queries: user_prompt_content = Content( role="user", parts=[Part.from_text(text=query)], ) history.append(user_prompt_content) response = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( system_instruction=prompt, tools=genai_tools, ), ) history.append(response.candidates[0].content) function_response_parts = [] if response.function_calls: for function_call in response.function_calls: fn_name = function_call.name # The tools are sorted alphabetically if fn_name == "search-hotels-by-name": function_result = await toolbox_tools[3](**function_call.args) elif fn_name == "search-hotels-by-location": function_result = await toolbox_tools[2](**function_call.args) elif fn_name == "book-hotel": function_result = await toolbox_tools[0](**function_call.args) elif fn_name == "update-hotel": function_result = await toolbox_tools[4](**function_call.args) elif fn_name == "cancel-hotel": function_result = await toolbox_tools[1](**function_call.args) else: raise ValueError(f"Function name {fn_name} not present.") function_response = {"result": function_result} function_response_part = Part.from_function_response( name=function_call.name, response=function_response, ) function_response_parts.append(function_response_part) if function_response_parts: tool_response_content = Content(role="tool", parts=function_response_parts) history.append(tool_response_content) response2 = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( tools=genai_tools, ), ) final_model_response_content = response2.candidates[0].content history.append(final_model_response_content) print(response2.text) else: print(response.text) asyncio.run(main()) * ADK * Langchain * LlamaIndex * Core To learn more about Agent Development Kit, check out the [ADK Documentation](https://google.github.io/adk-docs/get-started/python/) . To learn more about Agents in LangChain, check out the [LangGraph Agent Documentation](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) . To learn more about Agents in LlamaIndex, check out the [LlamaIndex AgentWorkflow Documentation](https://docs.llamaindex.ai/en/stable/examples/agent/agent_workflow_basic/) . To learn more about tool calling with Google GenAI, check out the [Google GenAI Documentation](https://github.com/googleapis/python-genai?tab=readme-ov-file#manually-declare-and-invoke-a-function-for-function-calling) . 4. Run your agent, and observe the results: * ADK * Langchain * LlamaIndex * Core Run your agent locally for testing: adk run my_agent Alternatively, serve it via a web interface: adk web --port 8000 For more information, refer to the ADK documentation on [Running Agents](https://google.github.io/adk-docs/get-started/python/#run-your-agent) and [Deploying to Cloud](https://google.github.io/adk-docs/deploy/) . python agent.py python agent.py python agent.py Info For more information, visit the [Python SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-python) . Last modified November 26, 2025: [docs: Improve and simplify ADK Python Quickstart (#1962) (923479034fa)](https://github.com/googleapis/genai-toolbox/commit/923479034fa26241309887c88f956985293a4a42) --- # Introduction | MCP Toolbox for Databases Introduction ============ An introduction to MCP Toolbox for Databases. MCP Toolbox for Databases is an open source MCP server for databases. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more. Note This solution was originally named “Gen AI Toolbox for Databases” as its initial development predated MCP, but was renamed to align with recently added MCP compatibility. Note This document has been updated to support the configuration file v2 format. To view documentation with configuration file v1 format, please navigate to the top-right menu and select versions v0.26.0 or older. Why Toolbox? ------------ Toolbox helps you build Gen AI tools that let your agents access data in your database. Toolbox provides: * **Simplified development**: Integrate tools to your agent in less than 10 lines of code, reuse tools between multiple agents or frameworks, and deploy new versions of tools more easily. * **Better performance**: Best practices such as connection pooling, authentication, and more. * **Enhanced security**: Integrated auth for more secure access to your data * **End-to-end observability**: Out of the box metrics and tracing with built-in support for OpenTelemetry. **⚡ Supercharge Your Workflow with an AI Database Assistant ⚡** Stop context-switching and let your AI assistant become a true co-developer. By [connecting your IDE to your databases with MCP Toolbox](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/) , you can delegate complex and time-consuming database tasks, allowing you to build faster and focus on what matters. This isn’t just about code completion; it’s about giving your AI the context it needs to handle the entire development lifecycle. Here’s how it will save you time: * **Query in Plain English**: Interact with your data using natural language right from your IDE. Ask complex questions like, _“How many orders were delivered in 2024, and what items were in them?”_ without writing any SQL. * **Automate Database Management**: Simply describe your data needs, and let the AI assistant manage your database for you. It can handle generating queries, creating tables, adding indexes, and more. * **Generate Context-Aware Code**: Empower your AI assistant to generate application code and tests with a deep understanding of your real-time database schema. This accelerates the development cycle by ensuring the generated code is directly usable. * **Slash Development Overhead**: Radically reduce the time spent on manual setup and boilerplate. MCP Toolbox helps streamline lengthy database configurations, repetitive code, and error-prone schema migrations. Learn [how to connect your AI tools (IDEs) to Toolbox using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/) . General Architecture -------------------- Toolbox sits between your application’s orchestration framework and your database, providing a control plane that is used to modify, distribute, or invoke tools. It simplifies the management of your tools by providing you with a centralized location to store and update tools, allowing you to share tools between agents and applications and update those tools without necessarily redeploying your application. ![architecture](https://mcp-toolbox.dev/v0.29.0/getting-started/introduction/architecture.png) Getting Started --------------- ### Quickstart: Running Toolbox using NPX You can run Toolbox directly with a [configuration file](https://mcp-toolbox.dev/v0.29.0/getting-started/configure/) : npx @toolbox-sdk/server --tools-file tools.yaml This runs the latest version of the toolbox server with your configuration file. Note This method should only be used for non-production use cases such as experimentation. For any production use-cases, please consider [Installing the server](https://mcp-toolbox.dev/v0.29.0/#installing-the-server) and then [running it](https://mcp-toolbox.dev/v0.29.0/#running-the-server) . ### Installing the server For the latest version, check the [releases page](https://github.com/googleapis/genai-toolbox/releases) and use the following instructions for your OS and CPU architecture. * Binary * Container image * Homebrew * Compile from source * Linux (AMD64) * macOS (Apple Silicon) * macOS (Intel) * Windows (Command Prompt) * Windows (PowerShell) To install Toolbox as a binary on Linux (AMD64): # see releases page for other versions export VERSION=0.29.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Apple Silicon): # see releases page for other versions export VERSION=0.29.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Intel): # see releases page for other versions export VERSION=0.29.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on Windows (Command Prompt): :: see releases page for other versions set VERSION=0.29.0 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe" To install Toolbox as a binary on Windows (PowerShell): # see releases page for other versions $VERSION = "0.29.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe" You can also install Toolbox as a container: # see releases page for other versions export VERSION=0.29.0 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION To install Toolbox using Homebrew on macOS or Linux: brew install mcp-toolbox To install from source, ensure you have the latest version of [Go installed](https://go.dev/doc/install) , and then run the following command: go install github.com/googleapis/[email protected] ### Running the server [Configure](https://mcp-toolbox.dev/v0.29.0/getting-started/configure/) a `tools.yaml` to define your tools, and then execute `toolbox` to start the server: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. #### Launching Toolbox UI To launch Toolbox’s interactive UI, use the `--ui` flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit [Toolbox UI](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/) . ./toolbox --ui #### Homebrew Users If you installed Toolbox using Homebrew, the `toolbox` binary is available in your system path. You can start the server with the same command: toolbox --tools-file "tools.yaml" You can use `toolbox help` for a full list of flags! To stop the server, send a terminate signal (`ctrl+c` on most platforms). For more detailed documentation on deploying to different environments, check out the resources in the [How-to section](https://mcp-toolbox.dev/v0.29.0/how-to/) ### Integrating your application Once your server is up and running, you can load the tools into your application. See below the list of Client SDKs for using various frameworks: #### Python * Core * LangChain * Llamaindex Once you’ve installed the [Toolbox Core SDK](https://pypi.org/project/toolbox-core/) , you can load tools: from toolbox_core import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = await client.load_toolset("toolset_name") For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) . Once you’ve installed the [Toolbox LangChain SDK](https://pypi.org/project/toolbox-langchain/) , you can load tools: from toolbox_langchain import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset() For more detailed instructions on using the Toolbox LangChain SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) . Once you’ve installed the [Toolbox Llamaindex SDK](https://github.com/googleapis/genai-toolbox-llamaindex-python) , you can load tools: from toolbox_llamaindex import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application tools = client.load_toolset() For more detailed instructions on using the Toolbox Llamaindex SDK, see the [project’s README](https://github.com/googleapis/genai-toolbox-llamaindex-python/blob/main/README.md) . #### Javascript/Typescript Once you’ve installed the [Toolbox Core SDK](https://www.npmjs.com/package/@toolbox-sdk/core) , you can load tools: * Core * LangChain/Langraph * Genkit * LlamaIndex * ADK TS import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(currTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); // Use these tools in your Langchain/Langraph applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { genkit } from 'genkit'; // Initialise genkit const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => ai.defineTool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }, toolboxTool) // Use these tools in your Genkit applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { tool } from "llamaindex"; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool });; // Use these tools in your LlamaIndex applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/adk'; // Replace with the actual URL where your Toolbox service is running const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const tools = await client.loadToolset(); // Use the client and tools as per requirement For detailed samples on using the Toolbox JS SDK with ADK JS, see the [project’s README.](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main/packages/toolbox-adk/README.md) #### Go * Core * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" ) func main() { // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tools tools, err := client.LoadToolset("toolsetName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } } Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with LangChainGo langChainTool := llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with LangChain Go, see the [module’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go TBGenkit SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/invopop/jsonschema" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() g, err := genkit.Init(ctx) client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Convert the tool using the tbgenkit package // Use this tool with Genkit Go genkitTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } } For end-to-end samples on using the Toolbox Go SDK with Genkit Go, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit/samples) Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var schema *genai.Schema _ = json.Unmarshal(inputschema, &schema) funcDeclaration := &genai.FunctionDeclaration{ Name: tool.Name(), Description: tool.Description(), Parameters: schema, } // Use this tool with Go GenAI genAITool := &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } For end-to-end samples on using the Toolbox Go SDK with Go GenAI, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema openai.FunctionParameters _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with OpenAI Go openAITool := openai.ChatCompletionToolParam{ Function: openai.FunctionDefinitionParam{ Name: tool.Name(), Description: openai.String(tool.Description()), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with OpenAI Go, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go TBADK SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/tbadk) , you can load tools: package main import ( "context" "fmt" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := tbadk.NewToolboxClient(URL) if err != nil { return fmt.Sprintln("Could not start Toolbox Client", err) } // Use this tool with ADK Go tool, err := client.LoadTool("toolName", ctx) if err != nil { return fmt.Sprintln("Could not load Toolbox Tool", err) } } For end-to-end samples on using the Toolbox Go SDK with ADK Go, see the [module’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbadk/samples) For more detailed instructions on using the Toolbox Go SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md) . Last modified March 13, 2026: [chore(main): release 0.29.0 (#2608) (39832a0faa6)](https://github.com/googleapis/genai-toolbox/commit/39832a0faa6e967734f4cf2283ec270aa17fc363) --- # Introduction | MCP Toolbox for Databases Introduction ============ An introduction to MCP Toolbox for Databases. MCP Toolbox for Databases is an open source MCP server for databases. It enables you to develop tools easier, faster, and more securely by handling the complexities such as connection pooling, authentication, and more. Note This solution was originally named “Gen AI Toolbox for Databases” as its initial development predated MCP, but was renamed to align with recently added MCP compatibility. Note This document has been updated to support the configuration file v2 format. To view documentation with configuration file v1 format, please navigate to the top-right menu and select versions v0.26.0 or older. Why Toolbox? ------------ Toolbox helps you build Gen AI tools that let your agents access data in your database. Toolbox provides: * **Simplified development**: Integrate tools to your agent in less than 10 lines of code, reuse tools between multiple agents or frameworks, and deploy new versions of tools more easily. * **Better performance**: Best practices such as connection pooling, authentication, and more. * **Enhanced security**: Integrated auth for more secure access to your data * **End-to-end observability**: Out of the box metrics and tracing with built-in support for OpenTelemetry. **⚡ Supercharge Your Workflow with an AI Database Assistant ⚡** Stop context-switching and let your AI assistant become a true co-developer. By [connecting your IDE to your databases with MCP Toolbox](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/) , you can delegate complex and time-consuming database tasks, allowing you to build faster and focus on what matters. This isn’t just about code completion; it’s about giving your AI the context it needs to handle the entire development lifecycle. Here’s how it will save you time: * **Query in Plain English**: Interact with your data using natural language right from your IDE. Ask complex questions like, _“How many orders were delivered in 2024, and what items were in them?”_ without writing any SQL. * **Automate Database Management**: Simply describe your data needs, and let the AI assistant manage your database for you. It can handle generating queries, creating tables, adding indexes, and more. * **Generate Context-Aware Code**: Empower your AI assistant to generate application code and tests with a deep understanding of your real-time database schema. This accelerates the development cycle by ensuring the generated code is directly usable. * **Slash Development Overhead**: Radically reduce the time spent on manual setup and boilerplate. MCP Toolbox helps streamline lengthy database configurations, repetitive code, and error-prone schema migrations. Learn [how to connect your AI tools (IDEs) to Toolbox using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/) . General Architecture -------------------- Toolbox sits between your application’s orchestration framework and your database, providing a control plane that is used to modify, distribute, or invoke tools. It simplifies the management of your tools by providing you with a centralized location to store and update tools, allowing you to share tools between agents and applications and update those tools without necessarily redeploying your application. ![architecture](https://mcp-toolbox.dev/v0.30.0/getting-started/introduction/architecture.png) Getting Started --------------- ### Quickstart: Running Toolbox using NPX You can run Toolbox directly with a [configuration file](https://mcp-toolbox.dev/v0.30.0/getting-started/configure/) : npx @toolbox-sdk/server --tools-file tools.yaml This runs the latest version of the toolbox server with your configuration file. Note This method should only be used for non-production use cases such as experimentation. For any production use-cases, please consider [Installing the server](https://mcp-toolbox.dev/v0.30.0/#installing-the-server) and then [running it](https://mcp-toolbox.dev/v0.30.0/#running-the-server) . ### Installing the server For the latest version, check the [releases page](https://github.com/googleapis/genai-toolbox/releases) and use the following instructions for your OS and CPU architecture. * Binary * Container image * Homebrew * Compile from source * Linux (AMD64) * macOS (Apple Silicon) * macOS (Intel) * Windows (Command Prompt) * Windows (PowerShell) To install Toolbox as a binary on Linux (AMD64): # see releases page for other versions export VERSION=0.30.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Apple Silicon): # see releases page for other versions export VERSION=0.30.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox chmod +x toolbox To install Toolbox as a binary on macOS (Intel): # see releases page for other versions export VERSION=0.30.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox chmod +x toolbox To install Toolbox as a binary on Windows (Command Prompt): :: see releases page for other versions set VERSION=0.30.0 curl -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v%VERSION%/windows/amd64/toolbox.exe" To install Toolbox as a binary on Windows (PowerShell): # see releases page for other versions $VERSION = "0.30.0" curl.exe -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe" You can also install Toolbox as a container: # see releases page for other versions export VERSION=0.30.0 docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION To install Toolbox using Homebrew on macOS or Linux: brew install mcp-toolbox To install from source, ensure you have the latest version of [Go installed](https://go.dev/doc/install) , and then run the following command: go install github.com/googleapis/[email protected] ### Running the server [Configure](https://mcp-toolbox.dev/v0.30.0/getting-started/configure/) a `tools.yaml` to define your tools, and then execute `toolbox` to start the server: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. #### Launching Toolbox UI To launch Toolbox’s interactive UI, use the `--ui` flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit [Toolbox UI](https://mcp-toolbox.dev/v0.30.0/how-to/toolbox-ui/) . ./toolbox --ui #### Homebrew Users If you installed Toolbox using Homebrew, the `toolbox` binary is available in your system path. You can start the server with the same command: toolbox --tools-file "tools.yaml" You can use `toolbox help` for a full list of flags! To stop the server, send a terminate signal (`ctrl+c` on most platforms). For more detailed documentation on deploying to different environments, check out the resources in the [How-to section](https://mcp-toolbox.dev/v0.30.0/how-to/) ### Integrating your application Once your server is up and running, you can load the tools into your application. See below the list of Client SDKs for using various frameworks: #### Python * Core * LangChain * Llamaindex Once you’ve installed the [Toolbox Core SDK](https://pypi.org/project/toolbox-core/) , you can load tools: from toolbox_core import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = await client.load_toolset("toolset_name") For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/README.md) . Once you’ve installed the [Toolbox LangChain SDK](https://pypi.org/project/toolbox-langchain/) , you can load tools: from toolbox_langchain import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application! tools = client.load_toolset() For more detailed instructions on using the Toolbox LangChain SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-langchain/README.md) . Once you’ve installed the [Toolbox Llamaindex SDK](https://github.com/googleapis/genai-toolbox-llamaindex-python) , you can load tools: from toolbox_llamaindex import ToolboxClient # update the url to point to your server async with ToolboxClient("http://127.0.0.1:5000") as client: # these tools can be passed to your application tools = client.load_toolset() For more detailed instructions on using the Toolbox Llamaindex SDK, see the [project’s README](https://github.com/googleapis/genai-toolbox-llamaindex-python/blob/main/README.md) . #### Javascript/Typescript Once you’ve installed the [Toolbox Core SDK](https://www.npmjs.com/package/@toolbox-sdk/core) , you can load tools: * Core * LangChain/Langraph * Genkit * LlamaIndex * ADK TS import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(currTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); // Use these tools in your Langchain/Langraph applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { genkit } from 'genkit'; // Initialise genkit const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => ai.defineTool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }, toolboxTool) // Use these tools in your Genkit applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/core'; import { tool } from "llamaindex"; // update the url to point to your server const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); // these tools can be passed to your application! const toolboxTools = await client.loadToolset('toolsetName'); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool });; // Use these tools in your LlamaIndex applications const tools = toolboxTools.map(getTool); For more detailed instructions on using the Toolbox Core SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/packages/toolbox-core/README.md) . import { ToolboxClient } from '@toolbox-sdk/adk'; // Replace with the actual URL where your Toolbox service is running const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const tools = await client.loadToolset(); // Use the client and tools as per requirement For detailed samples on using the Toolbox JS SDK with ADK JS, see the [project’s README.](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main/packages/toolbox-adk/README.md) #### Go * Core * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" ) func main() { // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tools tools, err := client.LoadToolset("toolsetName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } } Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" ) func main() { // Make sure to add the error checks // update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with LangChainGo langChainTool := llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: tool.Name(), Description: tool.Description(), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with LangChain Go, see the [module’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go TBGenkit SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/invopop/jsonschema" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() g, err := genkit.Init(ctx) client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Convert the tool using the tbgenkit package // Use this tool with Genkit Go genkitTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } } For end-to-end samples on using the Toolbox Go SDK with Genkit Go, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbgenkit/samples) Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var schema *genai.Schema _ = json.Unmarshal(inputschema, &schema) funcDeclaration := &genai.FunctionDeclaration{ Name: tool.Name(), Description: tool.Description(), Parameters: schema, } // Use this tool with Go GenAI genAITool := &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } For end-to-end samples on using the Toolbox Go SDK with Go GenAI, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go Core SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/core) , you can load tools: package main import ( "context" "encoding/json" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Framework agnostic tool tool, err := client.LoadTool("toolName", ctx) if err != nil { log.Fatalf("Failed to load tools: %v", err) } // Fetch the tool's input schema inputschema, err := tool.InputSchema() if err != nil { log.Fatalf("Failed to fetch inputSchema: %v", err) } var paramsSchema openai.FunctionParameters _ = json.Unmarshal(inputschema, ¶msSchema) // Use this tool with OpenAI Go openAITool := openai.ChatCompletionToolParam{ Function: openai.FunctionDefinitionParam{ Name: tool.Name(), Description: openai.String(tool.Description()), Parameters: paramsSchema, }, } } For end-to-end samples on using the Toolbox Go SDK with OpenAI Go, see the \[module's samples\](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/core/samples) Once you’ve installed the [Go TBADK SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go/tbadk) , you can load tools: package main import ( "context" "fmt" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" ) func main() { // Make sure to add the error checks // Update the url to point to your server URL := "http://127.0.0.1:5000" ctx := context.Background() client, err := tbadk.NewToolboxClient(URL) if err != nil { return fmt.Sprintln("Could not start Toolbox Client", err) } // Use this tool with ADK Go tool, err := client.LoadTool("toolName", ctx) if err != nil { return fmt.Sprintln("Could not load Toolbox Tool", err) } } For end-to-end samples on using the Toolbox Go SDK with ADK Go, see the [module’s samples](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main/tbadk/samples) For more detailed instructions on using the Toolbox Go SDK, see the [project’s README](https://github.com/googleapis/mcp-toolbox-sdk-go/blob/main/core/README.md) . Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # Python Quickstart (Local) | MCP Toolbox for Databases Python Quickstart (Local) ========================= How to get started running MCP Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/getting-started/colab_quickstart.ipynb) Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Python 3.10+](https://wiki.python.org/moin/BeginnersGuide/Download) (including [pip](https://pip.pypa.io/en/stable/installation/) and your preferred virtual environment tool for managing dependencies e.g. [venv](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) ). 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. Tip If you prefer to experiment within a Google Colab environment, you can connect to a [local runtime](https://research.google.com/colaboratory/local-runtimes.html) . 1. In a new terminal, install the SDK package. * ADK * Langchain * LlamaIndex * Core pip install google-adk[toolbox] pip install toolbox-langchain pip install toolbox-llamaindex pip install toolbox-core 2. Install other required dependencies: * ADK * Langchain * LlamaIndex * Core # No other dependencies required for ADK # TODO(developer): replace with correct package if needed pip install langgraph langchain-google-vertexai # pip install langchain-google-genai # pip install langchain-anthropic # TODO(developer): replace with correct package if needed pip install llama-index-llms-google-genai # pip install llama-index-llms-anthropic pip install google-genai 3. Create the agent: * ADK * LangChain * LlamaIndex * Core 1. Create a new agent project. This will create a new directory named `my_agent` with a file `agent.py`. adk create my_agent 2. Update `my_agent/agent.py` with the following content to connect to MCP Toolbox: import asyncio from google.adk import Agent from google.adk.apps import App from google.adk.runners import InMemoryRunner from google.adk.tools.toolbox_toolset import ToolboxToolset from google.genai.types import Content, Part prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ # TODO(developer): update the TOOLBOX_URL to your toolbox endpoint toolset = ToolboxToolset( server_url="http://127.0.0.1:5000", ) root_agent = Agent( name='hotel_assistant', model='gemini-2.5-flash', instruction=prompt, tools=[toolset], ) app = App(root_agent=root_agent, name="my_agent") 3. Create a `.env` file with your Google API key: echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env Create a new file named `agent.py` and copy the following code: import asyncio from langgraph.prebuilt import create_react_agent # TODO(developer): replace this with another import if needed from langchain_google_vertexai import ChatVertexAI # from langchain_google_genai import ChatGoogleGenerativeAI # from langchain_anthropic import ChatAnthropic from langgraph.checkpoint.memory import MemorySaver from toolbox_langchain import ToolboxClient prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed model = ChatVertexAI(model_name="gemini-2.0-flash-001") # model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001") # model = ChatAnthropic(model="claude-3-5-sonnet-20240620") # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = create_react_agent(model, tools, checkpointer=MemorySaver()) config = {"configurable": {"thread_id": "thread-1"}} for query in queries: inputs = {"messages": [("user", prompt + query)]} response = agent.invoke(inputs, stream_mode="values", config=config) print(response["messages"][-1].content) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from llama_index.core.agent.workflow import AgentWorkflow from llama_index.core.workflow import Context # TODO(developer): replace this with another import if needed from llama_index.llms.google_genai import GoogleGenAI # from llama_index.llms.anthropic import Anthropic from toolbox_llamaindex import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed llm = GoogleGenAI( model="gemini-2.0-flash-001", vertexai_config={"project": project, "location": "us-central1"}, ) # llm = GoogleGenAI( # api_key=os.getenv("GOOGLE_API_KEY"), # model="gemini-2.0-flash-001", # ) # llm = Anthropic( # model="claude-3-7-sonnet-latest", # api_key=os.getenv("ANTHROPIC_API_KEY") # ) # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = AgentWorkflow.from_tools_or_functions( tools, llm=llm, system_prompt=prompt, ) ctx = Context(agent) for query in queries: response = await agent.run(user_msg=query, ctx=ctx) print(f"---- {query} ----") print(str(response)) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from google import genai from google.genai.types import ( Content, FunctionDeclaration, GenerateContentConfig, Part, Tool, ) from toolbox_core import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Please book the hotel Hilton Basel for me.",\ "This is too expensive. Please cancel it.",\ "Please book Hyatt Regency for me",\ "My check in dates for my booking would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): async with ToolboxClient("http://127.0.0.1:5000") as toolbox_client: # The toolbox_tools list contains Python callables (functions/methods) designed for LLM tool-use # integration. While this example uses Google's genai client, these callables can be adapted for # various function-calling or agent frameworks. For easier integration with supported frameworks # (https://github.com/googleapis/mcp-toolbox-python-sdk/tree/main/packages), use the # provided wrapper packages, which handle framework-specific boilerplate. toolbox_tools = await toolbox_client.load_toolset("my-toolset") genai_client = genai.Client( vertexai=True, project=project, location="us-central1" ) genai_tools = [\ Tool(\ function_declarations=[\ FunctionDeclaration.from_callable_with_api_option(callable=tool)\ ]\ )\ for tool in toolbox_tools\ ] history = [] for query in queries: user_prompt_content = Content( role="user", parts=[Part.from_text(text=query)], ) history.append(user_prompt_content) response = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( system_instruction=prompt, tools=genai_tools, ), ) history.append(response.candidates[0].content) function_response_parts = [] if response.function_calls: for function_call in response.function_calls: fn_name = function_call.name # The tools are sorted alphabetically if fn_name == "search-hotels-by-name": function_result = await toolbox_tools[3](**function_call.args) elif fn_name == "search-hotels-by-location": function_result = await toolbox_tools[2](**function_call.args) elif fn_name == "book-hotel": function_result = await toolbox_tools[0](**function_call.args) elif fn_name == "update-hotel": function_result = await toolbox_tools[4](**function_call.args) elif fn_name == "cancel-hotel": function_result = await toolbox_tools[1](**function_call.args) else: raise ValueError(f"Function name {fn_name} not present.") function_response = {"result": function_result} function_response_part = Part.from_function_response( name=function_call.name, response=function_response, ) function_response_parts.append(function_response_part) if function_response_parts: tool_response_content = Content(role="tool", parts=function_response_parts) history.append(tool_response_content) response2 = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( tools=genai_tools, ), ) final_model_response_content = response2.candidates[0].content history.append(final_model_response_content) print(response2.text) else: print(response.text) asyncio.run(main()) * ADK * Langchain * LlamaIndex * Core To learn more about Agent Development Kit, check out the [ADK Documentation](https://google.github.io/adk-docs/get-started/python/) . To learn more about Agents in LangChain, check out the [LangGraph Agent Documentation](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) . To learn more about Agents in LlamaIndex, check out the [LlamaIndex AgentWorkflow Documentation](https://docs.llamaindex.ai/en/stable/examples/agent/agent_workflow_basic/) . To learn more about tool calling with Google GenAI, check out the [Google GenAI Documentation](https://github.com/googleapis/python-genai?tab=readme-ov-file#manually-declare-and-invoke-a-function-for-function-calling) . 4. Run your agent, and observe the results: * ADK * Langchain * LlamaIndex * Core Run your agent locally for testing: adk run my_agent Alternatively, serve it via a web interface: adk web --port 8000 For more information, refer to the ADK documentation on [Running Agents](https://google.github.io/adk-docs/get-started/python/#run-your-agent) and [Deploying to Cloud](https://google.github.io/adk-docs/deploy/) . python agent.py python agent.py python agent.py Info For more information, visit the [Python SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-python) . Last modified February 25, 2026: [doc: Fix ADK quickstart rendering with shortcodes (#2541) (182d63c7a08)](https://github.com/googleapis/genai-toolbox/commit/182d63c7a080de7f673ad4364ddfde863405c6cb) --- # Python Quickstart (Local) | MCP Toolbox for Databases Python Quickstart (Local) ========================= How to get started running Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/getting-started/colab_quickstart.ipynb) Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Python 3.10+](https://wiki.python.org/moin/BeginnersGuide/Download) (including [pip](https://pip.pypa.io/en/stable/installation/) and your preferred virtual environment tool for managing dependencies e.g. [venv](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) ). 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. Tip If you prefer to experiment within a Google Colab environment, you can connect to a [local runtime](https://research.google.com/colaboratory/local-runtimes.html) . 1. In a new terminal, install the SDK package. * ADK * Langchain * LlamaIndex * Core pip install google-adk[toolbox] pip install toolbox-langchain pip install toolbox-llamaindex pip install toolbox-core 2. Install other required dependencies: * ADK * Langchain * LlamaIndex * Core # No other dependencies required for ADK # TODO(developer): replace with correct package if needed pip install langgraph langchain-google-vertexai # pip install langchain-google-genai # pip install langchain-anthropic # TODO(developer): replace with correct package if needed pip install llama-index-llms-google-genai # pip install llama-index-llms-anthropic pip install google-genai 3. Create the agent: * ADK * LangChain * LlamaIndex * Core 1. Create a new agent project. This will create a new directory named `my_agent` with a file `agent.py`. adk create my_agent 2. Update `my_agent/agent.py` with the following content to connect to Toolbox:

import asyncio

from google.adk import Agent from google.adk.apps import App from google.adk.runners import InMemoryRunner from google.adk.tools.toolbox_toolset import ToolboxToolset from google.genai.types import Content, Part

prompt = """ You’re a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it’s name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don’t ask for confirmations from the user. """

TODO(developer): update the TOOLBOX_URL to your toolbox endpoint

toolset = ToolboxToolset( server_url=“http://127.0.0.1:5000”, )

root_agent = Agent( name=‘hotel_assistant’, model=‘gemini-2.5-flash’, instruction=prompt, tools=[toolset], )

app = App(root_agent=root_agent, name=“my_agent”)

3. Create a `.env` file with your Google API key: echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env Create a new file named `agent.py` and copy the following code: import asyncio from langgraph.prebuilt import create_react_agent # TODO(developer): replace this with another import if needed from langchain_google_vertexai import ChatVertexAI # from langchain_google_genai import ChatGoogleGenerativeAI # from langchain_anthropic import ChatAnthropic from langgraph.checkpoint.memory import MemorySaver from toolbox_langchain import ToolboxClient prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed model = ChatVertexAI(model_name="gemini-2.0-flash-001") # model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001") # model = ChatAnthropic(model="claude-3-5-sonnet-20240620") # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = create_react_agent(model, tools, checkpointer=MemorySaver()) config = {"configurable": {"thread_id": "thread-1"}} for query in queries: inputs = {"messages": [("user", prompt + query)]} response = agent.invoke(inputs, stream_mode="values", config=config) print(response["messages"][-1].content) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from llama_index.core.agent.workflow import AgentWorkflow from llama_index.core.workflow import Context # TODO(developer): replace this with another import if needed from llama_index.llms.google_genai import GoogleGenAI # from llama_index.llms.anthropic import Anthropic from toolbox_llamaindex import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed llm = GoogleGenAI( model="gemini-2.0-flash-001", vertexai_config={"project": project, "location": "us-central1"}, ) # llm = GoogleGenAI( # api_key=os.getenv("GOOGLE_API_KEY"), # model="gemini-2.0-flash-001", # ) # llm = Anthropic( # model="claude-3-7-sonnet-latest", # api_key=os.getenv("ANTHROPIC_API_KEY") # ) # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = AgentWorkflow.from_tools_or_functions( tools, llm=llm, system_prompt=prompt, ) ctx = Context(agent) for query in queries: response = await agent.run(user_msg=query, ctx=ctx) print(f"---- {query} ----") print(str(response)) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from google import genai from google.genai.types import ( Content, FunctionDeclaration, GenerateContentConfig, Part, Tool, ) from toolbox_core import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Please book the hotel Hilton Basel for me.",\ "This is too expensive. Please cancel it.",\ "Please book Hyatt Regency for me",\ "My check in dates for my booking would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): async with ToolboxClient("http://127.0.0.1:5000") as toolbox_client: # The toolbox_tools list contains Python callables (functions/methods) designed for LLM tool-use # integration. While this example uses Google's genai client, these callables can be adapted for # various function-calling or agent frameworks. For easier integration with supported frameworks # (https://github.com/googleapis/mcp-toolbox-python-sdk/tree/main/packages), use the # provided wrapper packages, which handle framework-specific boilerplate. toolbox_tools = await toolbox_client.load_toolset("my-toolset") genai_client = genai.Client( vertexai=True, project=project, location="us-central1" ) genai_tools = [\ Tool(\ function_declarations=[\ FunctionDeclaration.from_callable_with_api_option(callable=tool)\ ]\ )\ for tool in toolbox_tools\ ] history = [] for query in queries: user_prompt_content = Content( role="user", parts=[Part.from_text(text=query)], ) history.append(user_prompt_content) response = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( system_instruction=prompt, tools=genai_tools, ), ) history.append(response.candidates[0].content) function_response_parts = [] if response.function_calls: for function_call in response.function_calls: fn_name = function_call.name # The tools are sorted alphabetically if fn_name == "search-hotels-by-name": function_result = await toolbox_tools[3](**function_call.args) elif fn_name == "search-hotels-by-location": function_result = await toolbox_tools[2](**function_call.args) elif fn_name == "book-hotel": function_result = await toolbox_tools[0](**function_call.args) elif fn_name == "update-hotel": function_result = await toolbox_tools[4](**function_call.args) elif fn_name == "cancel-hotel": function_result = await toolbox_tools[1](**function_call.args) else: raise ValueError(f"Function name {fn_name} not present.") function_response = {"result": function_result} function_response_part = Part.from_function_response( name=function_call.name, response=function_response, ) function_response_parts.append(function_response_part) if function_response_parts: tool_response_content = Content(role="tool", parts=function_response_parts) history.append(tool_response_content) response2 = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( tools=genai_tools, ), ) final_model_response_content = response2.candidates[0].content history.append(final_model_response_content) print(response2.text) else: print(response.text) asyncio.run(main()) * ADK * Langchain * LlamaIndex * Core To learn more about Agent Development Kit, check out the [ADK Documentation](https://google.github.io/adk-docs/get-started/python/) . To learn more about Agents in LangChain, check out the [LangGraph Agent Documentation](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) . To learn more about Agents in LlamaIndex, check out the [LlamaIndex AgentWorkflow Documentation](https://docs.llamaindex.ai/en/stable/examples/agent/agent_workflow_basic/) . To learn more about tool calling with Google GenAI, check out the [Google GenAI Documentation](https://github.com/googleapis/python-genai?tab=readme-ov-file#manually-declare-and-invoke-a-function-for-function-calling) . 4. Run your agent, and observe the results: * ADK * Langchain * LlamaIndex * Core Run your agent locally for testing: adk run my_agent Alternatively, serve it via a web interface: adk web --port 8000 For more information, refer to the ADK documentation on [Running Agents](https://google.github.io/adk-docs/get-started/python/#run-your-agent) and [Deploying to Cloud](https://google.github.io/adk-docs/deploy/) . python agent.py python agent.py python agent.py Info For more information, visit the [Python SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-python) . Last modified February 11, 2026: [docs(adk): align quickstart script with other orchestrations (#2423) (1f8019c50a0)](https://github.com/googleapis/genai-toolbox/commit/1f8019c50a06d65553abd93da833b6dba09c612b) --- # Python Quickstart (Local) | MCP Toolbox for Databases Python Quickstart (Local) ========================= How to get started running MCP Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/getting-started/colab_quickstart.ipynb) Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Python 3.10+](https://wiki.python.org/moin/BeginnersGuide/Download) (including [pip](https://pip.pypa.io/en/stable/installation/) and your preferred virtual environment tool for managing dependencies e.g. [venv](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) ). 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. Tip If you prefer to experiment within a Google Colab environment, you can connect to a [local runtime](https://research.google.com/colaboratory/local-runtimes.html) . 1. In a new terminal, install the SDK package. * ADK * Langchain * LlamaIndex * Core pip install google-adk[toolbox] pip install toolbox-langchain pip install toolbox-llamaindex pip install toolbox-core 2. Install other required dependencies: * ADK * Langchain * LlamaIndex * Core # No other dependencies required for ADK # TODO(developer): replace with correct package if needed pip install langgraph langchain-google-vertexai # pip install langchain-google-genai # pip install langchain-anthropic # TODO(developer): replace with correct package if needed pip install llama-index-llms-google-genai # pip install llama-index-llms-anthropic pip install google-genai 3. Create the agent: * ADK * LangChain * LlamaIndex * Core 1. Create a new agent project. This will create a new directory named `my_agent` with a file `agent.py`. adk create my_agent 2. Update `my_agent/agent.py` with the following content to connect to MCP Toolbox: import asyncio from google.adk import Agent from google.adk.apps import App from google.adk.runners import InMemoryRunner from google.adk.tools.toolbox_toolset import ToolboxToolset from google.genai.types import Content, Part prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ # TODO(developer): update the TOOLBOX_URL to your toolbox endpoint toolset = ToolboxToolset( server_url="http://127.0.0.1:5000", ) root_agent = Agent( name='hotel_assistant', model='gemini-2.5-flash', instruction=prompt, tools=[toolset], ) app = App(root_agent=root_agent, name="my_agent") 3. Create a `.env` file with your Google API key: echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env Create a new file named `agent.py` and copy the following code: import asyncio from langgraph.prebuilt import create_react_agent # TODO(developer): replace this with another import if needed from langchain_google_vertexai import ChatVertexAI # from langchain_google_genai import ChatGoogleGenerativeAI # from langchain_anthropic import ChatAnthropic from langgraph.checkpoint.memory import MemorySaver from toolbox_langchain import ToolboxClient prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed model = ChatVertexAI(model_name="gemini-2.0-flash-001") # model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001") # model = ChatAnthropic(model="claude-3-5-sonnet-20240620") # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = create_react_agent(model, tools, checkpointer=MemorySaver()) config = {"configurable": {"thread_id": "thread-1"}} for query in queries: inputs = {"messages": [("user", prompt + query)]} response = agent.invoke(inputs, stream_mode="values", config=config) print(response["messages"][-1].content) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from llama_index.core.agent.workflow import AgentWorkflow from llama_index.core.workflow import Context # TODO(developer): replace this with another import if needed from llama_index.llms.google_genai import GoogleGenAI # from llama_index.llms.anthropic import Anthropic from toolbox_llamaindex import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed llm = GoogleGenAI( model="gemini-2.0-flash-001", vertexai_config={"project": project, "location": "us-central1"}, ) # llm = GoogleGenAI( # api_key=os.getenv("GOOGLE_API_KEY"), # model="gemini-2.0-flash-001", # ) # llm = Anthropic( # model="claude-3-7-sonnet-latest", # api_key=os.getenv("ANTHROPIC_API_KEY") # ) # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = AgentWorkflow.from_tools_or_functions( tools, llm=llm, system_prompt=prompt, ) ctx = Context(agent) for query in queries: response = await agent.run(user_msg=query, ctx=ctx) print(f"---- {query} ----") print(str(response)) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from google import genai from google.genai.types import ( Content, FunctionDeclaration, GenerateContentConfig, Part, Tool, ) from toolbox_core import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Please book the hotel Hilton Basel for me.",\ "This is too expensive. Please cancel it.",\ "Please book Hyatt Regency for me",\ "My check in dates for my booking would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): async with ToolboxClient("http://127.0.0.1:5000") as toolbox_client: # The toolbox_tools list contains Python callables (functions/methods) designed for LLM tool-use # integration. While this example uses Google's genai client, these callables can be adapted for # various function-calling or agent frameworks. For easier integration with supported frameworks # (https://github.com/googleapis/mcp-toolbox-python-sdk/tree/main/packages), use the # provided wrapper packages, which handle framework-specific boilerplate. toolbox_tools = await toolbox_client.load_toolset("my-toolset") genai_client = genai.Client( vertexai=True, project=project, location="us-central1" ) genai_tools = [\ Tool(\ function_declarations=[\ FunctionDeclaration.from_callable_with_api_option(callable=tool)\ ]\ )\ for tool in toolbox_tools\ ] history = [] for query in queries: user_prompt_content = Content( role="user", parts=[Part.from_text(text=query)], ) history.append(user_prompt_content) response = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( system_instruction=prompt, tools=genai_tools, ), ) history.append(response.candidates[0].content) function_response_parts = [] if response.function_calls: for function_call in response.function_calls: fn_name = function_call.name # The tools are sorted alphabetically if fn_name == "search-hotels-by-name": function_result = await toolbox_tools[3](**function_call.args) elif fn_name == "search-hotels-by-location": function_result = await toolbox_tools[2](**function_call.args) elif fn_name == "book-hotel": function_result = await toolbox_tools[0](**function_call.args) elif fn_name == "update-hotel": function_result = await toolbox_tools[4](**function_call.args) elif fn_name == "cancel-hotel": function_result = await toolbox_tools[1](**function_call.args) else: raise ValueError(f"Function name {fn_name} not present.") function_response = {"result": function_result} function_response_part = Part.from_function_response( name=function_call.name, response=function_response, ) function_response_parts.append(function_response_part) if function_response_parts: tool_response_content = Content(role="tool", parts=function_response_parts) history.append(tool_response_content) response2 = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( tools=genai_tools, ), ) final_model_response_content = response2.candidates[0].content history.append(final_model_response_content) print(response2.text) else: print(response.text) asyncio.run(main()) * ADK * Langchain * LlamaIndex * Core To learn more about Agent Development Kit, check out the [ADK Documentation](https://google.github.io/adk-docs/get-started/python/) . To learn more about Agents in LangChain, check out the [LangGraph Agent Documentation](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) . To learn more about Agents in LlamaIndex, check out the [LlamaIndex AgentWorkflow Documentation](https://docs.llamaindex.ai/en/stable/examples/agent/agent_workflow_basic/) . To learn more about tool calling with Google GenAI, check out the [Google GenAI Documentation](https://github.com/googleapis/python-genai?tab=readme-ov-file#manually-declare-and-invoke-a-function-for-function-calling) . 4. Run your agent, and observe the results: * ADK * Langchain * LlamaIndex * Core Run your agent locally for testing: adk run my_agent Alternatively, serve it via a web interface: adk web --port 8000 For more information, refer to the ADK documentation on [Running Agents](https://google.github.io/adk-docs/get-started/python/#run-your-agent) and [Deploying to Cloud](https://google.github.io/adk-docs/deploy/) . python agent.py python agent.py python agent.py Info For more information, visit the [Python SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-python) . Last modified February 25, 2026: [doc: Fix ADK quickstart rendering with shortcodes (#2541) (182d63c7a08)](https://github.com/googleapis/genai-toolbox/commit/182d63c7a080de7f673ad4364ddfde863405c6cb) --- # JS Quickstart (Local) | MCP Toolbox for Databases JS Quickstart (Local) ===================== How to get started running Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Node.js (v18 or higher)](https://nodejs.org/) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. 1. (Optional) Initialize a Node.js project: npm init -y 2. In a new terminal, install the SDK package. * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/adk 3. Install other required dependencies * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install langchain @langchain/google-genai npm install genkit @genkit-ai/googleai npm install llamaindex @llamaindex/google @llamaindex/workflow npm install @google/genai npm install @google/adk 4. Create a new file named `hotelAgent.js` and copy the following code to create an agent: * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK import { ChatGoogleGenerativeAI } from "@langchain/google-genai"; import { ToolboxClient } from "@toolbox-sdk/core"; import { tool } from "@langchain/core/tools"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { MemorySaver } from "@langchain/langgraph"; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const model = new ChatGoogleGenerativeAI({ model: "gemini-2.0-flash", }); const client = new ToolboxClient("http://127.0.0.1:5000"); const toolboxTools = await client.loadToolset("my-toolset"); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(toolboxTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); const tools = toolboxTools.map(getTool); const agent = createReactAgent({ llm: model, tools: tools, checkpointer: new MemorySaver(), systemPrompt: prompt, }); const langGraphConfig = { configurable: { thread_id: "test-thread", }, }; for (const query of queries) { const agentOutput = await agent.invoke( { messages: [\ {\ role: "user",\ content: query,\ },\ ], verbose: true, }, langGraphConfig ); const response = agentOutput.messages[agentOutput.messages.length - 1].content; console.log(response); } } main(); import { ToolboxClient } from "@toolbox-sdk/core"; import { genkit } from "genkit"; import { googleAI } from '@genkit-ai/googleai'; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const toolboxClient = new ToolboxClient("http://127.0.0.1:5000"); const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const toolMap = Object.fromEntries( toolboxTools.map((tool) => { const definedTool = ai.defineTool( { name: tool.getName(), description: tool.getDescription(), inputSchema: tool.getParamSchema(), }, tool ); return [tool.getName(), definedTool]; }) ); const tools = Object.values(toolMap); let conversationHistory = [{ role: "system", content: [{ text: systemPrompt }] }]; for (const query of queries) { conversationHistory.push({ role: "user", content: [{ text: query }] }); const response = await ai.generate({ messages: conversationHistory, tools: tools, }); conversationHistory.push(response.message); const toolRequests = response.toolRequests; if (toolRequests?.length > 0) { // Execute tools concurrently and collect their responses. const toolResponses = await Promise.all( toolRequests.map(async (call) => { try { const toolOutput = await toolMap[call.name].invoke(call.input); return { role: "tool", content: [{ toolResponse: { name: call.name, output: toolOutput } }] }; } catch (e) { console.error(`Error executing tool ${call.name}:`, e); return { role: "tool", content: [{ toolResponse: { name: call.name, output: { error: e.message } } }] }; } }) ); conversationHistory.push(...toolResponses); // Call the AI again with the tool results. response = await ai.generate({ messages: conversationHistory, tools }); conversationHistory.push(response.message); } console.log(response.text); } } main(); import { gemini, GEMINI_MODEL } from "@llamaindex/google"; import { agent } from "@llamaindex/workflow"; import { createMemory, staticBlock, tool } from "llamaindex"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches — this is very important for operations. For any bookings or cancellations, please provide the appropriate confirmation. Update check-in or check-out dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { // Connect to MCP Toolbox const client = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await client.loadToolset("my-toolset"); const tools = toolboxTools.map((toolboxTool) => { return tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool, }); }); // Initialize LLM const llm = gemini({ model: GEMINI_MODEL.GEMINI_2_0_FLASH, apiKey: GOOGLE_API_KEY, }); const memory = createMemory({ memoryBlocks: [\ staticBlock({\ content: prompt,\ }),\ ], }); // Create the Agent const myAgent = agent({ tools: tools, llm, memory, systemPrompt: prompt, }); for (const query of queries) { const result = await myAgent.run(query); const output = result.data.result; console.log(`\nUser: ${query}`); if (typeof output === "string") { console.log(output.trim()); } else if (typeof output === "object" && "text" in output) { console.log(output.text.trim()); } else { console.log(JSON.stringify(output)); } } //You may observe some extra logs during execution due to the run method provided by Llama. console.log("Agent run finished."); } main(); import { GoogleGenAI } from "@google/genai"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, you MUST use the available tools to find information. Mention its name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; function mapZodTypeToOpenAPIType(zodTypeName) { const typeMap = { 'ZodString': 'string', 'ZodNumber': 'number', 'ZodBoolean': 'boolean', 'ZodArray': 'array', 'ZodObject': 'object', }; return typeMap[zodTypeName] || 'string'; } export async function main() { const toolboxClient = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const geminiTools = [{\ functionDeclarations: toolboxTools.map(tool => {\ \ const schema = tool.getParamSchema();\ const properties = {};\ const required = [];\ \ \ for (const [key, param] of Object.entries(schema.shape)) {\ properties[key] = {\ type: mapZodTypeToOpenAPIType(param.constructor.name),\ description: param.description || '',\ };\ required.push(key)\ }\ \ return {\ name: tool.getName(),\ description: tool.getDescription(),\ parameters: { type: 'object', properties, required },\ };\ })\ }]; const genAI = new GoogleGenAI({ apiKey: GOOGLE_API_KEY }); const chat = genAI.chats.create({ model: "gemini-2.5-flash", config: { systemInstruction: prompt, tools: geminiTools, } }); for (const query of queries) { let currentResult = await chat.sendMessage({ message: query }); let finalResponseGiven = false while (!finalResponseGiven) { const response = currentResult; const functionCalls = response.functionCalls || []; if (functionCalls.length === 0) { console.log(response.text) finalResponseGiven = true; } else { const toolResponses = []; for (const call of functionCalls) { const toolName = call.name const toolToExecute = toolboxTools.find(t => t.getName() === toolName); if (toolToExecute) { try { const functionResult = await toolToExecute(call.args); toolResponses.push({ functionResponse: { name: call.name, response: { result: functionResult } } }); } catch (e) { console.error(`Error executing tool '${toolName}':`, e); toolResponses.push({ functionResponse: { name: call.name, response: { error: e.message } } }); } } } currentResult = await chat.sendMessage({ message: toolResponses }); } } } } main(); import { InMemoryRunner, LlmAgent, LogLevel } from '@google/adk'; import { ToolboxClient } from '@toolbox-sdk/adk'; const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; process.env.GOOGLE_GENAI_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key export async function main() { const userId = 'test_user'; const client = new ToolboxClient('http://127.0.0.1:5000'); const tools = await client.loadToolset("my-toolset"); const rootAgent = new LlmAgent({ name: 'hotel_agent', model: 'gemini-2.5-flash', description: 'Agent for hotel bookings and administration.', instruction: prompt, tools: tools, }); const appName = rootAgent.name; const runner = new InMemoryRunner({ agent: rootAgent, appName, logLevel: LogLevel.ERROR, }); const session = await runner.sessionService.createSession({ appName, userId }); for (const query of queries) { await runPrompt(runner, userId, session.id, query); } } async function runPrompt(runner, userId, sessionId, prompt) { const content = { role: 'user', parts: [{ text: prompt }] }; const stream = runner.runAsync({ userId, sessionId, newMessage: content }); const responses = await Array.fromAsync(stream); const accumulatedResponse = responses .flatMap((e) => e.content?.parts?.map((p) => p.text) ?? []) .join(''); console.log(`\nMODEL RESPONSE: ${accumulatedResponse}\n`); } main(); 5. Run your agent, and observe the results: node hotelAgent.js Info For more information, visit the [JS SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-js) . Last modified December 4, 2025: [docs(toolbox-adk): Add quickstart for ADK JS SDK (#1862) (1e67810740d)](https://github.com/googleapis/genai-toolbox/commit/1e67810740d6e4d1d04a3e6122ba405afcd88477) --- # JS Quickstart (Local) | MCP Toolbox for Databases JS Quickstart (Local) ===================== How to get started running Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Node.js (v18 or higher)](https://nodejs.org/) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. 1. (Optional) Initialize a Node.js project: npm init -y 2. In a new terminal, install the SDK package. * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/adk 3. Install other required dependencies * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install langchain @langchain/google-genai npm install genkit @genkit-ai/googleai npm install llamaindex @llamaindex/google @llamaindex/workflow npm install @google/genai npm install @google/adk 4. Create a new file named `hotelAgent.js` and copy the following code to create an agent: * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK import { ChatGoogleGenerativeAI } from "@langchain/google-genai"; import { ToolboxClient } from "@toolbox-sdk/core"; import { tool } from "@langchain/core/tools"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { MemorySaver } from "@langchain/langgraph"; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const model = new ChatGoogleGenerativeAI({ model: "gemini-2.0-flash", }); const client = new ToolboxClient("http://127.0.0.1:5000"); const toolboxTools = await client.loadToolset("my-toolset"); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(toolboxTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); const tools = toolboxTools.map(getTool); const agent = createReactAgent({ llm: model, tools: tools, checkpointer: new MemorySaver(), systemPrompt: prompt, }); const langGraphConfig = { configurable: { thread_id: "test-thread", }, }; for (const query of queries) { const agentOutput = await agent.invoke( { messages: [\ {\ role: "user",\ content: query,\ },\ ], verbose: true, }, langGraphConfig ); const response = agentOutput.messages[agentOutput.messages.length - 1].content; console.log(response); } } main(); import { ToolboxClient } from "@toolbox-sdk/core"; import { genkit } from "genkit"; import { googleAI } from '@genkit-ai/googleai'; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const toolboxClient = new ToolboxClient("http://127.0.0.1:5000"); const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const toolMap = Object.fromEntries( toolboxTools.map((tool) => { const definedTool = ai.defineTool( { name: tool.getName(), description: tool.getDescription(), inputSchema: tool.getParamSchema(), }, tool ); return [tool.getName(), definedTool]; }) ); const tools = Object.values(toolMap); let conversationHistory = [{ role: "system", content: [{ text: systemPrompt }] }]; for (const query of queries) { conversationHistory.push({ role: "user", content: [{ text: query }] }); const response = await ai.generate({ messages: conversationHistory, tools: tools, }); conversationHistory.push(response.message); const toolRequests = response.toolRequests; if (toolRequests?.length > 0) { // Execute tools concurrently and collect their responses. const toolResponses = await Promise.all( toolRequests.map(async (call) => { try { const toolOutput = await toolMap[call.name].invoke(call.input); return { role: "tool", content: [{ toolResponse: { name: call.name, output: toolOutput } }] }; } catch (e) { console.error(`Error executing tool ${call.name}:`, e); return { role: "tool", content: [{ toolResponse: { name: call.name, output: { error: e.message } } }] }; } }) ); conversationHistory.push(...toolResponses); // Call the AI again with the tool results. response = await ai.generate({ messages: conversationHistory, tools }); conversationHistory.push(response.message); } console.log(response.text); } } main(); import { gemini, GEMINI_MODEL } from "@llamaindex/google"; import { agent } from "@llamaindex/workflow"; import { createMemory, staticBlock, tool } from "llamaindex"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches — this is very important for operations. For any bookings or cancellations, please provide the appropriate confirmation. Update check-in or check-out dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { // Connect to MCP Toolbox const client = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await client.loadToolset("my-toolset"); const tools = toolboxTools.map((toolboxTool) => { return tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool, }); }); // Initialize LLM const llm = gemini({ model: GEMINI_MODEL.GEMINI_2_0_FLASH, apiKey: GOOGLE_API_KEY, }); const memory = createMemory({ memoryBlocks: [\ staticBlock({\ content: prompt,\ }),\ ], }); // Create the Agent const myAgent = agent({ tools: tools, llm, memory, systemPrompt: prompt, }); for (const query of queries) { const result = await myAgent.run(query); const output = result.data.result; console.log(`\nUser: ${query}`); if (typeof output === "string") { console.log(output.trim()); } else if (typeof output === "object" && "text" in output) { console.log(output.text.trim()); } else { console.log(JSON.stringify(output)); } } //You may observe some extra logs during execution due to the run method provided by Llama. console.log("Agent run finished."); } main(); import { GoogleGenAI } from "@google/genai"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, you MUST use the available tools to find information. Mention its name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; function mapZodTypeToOpenAPIType(zodTypeName) { const typeMap = { 'ZodString': 'string', 'ZodNumber': 'number', 'ZodBoolean': 'boolean', 'ZodArray': 'array', 'ZodObject': 'object', }; return typeMap[zodTypeName] || 'string'; } export async function main() { const toolboxClient = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const geminiTools = [{\ functionDeclarations: toolboxTools.map(tool => {\ \ const schema = tool.getParamSchema();\ const properties = {};\ const required = [];\ \ \ for (const [key, param] of Object.entries(schema.shape)) {\ properties[key] = {\ type: mapZodTypeToOpenAPIType(param.constructor.name),\ description: param.description || '',\ };\ required.push(key)\ }\ \ return {\ name: tool.getName(),\ description: tool.getDescription(),\ parameters: { type: 'object', properties, required },\ };\ })\ }]; const genAI = new GoogleGenAI({ apiKey: GOOGLE_API_KEY }); const chat = genAI.chats.create({ model: "gemini-2.5-flash", config: { systemInstruction: prompt, tools: geminiTools, } }); for (const query of queries) { let currentResult = await chat.sendMessage({ message: query }); let finalResponseGiven = false while (!finalResponseGiven) { const response = currentResult; const functionCalls = response.functionCalls || []; if (functionCalls.length === 0) { console.log(response.text) finalResponseGiven = true; } else { const toolResponses = []; for (const call of functionCalls) { const toolName = call.name const toolToExecute = toolboxTools.find(t => t.getName() === toolName); if (toolToExecute) { try { const functionResult = await toolToExecute(call.args); toolResponses.push({ functionResponse: { name: call.name, response: { result: functionResult } } }); } catch (e) { console.error(`Error executing tool '${toolName}':`, e); toolResponses.push({ functionResponse: { name: call.name, response: { error: e.message } } }); } } } currentResult = await chat.sendMessage({ message: toolResponses }); } } } } main(); import { InMemoryRunner, LlmAgent, LogLevel } from '@google/adk'; import { ToolboxClient } from '@toolbox-sdk/adk'; const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; process.env.GOOGLE_GENAI_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key export async function main() { const userId = 'test_user'; const client = new ToolboxClient('http://127.0.0.1:5000'); const tools = await client.loadToolset("my-toolset"); const rootAgent = new LlmAgent({ name: 'hotel_agent', model: 'gemini-2.5-flash', description: 'Agent for hotel bookings and administration.', instruction: prompt, tools: tools, }); const appName = rootAgent.name; const runner = new InMemoryRunner({ agent: rootAgent, appName, logLevel: LogLevel.ERROR, }); const session = await runner.sessionService.createSession({ appName, userId }); for (const query of queries) { await runPrompt(runner, userId, session.id, query); } } async function runPrompt(runner, userId, sessionId, prompt) { const content = { role: 'user', parts: [{ text: prompt }] }; const stream = runner.runAsync({ userId, sessionId, newMessage: content }); const responses = await Array.fromAsync(stream); const accumulatedResponse = responses .flatMap((e) => e.content?.parts?.map((p) => p.text) ?? []) .join(''); console.log(`\nMODEL RESPONSE: ${accumulatedResponse}\n`); } main(); 5. Run your agent, and observe the results: node hotelAgent.js Info For more information, visit the [JS SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-js) . Last modified December 4, 2025: [docs(toolbox-adk): Add quickstart for ADK JS SDK (#1862) (1e67810740d)](https://github.com/googleapis/genai-toolbox/commit/1e67810740d6e4d1d04a3e6122ba405afcd88477) --- # JS Quickstart (Local) | MCP Toolbox for Databases JS Quickstart (Local) ===================== How to get started running Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Node.js (v18 or higher)](https://nodejs.org/) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. 1. (Optional) Initialize a Node.js project: npm init -y 2. In a new terminal, install the SDK package. * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/adk 3. Install other required dependencies * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install langchain @langchain/google-genai npm install genkit @genkit-ai/googleai npm install llamaindex @llamaindex/google @llamaindex/workflow npm install @google/genai npm install @google/adk 4. Create a new file named `hotelAgent.js` and copy the following code to create an agent: * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK import { ChatGoogleGenerativeAI } from "@langchain/google-genai"; import { ToolboxClient } from "@toolbox-sdk/core"; import { tool } from "@langchain/core/tools"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { MemorySaver } from "@langchain/langgraph"; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const model = new ChatGoogleGenerativeAI({ model: "gemini-2.0-flash", }); const client = new ToolboxClient("http://127.0.0.1:5000"); const toolboxTools = await client.loadToolset("my-toolset"); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(toolboxTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); const tools = toolboxTools.map(getTool); const agent = createReactAgent({ llm: model, tools: tools, checkpointer: new MemorySaver(), systemPrompt: prompt, }); const langGraphConfig = { configurable: { thread_id: "test-thread", }, }; for (const query of queries) { const agentOutput = await agent.invoke( { messages: [\ {\ role: "user",\ content: query,\ },\ ], verbose: true, }, langGraphConfig ); const response = agentOutput.messages[agentOutput.messages.length - 1].content; console.log(response); } } main(); import { ToolboxClient } from "@toolbox-sdk/core"; import { genkit } from "genkit"; import { googleAI } from '@genkit-ai/googleai'; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const toolboxClient = new ToolboxClient("http://127.0.0.1:5000"); const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const toolMap = Object.fromEntries( toolboxTools.map((tool) => { const definedTool = ai.defineTool( { name: tool.getName(), description: tool.getDescription(), inputSchema: tool.getParamSchema(), }, tool ); return [tool.getName(), definedTool]; }) ); const tools = Object.values(toolMap); let conversationHistory = [{ role: "system", content: [{ text: systemPrompt }] }]; for (const query of queries) { conversationHistory.push({ role: "user", content: [{ text: query }] }); const response = await ai.generate({ messages: conversationHistory, tools: tools, }); conversationHistory.push(response.message); const toolRequests = response.toolRequests; if (toolRequests?.length > 0) { // Execute tools concurrently and collect their responses. const toolResponses = await Promise.all( toolRequests.map(async (call) => { try { const toolOutput = await toolMap[call.name].invoke(call.input); return { role: "tool", content: [{ toolResponse: { name: call.name, output: toolOutput } }] }; } catch (e) { console.error(`Error executing tool ${call.name}:`, e); return { role: "tool", content: [{ toolResponse: { name: call.name, output: { error: e.message } } }] }; } }) ); conversationHistory.push(...toolResponses); // Call the AI again with the tool results. response = await ai.generate({ messages: conversationHistory, tools }); conversationHistory.push(response.message); } console.log(response.text); } } main(); import { gemini, GEMINI_MODEL } from "@llamaindex/google"; import { agent } from "@llamaindex/workflow"; import { createMemory, staticBlock, tool } from "llamaindex"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches — this is very important for operations. For any bookings or cancellations, please provide the appropriate confirmation. Update check-in or check-out dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { // Connect to MCP Toolbox const client = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await client.loadToolset("my-toolset"); const tools = toolboxTools.map((toolboxTool) => { return tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool, }); }); // Initialize LLM const llm = gemini({ model: GEMINI_MODEL.GEMINI_2_0_FLASH, apiKey: GOOGLE_API_KEY, }); const memory = createMemory({ memoryBlocks: [\ staticBlock({\ content: prompt,\ }),\ ], }); // Create the Agent const myAgent = agent({ tools: tools, llm, memory, systemPrompt: prompt, }); for (const query of queries) { const result = await myAgent.run(query); const output = result.data.result; console.log(`\nUser: ${query}`); if (typeof output === "string") { console.log(output.trim()); } else if (typeof output === "object" && "text" in output) { console.log(output.text.trim()); } else { console.log(JSON.stringify(output)); } } //You may observe some extra logs during execution due to the run method provided by Llama. console.log("Agent run finished."); } main(); import { GoogleGenAI } from "@google/genai"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, you MUST use the available tools to find information. Mention its name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; function mapZodTypeToOpenAPIType(zodTypeName) { const typeMap = { 'ZodString': 'string', 'ZodNumber': 'number', 'ZodBoolean': 'boolean', 'ZodArray': 'array', 'ZodObject': 'object', }; return typeMap[zodTypeName] || 'string'; } export async function main() { const toolboxClient = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const geminiTools = [{\ functionDeclarations: toolboxTools.map(tool => {\ \ const schema = tool.getParamSchema();\ const properties = {};\ const required = [];\ \ \ for (const [key, param] of Object.entries(schema.shape)) {\ properties[key] = {\ type: mapZodTypeToOpenAPIType(param.constructor.name),\ description: param.description || '',\ };\ required.push(key)\ }\ \ return {\ name: tool.getName(),\ description: tool.getDescription(),\ parameters: { type: 'object', properties, required },\ };\ })\ }]; const genAI = new GoogleGenAI({ apiKey: GOOGLE_API_KEY }); const chat = genAI.chats.create({ model: "gemini-2.5-flash", config: { systemInstruction: prompt, tools: geminiTools, } }); for (const query of queries) { let currentResult = await chat.sendMessage({ message: query }); let finalResponseGiven = false while (!finalResponseGiven) { const response = currentResult; const functionCalls = response.functionCalls || []; if (functionCalls.length === 0) { console.log(response.text) finalResponseGiven = true; } else { const toolResponses = []; for (const call of functionCalls) { const toolName = call.name const toolToExecute = toolboxTools.find(t => t.getName() === toolName); if (toolToExecute) { try { const functionResult = await toolToExecute(call.args); toolResponses.push({ functionResponse: { name: call.name, response: { result: functionResult } } }); } catch (e) { console.error(`Error executing tool '${toolName}':`, e); toolResponses.push({ functionResponse: { name: call.name, response: { error: e.message } } }); } } } currentResult = await chat.sendMessage({ message: toolResponses }); } } } } main(); import { InMemoryRunner, LlmAgent, LogLevel } from '@google/adk'; import { ToolboxClient } from '@toolbox-sdk/adk'; const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; process.env.GOOGLE_GENAI_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key export async function main() { const userId = 'test_user'; const client = new ToolboxClient('http://127.0.0.1:5000'); const tools = await client.loadToolset("my-toolset"); const rootAgent = new LlmAgent({ name: 'hotel_agent', model: 'gemini-2.5-flash', description: 'Agent for hotel bookings and administration.', instruction: prompt, tools: tools, }); const appName = rootAgent.name; const runner = new InMemoryRunner({ agent: rootAgent, appName, logLevel: LogLevel.ERROR, }); const session = await runner.sessionService.createSession({ appName, userId }); for (const query of queries) { await runPrompt(runner, userId, session.id, query); } } async function runPrompt(runner, userId, sessionId, prompt) { const content = { role: 'user', parts: [{ text: prompt }] }; const stream = runner.runAsync({ userId, sessionId, newMessage: content }); const responses = await Array.fromAsync(stream); const accumulatedResponse = responses .flatMap((e) => e.content?.parts?.map((p) => p.text) ?? []) .join(''); console.log(`\nMODEL RESPONSE: ${accumulatedResponse}\n`); } main(); 5. Run your agent, and observe the results: node hotelAgent.js Info For more information, visit the [JS SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-js) . Last modified December 4, 2025: [docs(toolbox-adk): Add quickstart for ADK JS SDK (#1862) (1e67810740d)](https://github.com/googleapis/genai-toolbox/commit/1e67810740d6e4d1d04a3e6122ba405afcd88477) --- # Python Quickstart (Local) | MCP Toolbox for Databases Python Quickstart (Local) ========================= How to get started running MCP Toolbox locally with [Python](https://github.com/googleapis/mcp-toolbox-sdk-python) , PostgreSQL, and [Agent Development Kit](https://google.github.io/adk-docs/) , [LangGraph](https://www.langchain.com/langgraph) , [LlamaIndex](https://www.llamaindex.ai/) or [GoogleGenAI](https://pypi.org/project/google-genai/) . [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/getting-started/colab_quickstart.ipynb) Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Python 3.10+](https://wiki.python.org/moin/BeginnersGuide/Download) (including [pip](https://pip.pypa.io/en/stable/installation/) and your preferred virtual environment tool for managing dependencies e.g. [venv](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) ). 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. Tip If you prefer to experiment within a Google Colab environment, you can connect to a [local runtime](https://research.google.com/colaboratory/local-runtimes.html) . 1. In a new terminal, install the SDK package. * ADK * Langchain * LlamaIndex * Core pip install google-adk[toolbox] pip install toolbox-langchain pip install toolbox-llamaindex pip install toolbox-core 2. Install other required dependencies: * ADK * Langchain * LlamaIndex * Core # No other dependencies required for ADK # TODO(developer): replace with correct package if needed pip install langgraph langchain-google-vertexai # pip install langchain-google-genai # pip install langchain-anthropic # TODO(developer): replace with correct package if needed pip install llama-index-llms-google-genai # pip install llama-index-llms-anthropic pip install google-genai 3. Create the agent: * ADK * LangChain * LlamaIndex * Core 1. Create a new agent project. This will create a new directory named `my_agent` with a file `agent.py`. adk create my_agent 2. Update `my_agent/agent.py` with the following content to connect to MCP Toolbox: import asyncio from google.adk import Agent from google.adk.apps import App from google.adk.runners import InMemoryRunner from google.adk.tools.toolbox_toolset import ToolboxToolset from google.genai.types import Content, Part prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ # TODO(developer): update the TOOLBOX_URL to your toolbox endpoint toolset = ToolboxToolset( server_url="http://127.0.0.1:5000", ) root_agent = Agent( name='hotel_assistant', model='gemini-2.5-flash', instruction=prompt, tools=[toolset], ) app = App(root_agent=root_agent, name="my_agent") 3. Create a `.env` file with your Google API key: echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env Create a new file named `agent.py` and copy the following code: import asyncio from langgraph.prebuilt import create_react_agent # TODO(developer): replace this with another import if needed from langchain_google_vertexai import ChatVertexAI # from langchain_google_genai import ChatGoogleGenerativeAI # from langchain_anthropic import ChatAnthropic from langgraph.checkpoint.memory import MemorySaver from toolbox_langchain import ToolboxClient prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed model = ChatVertexAI(model_name="gemini-2.0-flash-001") # model = ChatGoogleGenerativeAI(model="gemini-2.0-flash-001") # model = ChatAnthropic(model="claude-3-5-sonnet-20240620") # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = create_react_agent(model, tools, checkpointer=MemorySaver()) config = {"configurable": {"thread_id": "thread-1"}} for query in queries: inputs = {"messages": [("user", prompt + query)]} response = agent.invoke(inputs, stream_mode="values", config=config) print(response["messages"][-1].content) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from llama_index.core.agent.workflow import AgentWorkflow from llama_index.core.workflow import Context # TODO(developer): replace this with another import if needed from llama_index.llms.google_genai import GoogleGenAI # from llama_index.llms.anthropic import Anthropic from toolbox_llamaindex import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): # TODO(developer): replace this with another model if needed llm = GoogleGenAI( model="gemini-2.0-flash-001", vertexai_config={"project": project, "location": "us-central1"}, ) # llm = GoogleGenAI( # api_key=os.getenv("GOOGLE_API_KEY"), # model="gemini-2.0-flash-001", # ) # llm = Anthropic( # model="claude-3-7-sonnet-latest", # api_key=os.getenv("ANTHROPIC_API_KEY") # ) # Load the tools from the Toolbox server async with ToolboxClient("http://127.0.0.1:5000") as client: tools = await client.aload_toolset() agent = AgentWorkflow.from_tools_or_functions( tools, llm=llm, system_prompt=prompt, ) ctx = Context(agent) for query in queries: response = await agent.run(user_msg=query, ctx=ctx) print(f"---- {query} ----") print(str(response)) asyncio.run(main()) Create a new file named `agent.py` and copy the following code: import asyncio import os from google import genai from google.genai.types import ( Content, FunctionDeclaration, GenerateContentConfig, Part, Tool, ) from toolbox_core import ToolboxClient project = os.environ.get("GCP_PROJECT") or "project-id" prompt = """ You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention it's name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. """ queries = [\ "Find hotels in Basel with Basel in its name.",\ "Please book the hotel Hilton Basel for me.",\ "This is too expensive. Please cancel it.",\ "Please book Hyatt Regency for me",\ "My check in dates for my booking would be from April 10, 2024 to April 19, 2024.",\ ] async def main(): async with ToolboxClient("http://127.0.0.1:5000") as toolbox_client: # The toolbox_tools list contains Python callables (functions/methods) designed for LLM tool-use # integration. While this example uses Google's genai client, these callables can be adapted for # various function-calling or agent frameworks. For easier integration with supported frameworks # (https://github.com/googleapis/mcp-toolbox-python-sdk/tree/main/packages), use the # provided wrapper packages, which handle framework-specific boilerplate. toolbox_tools = await toolbox_client.load_toolset("my-toolset") genai_client = genai.Client( vertexai=True, project=project, location="us-central1" ) genai_tools = [\ Tool(\ function_declarations=[\ FunctionDeclaration.from_callable_with_api_option(callable=tool)\ ]\ )\ for tool in toolbox_tools\ ] history = [] for query in queries: user_prompt_content = Content( role="user", parts=[Part.from_text(text=query)], ) history.append(user_prompt_content) response = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( system_instruction=prompt, tools=genai_tools, ), ) history.append(response.candidates[0].content) function_response_parts = [] if response.function_calls: for function_call in response.function_calls: fn_name = function_call.name # The tools are sorted alphabetically if fn_name == "search-hotels-by-name": function_result = await toolbox_tools[3](**function_call.args) elif fn_name == "search-hotels-by-location": function_result = await toolbox_tools[2](**function_call.args) elif fn_name == "book-hotel": function_result = await toolbox_tools[0](**function_call.args) elif fn_name == "update-hotel": function_result = await toolbox_tools[4](**function_call.args) elif fn_name == "cancel-hotel": function_result = await toolbox_tools[1](**function_call.args) else: raise ValueError(f"Function name {fn_name} not present.") function_response = {"result": function_result} function_response_part = Part.from_function_response( name=function_call.name, response=function_response, ) function_response_parts.append(function_response_part) if function_response_parts: tool_response_content = Content(role="tool", parts=function_response_parts) history.append(tool_response_content) response2 = genai_client.models.generate_content( model="gemini-2.0-flash-001", contents=history, config=GenerateContentConfig( tools=genai_tools, ), ) final_model_response_content = response2.candidates[0].content history.append(final_model_response_content) print(response2.text) else: print(response.text) asyncio.run(main()) * ADK * Langchain * LlamaIndex * Core To learn more about Agent Development Kit, check out the [ADK Documentation](https://google.github.io/adk-docs/get-started/python/) . To learn more about Agents in LangChain, check out the [LangGraph Agent Documentation](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) . To learn more about Agents in LlamaIndex, check out the [LlamaIndex AgentWorkflow Documentation](https://docs.llamaindex.ai/en/stable/examples/agent/agent_workflow_basic/) . To learn more about tool calling with Google GenAI, check out the [Google GenAI Documentation](https://github.com/googleapis/python-genai?tab=readme-ov-file#manually-declare-and-invoke-a-function-for-function-calling) . 4. Run your agent, and observe the results: * ADK * Langchain * LlamaIndex * Core Run your agent locally for testing: adk run my_agent Alternatively, serve it via a web interface: adk web --port 8000 For more information, refer to the ADK documentation on [Running Agents](https://google.github.io/adk-docs/get-started/python/#run-your-agent) and [Deploying to Cloud](https://google.github.io/adk-docs/deploy/) . python agent.py python agent.py python agent.py Info For more information, visit the [Python SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-python) . Last modified February 25, 2026: [doc: Fix ADK quickstart rendering with shortcodes (#2541) (182d63c7a08)](https://github.com/googleapis/genai-toolbox/commit/182d63c7a080de7f673ad4364ddfde863405c6cb) --- # JS Quickstart (Local) | MCP Toolbox for Databases JS Quickstart (Local) ===================== How to get started running Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Node.js (v18 or higher)](https://nodejs.org/) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. 1. (Optional) Initialize a Node.js project: npm init -y 2. In a new terminal, install the SDK package. * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/adk 3. Install other required dependencies * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install langchain @langchain/google-genai npm install genkit @genkit-ai/googleai npm install llamaindex @llamaindex/google @llamaindex/workflow npm install @google/genai npm install @google/adk 4. Create a new file named `hotelAgent.js` and copy the following code to create an agent: * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK import { ChatGoogleGenerativeAI } from "@langchain/google-genai"; import { ToolboxClient } from "@toolbox-sdk/core"; import { tool } from "@langchain/core/tools"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { MemorySaver } from "@langchain/langgraph"; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const model = new ChatGoogleGenerativeAI({ model: "gemini-2.0-flash", }); const client = new ToolboxClient("http://127.0.0.1:5000"); const toolboxTools = await client.loadToolset("my-toolset"); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(toolboxTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); const tools = toolboxTools.map(getTool); const agent = createReactAgent({ llm: model, tools: tools, checkpointer: new MemorySaver(), systemPrompt: prompt, }); const langGraphConfig = { configurable: { thread_id: "test-thread", }, }; for (const query of queries) { const agentOutput = await agent.invoke( { messages: [\ {\ role: "user",\ content: query,\ },\ ], verbose: true, }, langGraphConfig ); const response = agentOutput.messages[agentOutput.messages.length - 1].content; console.log(response); } } main(); import { ToolboxClient } from "@toolbox-sdk/core"; import { genkit } from "genkit"; import { googleAI } from '@genkit-ai/googleai'; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const toolboxClient = new ToolboxClient("http://127.0.0.1:5000"); const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const toolMap = Object.fromEntries( toolboxTools.map((tool) => { const definedTool = ai.defineTool( { name: tool.getName(), description: tool.getDescription(), inputSchema: tool.getParamSchema(), }, tool ); return [tool.getName(), definedTool]; }) ); const tools = Object.values(toolMap); let conversationHistory = [{ role: "system", content: [{ text: systemPrompt }] }]; for (const query of queries) { conversationHistory.push({ role: "user", content: [{ text: query }] }); let response = await ai.generate({ messages: conversationHistory, tools: tools, }); conversationHistory.push(response.message); const toolRequests = response.toolRequests; if (toolRequests?.length > 0) { // Execute tools concurrently and collect their responses. const toolResponses = await Promise.all( toolRequests.map(async (call) => { try { const toolOutput = await toolMap[call.name].invoke(call.input); return { role: "tool", content: [{ toolResponse: { name: call.name, output: toolOutput } }] }; } catch (e) { console.error(`Error executing tool ${call.name}:`, e); return { role: "tool", content: [{ toolResponse: { name: call.name, output: { error: e.message } } }] }; } }) ); conversationHistory.push(...toolResponses); // Call the AI again with the tool results. response = await ai.generate({ messages: conversationHistory, tools }); conversationHistory.push(response.message); } console.log(response.text); } } main(); import { gemini, GEMINI_MODEL } from "@llamaindex/google"; import { agent } from "@llamaindex/workflow"; import { createMemory, staticBlock, tool } from "llamaindex"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches — this is very important for operations. For any bookings or cancellations, please provide the appropriate confirmation. Update check-in or check-out dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { // Connect to MCP Toolbox const client = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await client.loadToolset("my-toolset"); const tools = toolboxTools.map((toolboxTool) => { return tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool, }); }); // Initialize LLM const llm = gemini({ model: GEMINI_MODEL.GEMINI_2_0_FLASH, apiKey: GOOGLE_API_KEY, }); const memory = createMemory({ memoryBlocks: [\ staticBlock({\ content: prompt,\ }),\ ], }); // Create the Agent const myAgent = agent({ tools: tools, llm, memory, systemPrompt: prompt, }); for (const query of queries) { const result = await myAgent.run(query); const output = result.data.result; console.log(`\nUser: ${query}`); if (typeof output === "string") { console.log(output.trim()); } else if (typeof output === "object" && "text" in output) { console.log(output.text.trim()); } else { console.log(JSON.stringify(output)); } } //You may observe some extra logs during execution due to the run method provided by Llama. console.log("Agent run finished."); } main(); import { GoogleGenAI } from "@google/genai"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, you MUST use the available tools to find information. Mention its name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; function mapZodTypeToOpenAPIType(zodTypeName) { const typeMap = { 'ZodString': 'string', 'ZodNumber': 'number', 'ZodBoolean': 'boolean', 'ZodArray': 'array', 'ZodObject': 'object', }; return typeMap[zodTypeName] || 'string'; } export async function main() { const toolboxClient = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const geminiTools = [{\ functionDeclarations: toolboxTools.map(tool => {\ \ const schema = tool.getParamSchema();\ const properties = {};\ const required = [];\ \ \ for (const [key, param] of Object.entries(schema.shape)) {\ properties[key] = {\ type: mapZodTypeToOpenAPIType(param.constructor.name),\ description: param.description || '',\ };\ required.push(key)\ }\ \ return {\ name: tool.getName(),\ description: tool.getDescription(),\ parameters: { type: 'object', properties, required },\ };\ })\ }]; const genAI = new GoogleGenAI({ apiKey: GOOGLE_API_KEY }); const chat = genAI.chats.create({ model: "gemini-2.5-flash", config: { systemInstruction: prompt, tools: geminiTools, } }); for (const query of queries) { let currentResult = await chat.sendMessage({ message: query }); let finalResponseGiven = false while (!finalResponseGiven) { const response = currentResult; const functionCalls = response.functionCalls || []; if (functionCalls.length === 0) { console.log(response.text) finalResponseGiven = true; } else { const toolResponses = []; for (const call of functionCalls) { const toolName = call.name const toolToExecute = toolboxTools.find(t => t.getName() === toolName); if (toolToExecute) { try { const functionResult = await toolToExecute(call.args); toolResponses.push({ functionResponse: { name: call.name, response: { result: functionResult } } }); } catch (e) { console.error(`Error executing tool '${toolName}':`, e); toolResponses.push({ functionResponse: { name: call.name, response: { error: e.message } } }); } } } currentResult = await chat.sendMessage({ message: toolResponses }); } } } } main(); import { InMemoryRunner, LlmAgent, LogLevel } from '@google/adk'; import { ToolboxClient } from '@toolbox-sdk/adk'; const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; process.env.GOOGLE_GENAI_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key export async function main() { const userId = 'test_user'; const client = new ToolboxClient('http://127.0.0.1:5000'); const tools = await client.loadToolset("my-toolset"); const rootAgent = new LlmAgent({ name: 'hotel_agent', model: 'gemini-2.5-flash', description: 'Agent for hotel bookings and administration.', instruction: prompt, tools: tools, }); const appName = rootAgent.name; const runner = new InMemoryRunner({ agent: rootAgent, appName, logLevel: LogLevel.ERROR, }); const session = await runner.sessionService.createSession({ appName, userId }); for (const query of queries) { await runPrompt(runner, userId, session.id, query); } } async function runPrompt(runner, userId, sessionId, prompt) { const content = { role: 'user', parts: [{ text: prompt }] }; const stream = runner.runAsync({ userId, sessionId, newMessage: content }); const responses = await Array.fromAsync(stream); const accumulatedResponse = responses .flatMap((e) => e.content?.parts?.map((p) => p.text) ?? []) .join(''); console.log(`\nMODEL RESPONSE: ${accumulatedResponse}\n`); } main(); 5. Run your agent, and observe the results: node hotelAgent.js Info For more information, visit the [JS SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-js) . Last modified December 4, 2025: [docs(toolbox-adk): Add quickstart for ADK JS SDK (#1862) (1e67810740d)](https://github.com/googleapis/genai-toolbox/commit/1e67810740d6e4d1d04a3e6122ba405afcd88477) --- # Go Quickstart (Local) | MCP Toolbox for Databases Go Quickstart (Local) ===================== How to get started running Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Go (v1.24.2 or higher)](https://go.dev/doc/install) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. 1. Initialize a go module: go mod init main 2. In a new terminal, install the [SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go) . go get github.com/googleapis/mcp-toolbox-sdk-go 3. Create a new file named `hotelagent.go` and copy the following code to create an agent: * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" "github.com/tmc/langchaingo/llms/googleai" ) // ConvertToLangchainTool converts a generic core.ToolboxTool into a LangChainGo llms.Tool. func ConvertToLangchainTool(toolboxTool *core.ToolboxTool) llms.Tool { // Fetch the tool's input schema inputschema, err := toolboxTool.InputSchema() if err != nil { return llms.Tool{} } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Convert into LangChain's llms.Tool return llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the Google AI client (LLM). llm, err := googleai.New(ctx, googleai.WithAPIKey(genaiKey), googleai.WithDefaultModel("gemini-2.0-flash")) if err != nil { log.Fatalf("Failed to create Google AI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } toolsMap := make(map[string]*core.ToolboxTool, len(tools)) langchainTools := make([]llms.Tool, len(tools)) // Convert the loaded ToolboxTools into the format LangChainGo requires. for i, tool := range tools { langchainTools[i] = ConvertToLangchainTool(tool) toolsMap[tool.Name()] = tool } // Start the conversation history. messageHistory := []llms.MessageContent{ llms.TextParts(llms.ChatMessageTypeSystem, systemPrompt), } for _, query := range queries { messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeHuman, query)) // Make the first call to the LLM, making it aware of the tool. resp, err := llm.GenerateContent(ctx, messageHistory, llms.WithTools(langchainTools)) if err != nil { log.Fatalf("LLM call failed: %v", err) } respChoice := resp.Choices[0] assistantResponse := llms.TextParts(llms.ChatMessageTypeAI, respChoice.Content) for _, tc := range respChoice.ToolCalls { assistantResponse.Parts = append(assistantResponse.Parts, tc) } messageHistory = append(messageHistory, assistantResponse) // Process each tool call requested by the model. for _, tc := range respChoice.ToolCalls { toolName := tc.FunctionCall.Name tool := toolsMap[toolName] var args map[string]any if err := json.Unmarshal([]byte(tc.FunctionCall.Arguments), &args); err != nil { log.Fatalf("Failed to unmarshal arguments for tool '%s': %v", toolName, err) } toolResult, err := tool.Invoke(ctx, args) if err != nil { log.Fatalf("Failed to execute tool '%s': %v", toolName, err) } if toolResult == "" || toolResult == nil { toolResult = "Operation completed successfully with no specific return value." } // Create the tool call response message and add it to the history. toolResponse := llms.MessageContent{ Role: llms.ChatMessageTypeTool, Parts: []llms.ContentPart{ llms.ToolCallResponse{ Name: toolName, Content: fmt.Sprintf("%v", toolResult), }, }, } messageHistory = append(messageHistory, toolResponse) } finalResp, err := llm.GenerateContent(ctx, messageHistory) if err != nil { log.Fatalf("Final LLM call failed after tool execution: %v", err) } // Add the final textual response from the LLM to the history messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeAI, finalResp.Choices[0].Content)) fmt.Println(finalResp.Choices[0].Content) } } package main import ( "context" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/firebase/genkit/go/plugins/googlegenai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { ctx := context.Background() // Create Toolbox Client toolboxClient, err := core.NewToolboxClient("http://127.0.0.1:5000") if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } // Initialize Genkit g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}), genkit.WithDefaultModel("googleai/gemini-2.0-flash"), ) if err != nil { log.Fatalf("Failed to init genkit: %v\n", err) } // Create a conversation history conversationHistory := []*ai.Message{ ai.NewSystemTextMessage(systemPrompt), } // Convert your tool to a Genkit tool. genkitTools := make([]ai.Tool, len(tools)) for i, tool := range tools { newTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } genkitTools[i] = newTool } toolRefs := make([]ai.ToolRef, len(genkitTools)) for i, tool := range genkitTools { toolRefs[i] = tool } for _, query := range queries { conversationHistory = append(conversationHistory, ai.NewUserTextMessage(query)) response, err := genkit.Generate(ctx, g, ai.WithMessages(conversationHistory...), ai.WithTools(toolRefs...), ai.WithReturnToolRequests(true), ) if err != nil { log.Fatalf("%v\n", err) } conversationHistory = append(conversationHistory, response.Message) parts := []*ai.Part{} for _, req := range response.ToolRequests() { tool := genkit.LookupTool(g, req.Name) if tool == nil { log.Fatalf("tool %q not found", req.Name) } output, err := tool.RunRaw(ctx, req.Input) if err != nil { log.Fatalf("tool %q execution failed: %v", tool.Name(), err) } parts = append(parts, ai.NewToolResponsePart(&ai.ToolResponse{ Name: req.Name, Ref: req.Ref, Output: output, })) } if len(parts) > 0 { resp, err := genkit.Generate(ctx, g, ai.WithMessages(append(response.History(), ai.NewMessage(ai.RoleTool, nil, parts...))...), ai.WithTools(toolRefs...), ) if err != nil { log.Fatal(err) } fmt.Println("\n", resp.Text()) conversationHistory = append(conversationHistory, resp.Message) } else { fmt.Println("\n", response.Text()) } } } package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) // ConvertToGenaiTool translates a ToolboxTool into the genai.FunctionDeclaration format. func ConvertToGenaiTool(toolboxTool *core.ToolboxTool) *genai.Tool { inputschema, err := toolboxTool.InputSchema() if err != nil { return &genai.Tool{} } var paramsSchema *genai.Schema _ = json.Unmarshal(inputschema, ¶msSchema) // First, create the function declaration. funcDeclaration := &genai.FunctionDeclaration{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, } // Then, wrap the function declaration in a genai.Tool struct. return &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } func printResponse(resp *genai.GenerateContentResponse) { for _, cand := range resp.Candidates { if cand.Content != nil { for _, part := range cand.Content.Parts { fmt.Println(part.Text) } } } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() apiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" // Initialize the Google GenAI client using the explicit ClientConfig. client, err := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: apiKey, }) if err != nil { log.Fatalf("Failed to create Google GenAI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } genAITools := make([]*genai.Tool, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { genAITools[i] = ConvertToGenaiTool(tool) toolsMap[tool.Name()] = tool } // Set up the generative model with the available tool. modelName := "gemini-2.0-flash" // Create the initial content prompt for the model. messageHistory := []*genai.Content{ genai.NewContentFromText(systemPrompt, genai.RoleUser), } config := &genai.GenerateContentConfig{ Tools: genAITools, ToolConfig: &genai.ToolConfig{ FunctionCallingConfig: &genai.FunctionCallingConfig{ Mode: genai.FunctionCallingConfigModeAny, }, }, } for _, query := range queries { messageHistory = append(messageHistory, genai.NewContentFromText(query, genai.RoleUser)) genContentResp, err := client.Models.GenerateContent(ctx, modelName, messageHistory, config) if err != nil { log.Fatalf("LLM call failed for query '%s': %v", query, err) } if len(genContentResp.Candidates) > 0 && genContentResp.Candidates[0].Content != nil { messageHistory = append(messageHistory, genContentResp.Candidates[0].Content) } functionCalls := genContentResp.FunctionCalls() toolResponseParts := []*genai.Part{} for _, fc := range functionCalls { toolToInvoke, found := toolsMap[fc.Name] if !found { log.Fatalf("Tool '%s' not found in loaded tools map. Check toolset configuration.", fc.Name) } toolResult, invokeErr := toolToInvoke.Invoke(ctx, fc.Args) if invokeErr != nil { log.Fatalf("Failed to execute tool '%s': %v", fc.Name, invokeErr) } // Enhanced Tool Result Handling (retained to prevent nil issues) toolResultString := "" if toolResult != nil { jsonBytes, marshalErr := json.Marshal(toolResult) if marshalErr == nil { toolResultString = string(jsonBytes) } else { toolResultString = fmt.Sprintf("%v", toolResult) } } responseMap := map[string]any{"result": toolResultString} toolResponseParts = append(toolResponseParts, genai.NewPartFromFunctionResponse(fc.Name, responseMap)) } // Add all accumulated tool responses for this turn to the message history. toolResponseContent := genai.NewContentFromParts(toolResponseParts, "function") messageHistory = append(messageHistory, toolResponseContent) finalResponse, err := client.Models.GenerateContent(ctx, modelName, messageHistory, &genai.GenerateContentConfig{}) if err != nil { log.Fatalf("Error calling GenerateContent (with function result): %v", err) } printResponse(finalResponse) // Add the final textual response from the LLM to the history if len(finalResponse.Candidates) > 0 && finalResponse.Candidates[0].Content != nil { messageHistory = append(messageHistory, finalResponse.Candidates[0].Content) } } } package main import ( "context" "encoding/json" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go/v3" ) // ConvertToOpenAITool converts a ToolboxTool into the go-openai library's Tool format. func ConvertToOpenAITool(toolboxTool *core.ToolboxTool) openai.ChatCompletionToolUnionParam { // Get the input schema jsonSchemaBytes, err := toolboxTool.InputSchema() if err != nil { return openai.ChatCompletionToolUnionParam{} } // Unmarshal the JSON bytes into FunctionParameters var paramsSchema openai.FunctionParameters if err := json.Unmarshal(jsonSchemaBytes, ¶msSchema); err != nil { return openai.ChatCompletionToolUnionParam{} } // Create and return the final tool parameter struct. return openai.ChatCompletionToolUnionParam{ OfFunction: &openai.ChatCompletionFunctionToolParam{ Function: openai.FunctionDefinitionParam{ Name: toolboxTool.Name(), Description: openai.String(toolboxTool.Description()), Parameters: paramsSchema, }, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() toolboxURL := "http://localhost:5000" openAIClient := openai.NewClient() // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tool : %v\nMake sure your Toolbox server is running and the tool is configured.", err) } openAITools := make([]openai.ChatCompletionToolUnionParam, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { // Convert the Toolbox tool into the openAI FunctionDeclaration format. openAITools[i] = ConvertToOpenAITool(tool) // Add tool to a map for lookup later toolsMap[tool.Name()] = tool } params := openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{ openai.SystemMessage(systemPrompt), }, Tools: openAITools, Seed: openai.Int(0), Model: openai.ChatModelGPT4o, } for _, query := range queries { params.Messages = append(params.Messages, openai.UserMessage(query)) // Make initial chat completion request completion, err := openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } toolCalls := completion.Choices[0].Message.ToolCalls // Return early if there are no tool calls if len(toolCalls) == 0 { log.Println("No function call") } // If there was a function call, continue the conversation params.Messages = append(params.Messages, completion.Choices[0].Message.ToParam()) for _, toolCall := range toolCalls { toolName := toolCall.Function.Name toolToInvoke := toolsMap[toolName] var args map[string]any err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args) if err != nil { panic(err) } result, err := toolToInvoke.Invoke(ctx, args) if err != nil { log.Fatal("Could not invoke tool", err) } params.Messages = append(params.Messages, openai.ToolMessage(result.(string), toolCall.ID)) } completion, err = openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } params.Messages = append(params.Messages, openai.AssistantMessage(query)) fmt.Println("\n", completion.Choices[0].Message.Content) } } package main import ( "context" "fmt" "log" "os" "strings" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/model/gemini" "google.golang.org/adk/runner" "google.golang.org/adk/session" "google.golang.org/adk/tool" "google.golang.org/genai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queriesAdk = []string{ "Find hotels in Basel. ", "Find hotels with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GEMINI_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the MCP Toolbox client. toolboxClient, err := tbadk.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create MCP Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. toolsetName := "my-toolset" mcpTools, err := toolboxClient.LoadToolset(toolsetName, ctx) if err != nil { log.Fatalf("Failed to load MCP toolset '%s': %v\nMake sure your Toolbox server is running.", toolsetName, err) } // Set up the Gemini Model model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{ APIKey: genaiKey, }) if err != nil { log.Fatalf("Failed to create model: %v", err) } // Type Cast the ToolboxTools tools := make([]tool.Tool, len(mcpTools)) for i := range mcpTools { tools[i] = &mcpTools[i] } // Create an llm agent llmagent, err := llmagent.New(llmagent.Config{ Name: "hotel_assistant", Model: model, Description: "Agent to answer questions about hotels.", Instruction: systemPrompt, Tools: tools, }) if err != nil { log.Fatalf("Failed to create agent: %v", err) } appName := "hotel_assistant" userID := "user-123" // Create a session service sessionService := session.InMemoryService() resp, err := sessionService.Create(ctx, &session.CreateRequest{ AppName: appName, UserID: userID, }) if err != nil { log.Fatalf("Failed to create the session service: %v", err) } session := resp.Session // Configure the runner r, err := runner.New(runner.Config{ AppName: appName, Agent: llmagent, SessionService: sessionService, }) if err != nil { log.Fatalf("Failed to create runner: %v", err) } // Loop through queries to the llm agent for i, query := range queriesAdk { fmt.Printf("\n=== Query %d: %s ===\n", i+1, query) userMsg := genai.NewContentFromText(query, genai.RoleUser) streamingMode := agent.StreamingModeSSE for event, err := range r.Run(ctx, userID, session.ID(), userMsg, agent.RunConfig{ StreamingMode: streamingMode, }) { if err != nil { fmt.Printf("\nAGENT_ERROR: %v\n", err) } else { if event.LLMResponse.Content != nil { for _, p := range event.LLMResponse.Content.Parts { // if its running in streaming mode, don't print the non partial llmResponses if streamingMode != agent.StreamingModeSSE || event.LLMResponse.Partial { fmt.Print(p.Text) } } } } } fmt.Println("\n" + strings.Repeat("-", 80) + "\n") } } 4. Ensure all dependencies are installed: go mod tidy 5. Run your agent, and observe the results: go run hotelagent.go Info For more information, visit the [Go SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-go) . Last modified November 6, 2025: [docs(tbadk): Add documentation for tbadk (#1846) (016c4c02d76)](https://github.com/googleapis/genai-toolbox/commit/016c4c02d7633c629b5025d770ac0443264d5058) --- # Go Quickstart (Local) | MCP Toolbox for Databases Go Quickstart (Local) ===================== How to get started running Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Go (v1.24.2 or higher)](https://go.dev/doc/install) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. 1. Initialize a go module: go mod init main 2. In a new terminal, install the [SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go) . go get github.com/googleapis/mcp-toolbox-sdk-go 3. Create a new file named `hotelagent.go` and copy the following code to create an agent: * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" "github.com/tmc/langchaingo/llms/googleai" ) // ConvertToLangchainTool converts a generic core.ToolboxTool into a LangChainGo llms.Tool. func ConvertToLangchainTool(toolboxTool *core.ToolboxTool) llms.Tool { // Fetch the tool's input schema inputschema, err := toolboxTool.InputSchema() if err != nil { return llms.Tool{} } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Convert into LangChain's llms.Tool return llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the Google AI client (LLM). llm, err := googleai.New(ctx, googleai.WithAPIKey(genaiKey), googleai.WithDefaultModel("gemini-2.0-flash")) if err != nil { log.Fatalf("Failed to create Google AI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } toolsMap := make(map[string]*core.ToolboxTool, len(tools)) langchainTools := make([]llms.Tool, len(tools)) // Convert the loaded ToolboxTools into the format LangChainGo requires. for i, tool := range tools { langchainTools[i] = ConvertToLangchainTool(tool) toolsMap[tool.Name()] = tool } // Start the conversation history. messageHistory := []llms.MessageContent{ llms.TextParts(llms.ChatMessageTypeSystem, systemPrompt), } for _, query := range queries { messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeHuman, query)) // Make the first call to the LLM, making it aware of the tool. resp, err := llm.GenerateContent(ctx, messageHistory, llms.WithTools(langchainTools)) if err != nil { log.Fatalf("LLM call failed: %v", err) } respChoice := resp.Choices[0] assistantResponse := llms.TextParts(llms.ChatMessageTypeAI, respChoice.Content) for _, tc := range respChoice.ToolCalls { assistantResponse.Parts = append(assistantResponse.Parts, tc) } messageHistory = append(messageHistory, assistantResponse) // Process each tool call requested by the model. for _, tc := range respChoice.ToolCalls { toolName := tc.FunctionCall.Name tool := toolsMap[toolName] var args map[string]any if err := json.Unmarshal([]byte(tc.FunctionCall.Arguments), &args); err != nil { log.Fatalf("Failed to unmarshal arguments for tool '%s': %v", toolName, err) } toolResult, err := tool.Invoke(ctx, args) if err != nil { log.Fatalf("Failed to execute tool '%s': %v", toolName, err) } if toolResult == "" || toolResult == nil { toolResult = "Operation completed successfully with no specific return value." } // Create the tool call response message and add it to the history. toolResponse := llms.MessageContent{ Role: llms.ChatMessageTypeTool, Parts: []llms.ContentPart{ llms.ToolCallResponse{ Name: toolName, Content: fmt.Sprintf("%v", toolResult), }, }, } messageHistory = append(messageHistory, toolResponse) } finalResp, err := llm.GenerateContent(ctx, messageHistory) if err != nil { log.Fatalf("Final LLM call failed after tool execution: %v", err) } // Add the final textual response from the LLM to the history messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeAI, finalResp.Choices[0].Content)) fmt.Println(finalResp.Choices[0].Content) } } package main import ( "context" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/firebase/genkit/go/plugins/googlegenai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { ctx := context.Background() // Create Toolbox Client toolboxClient, err := core.NewToolboxClient("http://127.0.0.1:5000") if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } // Initialize Genkit g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}), genkit.WithDefaultModel("googleai/gemini-2.0-flash"), ) if err != nil { log.Fatalf("Failed to init genkit: %v\n", err) } // Create a conversation history conversationHistory := []*ai.Message{ ai.NewSystemTextMessage(systemPrompt), } // Convert your tool to a Genkit tool. genkitTools := make([]ai.Tool, len(tools)) for i, tool := range tools { newTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } genkitTools[i] = newTool } toolRefs := make([]ai.ToolRef, len(genkitTools)) for i, tool := range genkitTools { toolRefs[i] = tool } for _, query := range queries { conversationHistory = append(conversationHistory, ai.NewUserTextMessage(query)) response, err := genkit.Generate(ctx, g, ai.WithMessages(conversationHistory...), ai.WithTools(toolRefs...), ai.WithReturnToolRequests(true), ) if err != nil { log.Fatalf("%v\n", err) } conversationHistory = append(conversationHistory, response.Message) parts := []*ai.Part{} for _, req := range response.ToolRequests() { tool := genkit.LookupTool(g, req.Name) if tool == nil { log.Fatalf("tool %q not found", req.Name) } output, err := tool.RunRaw(ctx, req.Input) if err != nil { log.Fatalf("tool %q execution failed: %v", tool.Name(), err) } parts = append(parts, ai.NewToolResponsePart(&ai.ToolResponse{ Name: req.Name, Ref: req.Ref, Output: output, })) } if len(parts) > 0 { resp, err := genkit.Generate(ctx, g, ai.WithMessages(append(response.History(), ai.NewMessage(ai.RoleTool, nil, parts...))...), ai.WithTools(toolRefs...), ) if err != nil { log.Fatal(err) } fmt.Println("\n", resp.Text()) conversationHistory = append(conversationHistory, resp.Message) } else { fmt.Println("\n", response.Text()) } } } package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) // ConvertToGenaiTool translates a ToolboxTool into the genai.FunctionDeclaration format. func ConvertToGenaiTool(toolboxTool *core.ToolboxTool) *genai.Tool { inputschema, err := toolboxTool.InputSchema() if err != nil { return &genai.Tool{} } var paramsSchema *genai.Schema _ = json.Unmarshal(inputschema, ¶msSchema) // First, create the function declaration. funcDeclaration := &genai.FunctionDeclaration{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, } // Then, wrap the function declaration in a genai.Tool struct. return &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } func printResponse(resp *genai.GenerateContentResponse) { for _, cand := range resp.Candidates { if cand.Content != nil { for _, part := range cand.Content.Parts { fmt.Println(part.Text) } } } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() apiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" // Initialize the Google GenAI client using the explicit ClientConfig. client, err := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: apiKey, }) if err != nil { log.Fatalf("Failed to create Google GenAI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } genAITools := make([]*genai.Tool, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { genAITools[i] = ConvertToGenaiTool(tool) toolsMap[tool.Name()] = tool } // Set up the generative model with the available tool. modelName := "gemini-2.0-flash" // Create the initial content prompt for the model. messageHistory := []*genai.Content{ genai.NewContentFromText(systemPrompt, genai.RoleUser), } config := &genai.GenerateContentConfig{ Tools: genAITools, ToolConfig: &genai.ToolConfig{ FunctionCallingConfig: &genai.FunctionCallingConfig{ Mode: genai.FunctionCallingConfigModeAny, }, }, } for _, query := range queries { messageHistory = append(messageHistory, genai.NewContentFromText(query, genai.RoleUser)) genContentResp, err := client.Models.GenerateContent(ctx, modelName, messageHistory, config) if err != nil { log.Fatalf("LLM call failed for query '%s': %v", query, err) } if len(genContentResp.Candidates) > 0 && genContentResp.Candidates[0].Content != nil { messageHistory = append(messageHistory, genContentResp.Candidates[0].Content) } functionCalls := genContentResp.FunctionCalls() toolResponseParts := []*genai.Part{} for _, fc := range functionCalls { toolToInvoke, found := toolsMap[fc.Name] if !found { log.Fatalf("Tool '%s' not found in loaded tools map. Check toolset configuration.", fc.Name) } toolResult, invokeErr := toolToInvoke.Invoke(ctx, fc.Args) if invokeErr != nil { log.Fatalf("Failed to execute tool '%s': %v", fc.Name, invokeErr) } // Enhanced Tool Result Handling (retained to prevent nil issues) toolResultString := "" if toolResult != nil { jsonBytes, marshalErr := json.Marshal(toolResult) if marshalErr == nil { toolResultString = string(jsonBytes) } else { toolResultString = fmt.Sprintf("%v", toolResult) } } responseMap := map[string]any{"result": toolResultString} toolResponseParts = append(toolResponseParts, genai.NewPartFromFunctionResponse(fc.Name, responseMap)) } // Add all accumulated tool responses for this turn to the message history. toolResponseContent := genai.NewContentFromParts(toolResponseParts, "function") messageHistory = append(messageHistory, toolResponseContent) finalResponse, err := client.Models.GenerateContent(ctx, modelName, messageHistory, &genai.GenerateContentConfig{}) if err != nil { log.Fatalf("Error calling GenerateContent (with function result): %v", err) } printResponse(finalResponse) // Add the final textual response from the LLM to the history if len(finalResponse.Candidates) > 0 && finalResponse.Candidates[0].Content != nil { messageHistory = append(messageHistory, finalResponse.Candidates[0].Content) } } } package main import ( "context" "encoding/json" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go/v3" ) // ConvertToOpenAITool converts a ToolboxTool into the go-openai library's Tool format. func ConvertToOpenAITool(toolboxTool *core.ToolboxTool) openai.ChatCompletionToolUnionParam { // Get the input schema jsonSchemaBytes, err := toolboxTool.InputSchema() if err != nil { return openai.ChatCompletionToolUnionParam{} } // Unmarshal the JSON bytes into FunctionParameters var paramsSchema openai.FunctionParameters if err := json.Unmarshal(jsonSchemaBytes, ¶msSchema); err != nil { return openai.ChatCompletionToolUnionParam{} } // Create and return the final tool parameter struct. return openai.ChatCompletionToolUnionParam{ OfFunction: &openai.ChatCompletionFunctionToolParam{ Function: openai.FunctionDefinitionParam{ Name: toolboxTool.Name(), Description: openai.String(toolboxTool.Description()), Parameters: paramsSchema, }, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() toolboxURL := "http://localhost:5000" openAIClient := openai.NewClient() // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tool : %v\nMake sure your Toolbox server is running and the tool is configured.", err) } openAITools := make([]openai.ChatCompletionToolUnionParam, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { // Convert the Toolbox tool into the openAI FunctionDeclaration format. openAITools[i] = ConvertToOpenAITool(tool) // Add tool to a map for lookup later toolsMap[tool.Name()] = tool } params := openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{ openai.SystemMessage(systemPrompt), }, Tools: openAITools, Seed: openai.Int(0), Model: openai.ChatModelGPT4o, } for _, query := range queries { params.Messages = append(params.Messages, openai.UserMessage(query)) // Make initial chat completion request completion, err := openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } toolCalls := completion.Choices[0].Message.ToolCalls // Return early if there are no tool calls if len(toolCalls) == 0 { log.Println("No function call") } // If there was a function call, continue the conversation params.Messages = append(params.Messages, completion.Choices[0].Message.ToParam()) for _, toolCall := range toolCalls { toolName := toolCall.Function.Name toolToInvoke := toolsMap[toolName] var args map[string]any err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args) if err != nil { panic(err) } result, err := toolToInvoke.Invoke(ctx, args) if err != nil { log.Fatal("Could not invoke tool", err) } params.Messages = append(params.Messages, openai.ToolMessage(result.(string), toolCall.ID)) } completion, err = openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } params.Messages = append(params.Messages, openai.AssistantMessage(query)) fmt.Println("\n", completion.Choices[0].Message.Content) } } package main import ( "context" "fmt" "log" "os" "strings" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/model/gemini" "google.golang.org/adk/runner" "google.golang.org/adk/session" "google.golang.org/adk/tool" "google.golang.org/genai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queriesAdk = []string{ "Find hotels in Basel. ", "Find hotels with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GEMINI_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the MCP Toolbox client. toolboxClient, err := tbadk.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create MCP Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. toolsetName := "my-toolset" mcpTools, err := toolboxClient.LoadToolset(toolsetName, ctx) if err != nil { log.Fatalf("Failed to load MCP toolset '%s': %v\nMake sure your Toolbox server is running.", toolsetName, err) } // Set up the Gemini Model model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{ APIKey: genaiKey, }) if err != nil { log.Fatalf("Failed to create model: %v", err) } // Type Cast the ToolboxTools tools := make([]tool.Tool, len(mcpTools)) for i := range mcpTools { tools[i] = &mcpTools[i] } // Create an llm agent llmagent, err := llmagent.New(llmagent.Config{ Name: "hotel_assistant", Model: model, Description: "Agent to answer questions about hotels.", Instruction: systemPrompt, Tools: tools, }) if err != nil { log.Fatalf("Failed to create agent: %v", err) } appName := "hotel_assistant" userID := "user-123" // Create a session service sessionService := session.InMemoryService() resp, err := sessionService.Create(ctx, &session.CreateRequest{ AppName: appName, UserID: userID, }) if err != nil { log.Fatalf("Failed to create the session service: %v", err) } session := resp.Session // Configure the runner r, err := runner.New(runner.Config{ AppName: appName, Agent: llmagent, SessionService: sessionService, }) if err != nil { log.Fatalf("Failed to create runner: %v", err) } // Loop through queries to the llm agent for i, query := range queriesAdk { fmt.Printf("\n=== Query %d: %s ===\n", i+1, query) userMsg := genai.NewContentFromText(query, genai.RoleUser) streamingMode := agent.StreamingModeSSE for event, err := range r.Run(ctx, userID, session.ID(), userMsg, agent.RunConfig{ StreamingMode: streamingMode, }) { if err != nil { fmt.Printf("\nAGENT_ERROR: %v\n", err) } else { if event.LLMResponse.Content != nil { for _, p := range event.LLMResponse.Content.Parts { // if its running in streaming mode, don't print the non partial llmResponses if streamingMode != agent.StreamingModeSSE || event.LLMResponse.Partial { fmt.Print(p.Text) } } } } } fmt.Println("\n" + strings.Repeat("-", 80) + "\n") } } 4. Ensure all dependencies are installed: go mod tidy 5. Run your agent, and observe the results: go run hotelagent.go Info For more information, visit the [Go SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-go) . Last modified November 6, 2025: [docs(tbadk): Add documentation for tbadk (#1846) (016c4c02d76)](https://github.com/googleapis/genai-toolbox/commit/016c4c02d7633c629b5025d770ac0443264d5058) --- # Prompts using Gemini CLI | MCP Toolbox for Databases Prompts using Gemini CLI ======================== How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create the required tables using the following commands: CREATE TABLE users ( id SERIAL PRIMARY KEY, username VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE restaurants ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, location VARCHAR(100) ); CREATE TABLE reviews ( id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id), restaurant_id INT REFERENCES restaurants(id), rating INT CHECK (rating >= 1 AND rating <= 5), review_text TEXT, is_published BOOLEAN DEFAULT false, moderation_status VARCHAR(50) DEFAULT 'pending_manual_review', created_at TIMESTAMPTZ DEFAULT NOW() ); 6. Insert dummy data into the tables. INSERT INTO users (id, username, email) VALUES (123, 'jane_d', '[email protected]'), (124, 'john_s', '[email protected]'), (125, 'sam_b', '[email protected]'); INSERT INTO restaurants (id, name, location) VALUES (455, 'Pizza Palace', '123 Main St'), (456, 'The Corner Bistro', '456 Oak Ave'), (457, 'Sushi Spot', '789 Pine Ln'); INSERT INTO reviews (user_id, restaurant_id, rating, review_text, is_published, moderation_status) VALUES (124, 455, 5, 'Best pizza in town! The crust was perfect.', true, 'approved'), (125, 457, 4, 'Great sushi, very fresh. A bit pricey but worth it.', true, 'approved'), (123, 457, 5, 'Absolutely loved the dragon roll. Will be back!', true, 'approved'), (123, 456, 4, 'The atmosphere was lovely and the food was great. My photo upload might have been weird though.', false, 'pending_manual_review'), (125, 456, 1, 'This review contains inappropriate language.', false, 'rejected'); 7. End the database session: \q Step 2: Configure Toolbox ------------------------- Create a file named `tools.yaml`. This file defines the database connection, the SQL tools available, and the prompts the agents will use. sources: my-foodiefind-db: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password tools: find_user_by_email: kind: postgres-sql source: my-foodiefind-db description: Find a user's ID by their email address. parameters: - name: email type: string description: The email address of the user to find. statement: SELECT id FROM users WHERE email = $1; find_restaurant_by_name: kind: postgres-sql source: my-foodiefind-db description: Find a restaurant's ID by its exact name. parameters: - name: name type: string description: The name of the restaurant to find. statement: SELECT id FROM restaurants WHERE name = $1; find_review_by_user_and_restaurant: kind: postgres-sql source: my-foodiefind-db description: Find the full record for a specific review using the user's ID and the restaurant's ID. parameters: - name: user_id type: integer description: The numerical ID of the user. - name: restaurant_id type: integer description: The numerical ID of the restaurant. statement: SELECT * FROM reviews WHERE user_id = $1 AND restaurant_id = $2; prompts: investigate_missing_review: description: "Investigates a user's missing review by finding the user, restaurant, and the review itself, then analyzing its status." arguments: - name: "user_email" description: "The email of the user who wrote the review." - name: "restaurant_name" description: "The name of the restaurant being reviewed." messages: - content: >- **Goal:** Find the review written by the user with email '{{.user_email}}' for the restaurant named '{{.restaurant_name}}' and understand its status. **Workflow:** 1. Use the `find_user_by_email` tool with the email '{{.user_email}}' to get the `user_id`. 2. Use the `find_restaurant_by_name` tool with the name '{{.restaurant_name}}' to get the `restaurant_id`. 3. Use the `find_review_by_user_and_restaurant` tool with the `user_id` and `restaurant_id` you just found. 4. Analyze the results from the final tool call. Examine the `is_published` and `moderation_status` fields and explain the review's status to the user in a clear, human-readable sentence. Step 3: Connect to Gemini CLI ----------------------------- Configure the Gemini CLI to talk to your local Toolbox MCP server. 1. Open or create your Gemini settings file: `~/.gemini/settings.json`. 2. Add the following configuration to the file: { "mcpServers": { "MCPToolbox": { "httpUrl": "http://localhost:5000/mcp" } }, "mcp": { "allowed": ["MCPToolbox"] } } 3. Start Gemini CLI using gemini In case Gemini CLI is already running, use `/mcp refresh` to refresh the MCP server. 4. Use gemini slash commands to run your prompt: /investigate_missing_review --user_email="[email protected]" --restaurant_name="The Corner Bistro" Last modified December 11, 2025: [docs: add prompts quickstart using gemini cli (#2158) (1f31c2c9b27)](https://github.com/googleapis/genai-toolbox/commit/1f31c2c9b2714a516aa2bc30317b736797ecf9a0) --- # Prompts using Gemini CLI | MCP Toolbox for Databases Prompts using Gemini CLI ======================== How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create the required tables using the following commands: CREATE TABLE users ( id SERIAL PRIMARY KEY, username VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE restaurants ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, location VARCHAR(100) ); CREATE TABLE reviews ( id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id), restaurant_id INT REFERENCES restaurants(id), rating INT CHECK (rating >= 1 AND rating <= 5), review_text TEXT, is_published BOOLEAN DEFAULT false, moderation_status VARCHAR(50) DEFAULT 'pending_manual_review', created_at TIMESTAMPTZ DEFAULT NOW() ); 6. Insert dummy data into the tables. INSERT INTO users (id, username, email) VALUES (123, 'jane_d', '[email protected]'), (124, 'john_s', '[email protected]'), (125, 'sam_b', '[email protected]'); INSERT INTO restaurants (id, name, location) VALUES (455, 'Pizza Palace', '123 Main St'), (456, 'The Corner Bistro', '456 Oak Ave'), (457, 'Sushi Spot', '789 Pine Ln'); INSERT INTO reviews (user_id, restaurant_id, rating, review_text, is_published, moderation_status) VALUES (124, 455, 5, 'Best pizza in town! The crust was perfect.', true, 'approved'), (125, 457, 4, 'Great sushi, very fresh. A bit pricey but worth it.', true, 'approved'), (123, 457, 5, 'Absolutely loved the dragon roll. Will be back!', true, 'approved'), (123, 456, 4, 'The atmosphere was lovely and the food was great. My photo upload might have been weird though.', false, 'pending_manual_review'), (125, 456, 1, 'This review contains inappropriate language.', false, 'rejected'); 7. End the database session: \q Step 2: Configure Toolbox ------------------------- Create a file named `tools.yaml`. This file defines the database connection, the SQL tools available, and the prompts the agents will use. sources: my-foodiefind-db: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password tools: find_user_by_email: kind: postgres-sql source: my-foodiefind-db description: Find a user's ID by their email address. parameters: - name: email type: string description: The email address of the user to find. statement: SELECT id FROM users WHERE email = $1; find_restaurant_by_name: kind: postgres-sql source: my-foodiefind-db description: Find a restaurant's ID by its exact name. parameters: - name: name type: string description: The name of the restaurant to find. statement: SELECT id FROM restaurants WHERE name = $1; find_review_by_user_and_restaurant: kind: postgres-sql source: my-foodiefind-db description: Find the full record for a specific review using the user's ID and the restaurant's ID. parameters: - name: user_id type: integer description: The numerical ID of the user. - name: restaurant_id type: integer description: The numerical ID of the restaurant. statement: SELECT * FROM reviews WHERE user_id = $1 AND restaurant_id = $2; prompts: investigate_missing_review: description: "Investigates a user's missing review by finding the user, restaurant, and the review itself, then analyzing its status." arguments: - name: "user_email" description: "The email of the user who wrote the review." - name: "restaurant_name" description: "The name of the restaurant being reviewed." messages: - content: >- **Goal:** Find the review written by the user with email '{{.user_email}}' for the restaurant named '{{.restaurant_name}}' and understand its status. **Workflow:** 1. Use the `find_user_by_email` tool with the email '{{.user_email}}' to get the `user_id`. 2. Use the `find_restaurant_by_name` tool with the name '{{.restaurant_name}}' to get the `restaurant_id`. 3. Use the `find_review_by_user_and_restaurant` tool with the `user_id` and `restaurant_id` you just found. 4. Analyze the results from the final tool call. Examine the `is_published` and `moderation_status` fields and explain the review's status to the user in a clear, human-readable sentence. Step 3: Connect to Gemini CLI ----------------------------- Configure the Gemini CLI to talk to your local Toolbox MCP server. 1. Open or create your Gemini settings file: `~/.gemini/settings.json`. 2. Add the following configuration to the file: { "mcpServers": { "MCPToolbox": { "httpUrl": "http://localhost:5000/mcp" } }, "mcp": { "allowed": ["MCPToolbox"] } } 3. Start Gemini CLI using gemini In case Gemini CLI is already running, use `/mcp refresh` to refresh the MCP server. 4. Use gemini slash commands to run your prompt: /investigate_missing_review --user_email="[email protected]" --restaurant_name="The Corner Bistro" Last modified December 11, 2025: [docs: add prompts quickstart using gemini cli (#2158) (1f31c2c9b27)](https://github.com/googleapis/genai-toolbox/commit/1f31c2c9b2714a516aa2bc30317b736797ecf9a0) --- # Go Quickstart (Local) | MCP Toolbox for Databases Go Quickstart (Local) ===================== How to get started running Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Go (v1.24.2 or higher)](https://go.dev/doc/install) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. 1. Initialize a go module: go mod init main 2. In a new terminal, install the [SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go) . go get github.com/googleapis/mcp-toolbox-sdk-go 3. Create a new file named `hotelagent.go` and copy the following code to create an agent: * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" "github.com/tmc/langchaingo/llms/googleai" ) // ConvertToLangchainTool converts a generic core.ToolboxTool into a LangChainGo llms.Tool. func ConvertToLangchainTool(toolboxTool *core.ToolboxTool) llms.Tool { // Fetch the tool's input schema inputschema, err := toolboxTool.InputSchema() if err != nil { return llms.Tool{} } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Convert into LangChain's llms.Tool return llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the Google AI client (LLM). llm, err := googleai.New(ctx, googleai.WithAPIKey(genaiKey), googleai.WithDefaultModel("gemini-2.0-flash")) if err != nil { log.Fatalf("Failed to create Google AI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } toolsMap := make(map[string]*core.ToolboxTool, len(tools)) langchainTools := make([]llms.Tool, len(tools)) // Convert the loaded ToolboxTools into the format LangChainGo requires. for i, tool := range tools { langchainTools[i] = ConvertToLangchainTool(tool) toolsMap[tool.Name()] = tool } // Start the conversation history. messageHistory := []llms.MessageContent{ llms.TextParts(llms.ChatMessageTypeSystem, systemPrompt), } for _, query := range queries { messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeHuman, query)) // Make the first call to the LLM, making it aware of the tool. resp, err := llm.GenerateContent(ctx, messageHistory, llms.WithTools(langchainTools)) if err != nil { log.Fatalf("LLM call failed: %v", err) } respChoice := resp.Choices[0] assistantResponse := llms.TextParts(llms.ChatMessageTypeAI, respChoice.Content) for _, tc := range respChoice.ToolCalls { assistantResponse.Parts = append(assistantResponse.Parts, tc) } messageHistory = append(messageHistory, assistantResponse) // Process each tool call requested by the model. for _, tc := range respChoice.ToolCalls { toolName := tc.FunctionCall.Name tool := toolsMap[toolName] var args map[string]any if err := json.Unmarshal([]byte(tc.FunctionCall.Arguments), &args); err != nil { log.Fatalf("Failed to unmarshal arguments for tool '%s': %v", toolName, err) } toolResult, err := tool.Invoke(ctx, args) if err != nil { log.Fatalf("Failed to execute tool '%s': %v", toolName, err) } if toolResult == "" || toolResult == nil { toolResult = "Operation completed successfully with no specific return value." } // Create the tool call response message and add it to the history. toolResponse := llms.MessageContent{ Role: llms.ChatMessageTypeTool, Parts: []llms.ContentPart{ llms.ToolCallResponse{ Name: toolName, Content: fmt.Sprintf("%v", toolResult), }, }, } messageHistory = append(messageHistory, toolResponse) } finalResp, err := llm.GenerateContent(ctx, messageHistory) if err != nil { log.Fatalf("Final LLM call failed after tool execution: %v", err) } // Add the final textual response from the LLM to the history messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeAI, finalResp.Choices[0].Content)) fmt.Println(finalResp.Choices[0].Content) } } package main import ( "context" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/firebase/genkit/go/plugins/googlegenai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { ctx := context.Background() // Create Toolbox Client toolboxClient, err := core.NewToolboxClient("http://127.0.0.1:5000") if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } // Initialize Genkit g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}), genkit.WithDefaultModel("googleai/gemini-2.0-flash"), ) if err != nil { log.Fatalf("Failed to init genkit: %v\n", err) } // Create a conversation history conversationHistory := []*ai.Message{ ai.NewSystemTextMessage(systemPrompt), } // Convert your tool to a Genkit tool. genkitTools := make([]ai.Tool, len(tools)) for i, tool := range tools { newTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } genkitTools[i] = newTool } toolRefs := make([]ai.ToolRef, len(genkitTools)) for i, tool := range genkitTools { toolRefs[i] = tool } for _, query := range queries { conversationHistory = append(conversationHistory, ai.NewUserTextMessage(query)) response, err := genkit.Generate(ctx, g, ai.WithMessages(conversationHistory...), ai.WithTools(toolRefs...), ai.WithReturnToolRequests(true), ) if err != nil { log.Fatalf("%v\n", err) } conversationHistory = append(conversationHistory, response.Message) parts := []*ai.Part{} for _, req := range response.ToolRequests() { tool := genkit.LookupTool(g, req.Name) if tool == nil { log.Fatalf("tool %q not found", req.Name) } output, err := tool.RunRaw(ctx, req.Input) if err != nil { log.Fatalf("tool %q execution failed: %v", tool.Name(), err) } parts = append(parts, ai.NewToolResponsePart(&ai.ToolResponse{ Name: req.Name, Ref: req.Ref, Output: output, })) } if len(parts) > 0 { resp, err := genkit.Generate(ctx, g, ai.WithMessages(append(response.History(), ai.NewMessage(ai.RoleTool, nil, parts...))...), ai.WithTools(toolRefs...), ) if err != nil { log.Fatal(err) } fmt.Println("\n", resp.Text()) conversationHistory = append(conversationHistory, resp.Message) } else { fmt.Println("\n", response.Text()) } } } package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) // ConvertToGenaiTool translates a ToolboxTool into the genai.FunctionDeclaration format. func ConvertToGenaiTool(toolboxTool *core.ToolboxTool) *genai.Tool { inputschema, err := toolboxTool.InputSchema() if err != nil { return &genai.Tool{} } var paramsSchema *genai.Schema _ = json.Unmarshal(inputschema, ¶msSchema) // First, create the function declaration. funcDeclaration := &genai.FunctionDeclaration{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, } // Then, wrap the function declaration in a genai.Tool struct. return &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } func printResponse(resp *genai.GenerateContentResponse) { for _, cand := range resp.Candidates { if cand.Content != nil { for _, part := range cand.Content.Parts { fmt.Println(part.Text) } } } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() apiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" // Initialize the Google GenAI client using the explicit ClientConfig. client, err := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: apiKey, }) if err != nil { log.Fatalf("Failed to create Google GenAI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } genAITools := make([]*genai.Tool, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { genAITools[i] = ConvertToGenaiTool(tool) toolsMap[tool.Name()] = tool } // Set up the generative model with the available tool. modelName := "gemini-2.0-flash" // Create the initial content prompt for the model. messageHistory := []*genai.Content{ genai.NewContentFromText(systemPrompt, genai.RoleUser), } config := &genai.GenerateContentConfig{ Tools: genAITools, ToolConfig: &genai.ToolConfig{ FunctionCallingConfig: &genai.FunctionCallingConfig{ Mode: genai.FunctionCallingConfigModeAny, }, }, } for _, query := range queries { messageHistory = append(messageHistory, genai.NewContentFromText(query, genai.RoleUser)) genContentResp, err := client.Models.GenerateContent(ctx, modelName, messageHistory, config) if err != nil { log.Fatalf("LLM call failed for query '%s': %v", query, err) } if len(genContentResp.Candidates) > 0 && genContentResp.Candidates[0].Content != nil { messageHistory = append(messageHistory, genContentResp.Candidates[0].Content) } functionCalls := genContentResp.FunctionCalls() toolResponseParts := []*genai.Part{} for _, fc := range functionCalls { toolToInvoke, found := toolsMap[fc.Name] if !found { log.Fatalf("Tool '%s' not found in loaded tools map. Check toolset configuration.", fc.Name) } toolResult, invokeErr := toolToInvoke.Invoke(ctx, fc.Args) if invokeErr != nil { log.Fatalf("Failed to execute tool '%s': %v", fc.Name, invokeErr) } // Enhanced Tool Result Handling (retained to prevent nil issues) toolResultString := "" if toolResult != nil { jsonBytes, marshalErr := json.Marshal(toolResult) if marshalErr == nil { toolResultString = string(jsonBytes) } else { toolResultString = fmt.Sprintf("%v", toolResult) } } responseMap := map[string]any{"result": toolResultString} toolResponseParts = append(toolResponseParts, genai.NewPartFromFunctionResponse(fc.Name, responseMap)) } // Add all accumulated tool responses for this turn to the message history. toolResponseContent := genai.NewContentFromParts(toolResponseParts, "function") messageHistory = append(messageHistory, toolResponseContent) finalResponse, err := client.Models.GenerateContent(ctx, modelName, messageHistory, &genai.GenerateContentConfig{}) if err != nil { log.Fatalf("Error calling GenerateContent (with function result): %v", err) } printResponse(finalResponse) // Add the final textual response from the LLM to the history if len(finalResponse.Candidates) > 0 && finalResponse.Candidates[0].Content != nil { messageHistory = append(messageHistory, finalResponse.Candidates[0].Content) } } } package main import ( "context" "encoding/json" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go/v3" ) // ConvertToOpenAITool converts a ToolboxTool into the go-openai library's Tool format. func ConvertToOpenAITool(toolboxTool *core.ToolboxTool) openai.ChatCompletionToolUnionParam { // Get the input schema jsonSchemaBytes, err := toolboxTool.InputSchema() if err != nil { return openai.ChatCompletionToolUnionParam{} } // Unmarshal the JSON bytes into FunctionParameters var paramsSchema openai.FunctionParameters if err := json.Unmarshal(jsonSchemaBytes, ¶msSchema); err != nil { return openai.ChatCompletionToolUnionParam{} } // Create and return the final tool parameter struct. return openai.ChatCompletionToolUnionParam{ OfFunction: &openai.ChatCompletionFunctionToolParam{ Function: openai.FunctionDefinitionParam{ Name: toolboxTool.Name(), Description: openai.String(toolboxTool.Description()), Parameters: paramsSchema, }, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() toolboxURL := "http://localhost:5000" openAIClient := openai.NewClient() // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tool : %v\nMake sure your Toolbox server is running and the tool is configured.", err) } openAITools := make([]openai.ChatCompletionToolUnionParam, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { // Convert the Toolbox tool into the openAI FunctionDeclaration format. openAITools[i] = ConvertToOpenAITool(tool) // Add tool to a map for lookup later toolsMap[tool.Name()] = tool } params := openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{ openai.SystemMessage(systemPrompt), }, Tools: openAITools, Seed: openai.Int(0), Model: openai.ChatModelGPT4o, } for _, query := range queries { params.Messages = append(params.Messages, openai.UserMessage(query)) // Make initial chat completion request completion, err := openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } toolCalls := completion.Choices[0].Message.ToolCalls // Return early if there are no tool calls if len(toolCalls) == 0 { log.Println("No function call") } // If there was a function call, continue the conversation params.Messages = append(params.Messages, completion.Choices[0].Message.ToParam()) for _, toolCall := range toolCalls { toolName := toolCall.Function.Name toolToInvoke := toolsMap[toolName] var args map[string]any err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args) if err != nil { panic(err) } result, err := toolToInvoke.Invoke(ctx, args) if err != nil { log.Fatal("Could not invoke tool", err) } params.Messages = append(params.Messages, openai.ToolMessage(result.(string), toolCall.ID)) } completion, err = openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } params.Messages = append(params.Messages, openai.AssistantMessage(query)) fmt.Println("\n", completion.Choices[0].Message.Content) } } package main import ( "context" "fmt" "log" "os" "strings" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/model/gemini" "google.golang.org/adk/runner" "google.golang.org/adk/session" "google.golang.org/adk/tool" "google.golang.org/genai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queriesAdk = []string{ "Find hotels in Basel. ", "Find hotels with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GEMINI_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the MCP Toolbox client. toolboxClient, err := tbadk.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create MCP Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. toolsetName := "my-toolset" mcpTools, err := toolboxClient.LoadToolset(toolsetName, ctx) if err != nil { log.Fatalf("Failed to load MCP toolset '%s': %v\nMake sure your Toolbox server is running.", toolsetName, err) } // Set up the Gemini Model model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{ APIKey: genaiKey, }) if err != nil { log.Fatalf("Failed to create model: %v", err) } // Type Cast the ToolboxTools tools := make([]tool.Tool, len(mcpTools)) for i := range mcpTools { tools[i] = &mcpTools[i] } // Create an llm agent llmagent, err := llmagent.New(llmagent.Config{ Name: "hotel_assistant", Model: model, Description: "Agent to answer questions about hotels.", Instruction: systemPrompt, Tools: tools, }) if err != nil { log.Fatalf("Failed to create agent: %v", err) } appName := "hotel_assistant" userID := "user-123" // Create a session service sessionService := session.InMemoryService() resp, err := sessionService.Create(ctx, &session.CreateRequest{ AppName: appName, UserID: userID, }) if err != nil { log.Fatalf("Failed to create the session service: %v", err) } session := resp.Session // Configure the runner r, err := runner.New(runner.Config{ AppName: appName, Agent: llmagent, SessionService: sessionService, }) if err != nil { log.Fatalf("Failed to create runner: %v", err) } // Loop through queries to the llm agent for i, query := range queriesAdk { fmt.Printf("\n=== Query %d: %s ===\n", i+1, query) userMsg := genai.NewContentFromText(query, genai.RoleUser) streamingMode := agent.StreamingModeSSE for event, err := range r.Run(ctx, userID, session.ID(), userMsg, agent.RunConfig{ StreamingMode: streamingMode, }) { if err != nil { fmt.Printf("\nAGENT_ERROR: %v\n", err) } else { if event.LLMResponse.Content != nil { for _, p := range event.LLMResponse.Content.Parts { // if its running in streaming mode, don't print the non partial llmResponses if streamingMode != agent.StreamingModeSSE || event.LLMResponse.Partial { fmt.Print(p.Text) } } } } } fmt.Println("\n" + strings.Repeat("-", 80) + "\n") } } 4. Ensure all dependencies are installed: go mod tidy 5. Run your agent, and observe the results: go run hotelagent.go Info For more information, visit the [Go SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-go) . Last modified November 6, 2025: [docs(tbadk): Add documentation for tbadk (#1846) (016c4c02d76)](https://github.com/googleapis/genai-toolbox/commit/016c4c02d7633c629b5025d770ac0443264d5058) --- # JS Quickstart (Local) | MCP Toolbox for Databases JS Quickstart (Local) ===================== How to get started running MCP Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Node.js (v18 or higher)](https://nodejs.org/) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. 1. (Optional) Initialize a Node.js project: npm init -y 2. In a new terminal, install the SDK package. * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/adk 3. Install other required dependencies * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install langchain @langchain/google-genai npm install genkit @genkit-ai/googleai npm install llamaindex @llamaindex/google @llamaindex/workflow npm install @google/genai npm install @google/adk 4. Create a new file named `hotelAgent.js` and copy the following code to create an agent: * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK import { ChatGoogleGenerativeAI } from "@langchain/google-genai"; import { ToolboxClient } from "@toolbox-sdk/core"; import { tool } from "@langchain/core/tools"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { MemorySaver } from "@langchain/langgraph"; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const model = new ChatGoogleGenerativeAI({ model: "gemini-2.0-flash", }); const client = new ToolboxClient("http://127.0.0.1:5000"); const toolboxTools = await client.loadToolset("my-toolset"); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(toolboxTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); const tools = toolboxTools.map(getTool); const agent = createReactAgent({ llm: model, tools: tools, checkpointer: new MemorySaver(), systemPrompt: prompt, }); const langGraphConfig = { configurable: { thread_id: "test-thread", }, }; for (const query of queries) { const agentOutput = await agent.invoke( { messages: [\ {\ role: "user",\ content: query,\ },\ ], verbose: true, }, langGraphConfig ); const response = agentOutput.messages[agentOutput.messages.length - 1].content; console.log(response); } } main(); import { ToolboxClient } from "@toolbox-sdk/core"; import { genkit } from "genkit"; import { googleAI } from '@genkit-ai/googleai'; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const toolboxClient = new ToolboxClient("http://127.0.0.1:5000"); const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const toolMap = Object.fromEntries( toolboxTools.map((tool) => { const definedTool = ai.defineTool( { name: tool.getName(), description: tool.getDescription(), inputSchema: tool.getParamSchema(), }, tool ); return [tool.getName(), definedTool]; }) ); const tools = Object.values(toolMap); let conversationHistory = [{ role: "system", content: [{ text: systemPrompt }] }]; for (const query of queries) { conversationHistory.push({ role: "user", content: [{ text: query }] }); let response = await ai.generate({ messages: conversationHistory, tools: tools, }); conversationHistory.push(response.message); const toolRequests = response.toolRequests; if (toolRequests?.length > 0) { // Execute tools concurrently and collect their responses. const toolResponses = await Promise.all( toolRequests.map(async (call) => { try { const toolOutput = await toolMap[call.name].invoke(call.input); return { role: "tool", content: [{ toolResponse: { name: call.name, output: toolOutput } }] }; } catch (e) { console.error(`Error executing tool ${call.name}:`, e); return { role: "tool", content: [{ toolResponse: { name: call.name, output: { error: e.message } } }] }; } }) ); conversationHistory.push(...toolResponses); // Call the AI again with the tool results. response = await ai.generate({ messages: conversationHistory, tools }); conversationHistory.push(response.message); } console.log(response.text); } } main(); import { gemini, GEMINI_MODEL } from "@llamaindex/google"; import { agent } from "@llamaindex/workflow"; import { createMemory, staticBlock, tool } from "llamaindex"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches — this is very important for operations. For any bookings or cancellations, please provide the appropriate confirmation. Update check-in or check-out dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { // Connect to MCP Toolbox const client = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await client.loadToolset("my-toolset"); const tools = toolboxTools.map((toolboxTool) => { return tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool, }); }); // Initialize LLM const llm = gemini({ model: GEMINI_MODEL.GEMINI_2_0_FLASH, apiKey: GOOGLE_API_KEY, }); const memory = createMemory({ memoryBlocks: [\ staticBlock({\ content: prompt,\ }),\ ], }); // Create the Agent const myAgent = agent({ tools: tools, llm, memory, systemPrompt: prompt, }); for (const query of queries) { const result = await myAgent.run(query); const output = result.data.result; console.log(`\nUser: ${query}`); if (typeof output === "string") { console.log(output.trim()); } else if (typeof output === "object" && "text" in output) { console.log(output.text.trim()); } else { console.log(JSON.stringify(output)); } } //You may observe some extra logs during execution due to the run method provided by Llama. console.log("Agent run finished."); } main(); import { GoogleGenAI } from "@google/genai"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, you MUST use the available tools to find information. Mention its name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; function mapZodTypeToOpenAPIType(zodTypeName) { const typeMap = { 'ZodString': 'string', 'ZodNumber': 'number', 'ZodBoolean': 'boolean', 'ZodArray': 'array', 'ZodObject': 'object', }; return typeMap[zodTypeName] || 'string'; } export async function main() { const toolboxClient = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const geminiTools = [{\ functionDeclarations: toolboxTools.map(tool => {\ \ const schema = tool.getParamSchema();\ const properties = {};\ const required = [];\ \ \ for (const [key, param] of Object.entries(schema.shape)) {\ properties[key] = {\ type: mapZodTypeToOpenAPIType(param.constructor.name),\ description: param.description || '',\ };\ required.push(key)\ }\ \ return {\ name: tool.getName(),\ description: tool.getDescription(),\ parameters: { type: 'object', properties, required },\ };\ })\ }]; const genAI = new GoogleGenAI({ apiKey: GOOGLE_API_KEY }); const chat = genAI.chats.create({ model: "gemini-2.5-flash", config: { systemInstruction: prompt, tools: geminiTools, } }); for (const query of queries) { let currentResult = await chat.sendMessage({ message: query }); let finalResponseGiven = false while (!finalResponseGiven) { const response = currentResult; const functionCalls = response.functionCalls || []; if (functionCalls.length === 0) { console.log(response.text) finalResponseGiven = true; } else { const toolResponses = []; for (const call of functionCalls) { const toolName = call.name const toolToExecute = toolboxTools.find(t => t.getName() === toolName); if (toolToExecute) { try { const functionResult = await toolToExecute(call.args); toolResponses.push({ functionResponse: { name: call.name, response: { result: functionResult } } }); } catch (e) { console.error(`Error executing tool '${toolName}':`, e); toolResponses.push({ functionResponse: { name: call.name, response: { error: e.message } } }); } } } currentResult = await chat.sendMessage({ message: toolResponses }); } } } } main(); import { InMemoryRunner, LlmAgent, LogLevel } from '@google/adk'; import { ToolboxClient } from '@toolbox-sdk/adk'; const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; process.env.GOOGLE_GENAI_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key export async function main() { const userId = 'test_user'; const client = new ToolboxClient('http://127.0.0.1:5000'); const tools = await client.loadToolset("my-toolset"); const rootAgent = new LlmAgent({ name: 'hotel_agent', model: 'gemini-2.5-flash', description: 'Agent for hotel bookings and administration.', instruction: prompt, tools: tools, }); const appName = rootAgent.name; const runner = new InMemoryRunner({ agent: rootAgent, appName, logLevel: LogLevel.ERROR, }); const session = await runner.sessionService.createSession({ appName, userId }); for (const query of queries) { await runPrompt(runner, userId, session.id, query); } } async function runPrompt(runner, userId, sessionId, prompt) { const content = { role: 'user', parts: [{ text: prompt }] }; const stream = runner.runAsync({ userId, sessionId, newMessage: content }); const responses = []; for await (const response of stream) { responses.push(response); } const accumulatedResponse = responses .flatMap((e) => e.content?.parts?.map((p) => p.text) ?? []) .join(''); console.log(`\nMODEL RESPONSE: ${accumulatedResponse}\n`); } main(); 5. Run your agent, and observe the results: node hotelAgent.js Info For more information, visit the [JS SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-js) . Last modified February 18, 2026: [docs: make branding consistent across quickstart docs (#2498) (e84a51b660c)](https://github.com/googleapis/genai-toolbox/commit/e84a51b660c36242e89ae8a2259a7e9ee927c673) --- # Prompts using Gemini CLI | MCP Toolbox for Databases Prompts using Gemini CLI ======================== How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create the required tables using the following commands: CREATE TABLE users ( id SERIAL PRIMARY KEY, username VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE restaurants ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, location VARCHAR(100) ); CREATE TABLE reviews ( id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id), restaurant_id INT REFERENCES restaurants(id), rating INT CHECK (rating >= 1 AND rating <= 5), review_text TEXT, is_published BOOLEAN DEFAULT false, moderation_status VARCHAR(50) DEFAULT 'pending_manual_review', created_at TIMESTAMPTZ DEFAULT NOW() ); 6. Insert dummy data into the tables. INSERT INTO users (id, username, email) VALUES (123, 'jane_d', '[email protected]'), (124, 'john_s', '[email protected]'), (125, 'sam_b', '[email protected]'); INSERT INTO restaurants (id, name, location) VALUES (455, 'Pizza Palace', '123 Main St'), (456, 'The Corner Bistro', '456 Oak Ave'), (457, 'Sushi Spot', '789 Pine Ln'); INSERT INTO reviews (user_id, restaurant_id, rating, review_text, is_published, moderation_status) VALUES (124, 455, 5, 'Best pizza in town! The crust was perfect.', true, 'approved'), (125, 457, 4, 'Great sushi, very fresh. A bit pricey but worth it.', true, 'approved'), (123, 457, 5, 'Absolutely loved the dragon roll. Will be back!', true, 'approved'), (123, 456, 4, 'The atmosphere was lovely and the food was great. My photo upload might have been weird though.', false, 'pending_manual_review'), (125, 456, 1, 'This review contains inappropriate language.', false, 'rejected'); 7. End the database session: \q Step 2: Configure Toolbox ------------------------- Create a file named `tools.yaml`. This file defines the database connection, the SQL tools available, and the prompts the agents will use. sources: my-foodiefind-db: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password tools: find_user_by_email: kind: postgres-sql source: my-foodiefind-db description: Find a user's ID by their email address. parameters: - name: email type: string description: The email address of the user to find. statement: SELECT id FROM users WHERE email = $1; find_restaurant_by_name: kind: postgres-sql source: my-foodiefind-db description: Find a restaurant's ID by its exact name. parameters: - name: name type: string description: The name of the restaurant to find. statement: SELECT id FROM restaurants WHERE name = $1; find_review_by_user_and_restaurant: kind: postgres-sql source: my-foodiefind-db description: Find the full record for a specific review using the user's ID and the restaurant's ID. parameters: - name: user_id type: integer description: The numerical ID of the user. - name: restaurant_id type: integer description: The numerical ID of the restaurant. statement: SELECT * FROM reviews WHERE user_id = $1 AND restaurant_id = $2; prompts: investigate_missing_review: description: "Investigates a user's missing review by finding the user, restaurant, and the review itself, then analyzing its status." arguments: - name: "user_email" description: "The email of the user who wrote the review." - name: "restaurant_name" description: "The name of the restaurant being reviewed." messages: - content: >- **Goal:** Find the review written by the user with email '{{.user_email}}' for the restaurant named '{{.restaurant_name}}' and understand its status. **Workflow:** 1. Use the `find_user_by_email` tool with the email '{{.user_email}}' to get the `user_id`. 2. Use the `find_restaurant_by_name` tool with the name '{{.restaurant_name}}' to get the `restaurant_id`. 3. Use the `find_review_by_user_and_restaurant` tool with the `user_id` and `restaurant_id` you just found. 4. Analyze the results from the final tool call. Examine the `is_published` and `moderation_status` fields and explain the review's status to the user in a clear, human-readable sentence. Step 3: Connect to Gemini CLI ----------------------------- Configure the Gemini CLI to talk to your local Toolbox MCP server. 1. Open or create your Gemini settings file: `~/.gemini/settings.json`. 2. Add the following configuration to the file: { "mcpServers": { "MCPToolbox": { "httpUrl": "http://localhost:5000/mcp" } }, "mcp": { "allowed": ["MCPToolbox"] } } 3. Start Gemini CLI using gemini In case Gemini CLI is already running, use `/mcp refresh` to refresh the MCP server. 4. Use gemini slash commands to run your prompt: /investigate_missing_review --user_email="[email protected]" --restaurant_name="The Corner Bistro" Last modified December 11, 2025: [docs: add prompts quickstart using gemini cli (#2158) (1f31c2c9b27)](https://github.com/googleapis/genai-toolbox/commit/1f31c2c9b2714a516aa2bc30317b736797ecf9a0) --- # Quickstart (MCP) | MCP Toolbox for Databases Quickstart (MCP) ================ How to get started running Toolbox locally with MCP Inspector. Overview -------- [Model Context Protocol](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to LLMs. Check out this page on how to [connect to Toolbox via MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect_via_mcp/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be access by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the [Tools](https://mcp-toolbox.dev/v0.24.0/resources/tools/) section. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Step 3: Connect to MCP Inspector -------------------------------- 1. Run the MCP Inspector: npx @modelcontextprotocol/inspector 2. Type `y` when it asks to install the inspector package. 3. It should show the following when the MCP Inspector is up and running (please take note of ``): Starting MCP inspector... ⚙️ Proxy server listening on localhost:6277 🔑 Session token: Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth 🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN= 4. Open the above link in your browser. 5. For `Transport Type`, select `Streamable HTTP`. 6. For `URL`, type in `http://127.0.0.1:5000/mcp`. 7. For `Configuration` -> `Proxy Session Token`, make sure `` is present. 8. Click Connect. ![inspector](https://mcp-toolbox.dev/v0.24.0/getting-started/mcp_quickstart/inspector.png) 9. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. ![inspector_tools](https://mcp-toolbox.dev/v0.24.0/getting-started/mcp_quickstart/inspector_tools.png) 10. Test out your tools here! Last modified December 19, 2025: [chore(main): release 0.24.0 (#2162) (f520b4ed8ae)](https://github.com/googleapis/genai-toolbox/commit/f520b4ed8aedc28147777bdb673a576092a53513) --- # JS Quickstart (Local) | MCP Toolbox for Databases JS Quickstart (Local) ===================== How to get started running MCP Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Node.js (v18 or higher)](https://nodejs.org/) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. 1. (Optional) Initialize a Node.js project: npm init -y 2. In a new terminal, install the SDK package. * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/adk 3. Install other required dependencies * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install langchain @langchain/google-genai npm install genkit @genkit-ai/googleai npm install llamaindex @llamaindex/google @llamaindex/workflow npm install @google/genai npm install @google/adk 4. Create a new file named `hotelAgent.js` and copy the following code to create an agent: * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK import { ChatGoogleGenerativeAI } from "@langchain/google-genai"; import { ToolboxClient } from "@toolbox-sdk/core"; import { tool } from "@langchain/core/tools"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { MemorySaver } from "@langchain/langgraph"; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const model = new ChatGoogleGenerativeAI({ model: "gemini-2.0-flash", }); const client = new ToolboxClient("http://127.0.0.1:5000"); const toolboxTools = await client.loadToolset("my-toolset"); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(toolboxTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); const tools = toolboxTools.map(getTool); const agent = createReactAgent({ llm: model, tools: tools, checkpointer: new MemorySaver(), systemPrompt: prompt, }); const langGraphConfig = { configurable: { thread_id: "test-thread", }, }; for (const query of queries) { const agentOutput = await agent.invoke( { messages: [\ {\ role: "user",\ content: query,\ },\ ], verbose: true, }, langGraphConfig ); const response = agentOutput.messages[agentOutput.messages.length - 1].content; console.log(response); } } main(); import { ToolboxClient } from "@toolbox-sdk/core"; import { genkit } from "genkit"; import { googleAI } from '@genkit-ai/googleai'; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const toolboxClient = new ToolboxClient("http://127.0.0.1:5000"); const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const toolMap = Object.fromEntries( toolboxTools.map((tool) => { const definedTool = ai.defineTool( { name: tool.getName(), description: tool.getDescription(), inputSchema: tool.getParamSchema(), }, tool ); return [tool.getName(), definedTool]; }) ); const tools = Object.values(toolMap); let conversationHistory = [{ role: "system", content: [{ text: systemPrompt }] }]; for (const query of queries) { conversationHistory.push({ role: "user", content: [{ text: query }] }); let response = await ai.generate({ messages: conversationHistory, tools: tools, }); conversationHistory.push(response.message); const toolRequests = response.toolRequests; if (toolRequests?.length > 0) { // Execute tools concurrently and collect their responses. const toolResponses = await Promise.all( toolRequests.map(async (call) => { try { const toolOutput = await toolMap[call.name].invoke(call.input); return { role: "tool", content: [{ toolResponse: { name: call.name, output: toolOutput } }] }; } catch (e) { console.error(`Error executing tool ${call.name}:`, e); return { role: "tool", content: [{ toolResponse: { name: call.name, output: { error: e.message } } }] }; } }) ); conversationHistory.push(...toolResponses); // Call the AI again with the tool results. response = await ai.generate({ messages: conversationHistory, tools }); conversationHistory.push(response.message); } console.log(response.text); } } main(); import { gemini, GEMINI_MODEL } from "@llamaindex/google"; import { agent } from "@llamaindex/workflow"; import { createMemory, staticBlock, tool } from "llamaindex"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches — this is very important for operations. For any bookings or cancellations, please provide the appropriate confirmation. Update check-in or check-out dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { // Connect to MCP Toolbox const client = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await client.loadToolset("my-toolset"); const tools = toolboxTools.map((toolboxTool) => { return tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool, }); }); // Initialize LLM const llm = gemini({ model: GEMINI_MODEL.GEMINI_2_0_FLASH, apiKey: GOOGLE_API_KEY, }); const memory = createMemory({ memoryBlocks: [\ staticBlock({\ content: prompt,\ }),\ ], }); // Create the Agent const myAgent = agent({ tools: tools, llm, memory, systemPrompt: prompt, }); for (const query of queries) { const result = await myAgent.run(query); const output = result.data.result; console.log(`\nUser: ${query}`); if (typeof output === "string") { console.log(output.trim()); } else if (typeof output === "object" && "text" in output) { console.log(output.text.trim()); } else { console.log(JSON.stringify(output)); } } //You may observe some extra logs during execution due to the run method provided by Llama. console.log("Agent run finished."); } main(); import { GoogleGenAI } from "@google/genai"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, you MUST use the available tools to find information. Mention its name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; function mapZodTypeToOpenAPIType(zodTypeName) { const typeMap = { 'ZodString': 'string', 'ZodNumber': 'number', 'ZodBoolean': 'boolean', 'ZodArray': 'array', 'ZodObject': 'object', }; return typeMap[zodTypeName] || 'string'; } export async function main() { const toolboxClient = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const geminiTools = [{\ functionDeclarations: toolboxTools.map(tool => {\ \ const schema = tool.getParamSchema();\ const properties = {};\ const required = [];\ \ \ for (const [key, param] of Object.entries(schema.shape)) {\ properties[key] = {\ type: mapZodTypeToOpenAPIType(param.constructor.name),\ description: param.description || '',\ };\ required.push(key)\ }\ \ return {\ name: tool.getName(),\ description: tool.getDescription(),\ parameters: { type: 'object', properties, required },\ };\ })\ }]; const genAI = new GoogleGenAI({ apiKey: GOOGLE_API_KEY }); const chat = genAI.chats.create({ model: "gemini-2.5-flash", config: { systemInstruction: prompt, tools: geminiTools, } }); for (const query of queries) { let currentResult = await chat.sendMessage({ message: query }); let finalResponseGiven = false while (!finalResponseGiven) { const response = currentResult; const functionCalls = response.functionCalls || []; if (functionCalls.length === 0) { console.log(response.text) finalResponseGiven = true; } else { const toolResponses = []; for (const call of functionCalls) { const toolName = call.name const toolToExecute = toolboxTools.find(t => t.getName() === toolName); if (toolToExecute) { try { const functionResult = await toolToExecute(call.args); toolResponses.push({ functionResponse: { name: call.name, response: { result: functionResult } } }); } catch (e) { console.error(`Error executing tool '${toolName}':`, e); toolResponses.push({ functionResponse: { name: call.name, response: { error: e.message } } }); } } } currentResult = await chat.sendMessage({ message: toolResponses }); } } } } main(); import { InMemoryRunner, LlmAgent, LogLevel } from '@google/adk'; import { ToolboxClient } from '@toolbox-sdk/adk'; const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; process.env.GOOGLE_GENAI_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key export async function main() { const userId = 'test_user'; const client = new ToolboxClient('http://127.0.0.1:5000'); const tools = await client.loadToolset("my-toolset"); const rootAgent = new LlmAgent({ name: 'hotel_agent', model: 'gemini-2.5-flash', description: 'Agent for hotel bookings and administration.', instruction: prompt, tools: tools, }); const appName = rootAgent.name; const runner = new InMemoryRunner({ agent: rootAgent, appName, logLevel: LogLevel.ERROR, }); const session = await runner.sessionService.createSession({ appName, userId }); for (const query of queries) { await runPrompt(runner, userId, session.id, query); } } async function runPrompt(runner, userId, sessionId, prompt) { const content = { role: 'user', parts: [{ text: prompt }] }; const stream = runner.runAsync({ userId, sessionId, newMessage: content }); const responses = []; for await (const response of stream) { responses.push(response); } const accumulatedResponse = responses .flatMap((e) => e.content?.parts?.map((p) => p.text) ?? []) .join(''); console.log(`\nMODEL RESPONSE: ${accumulatedResponse}\n`); } main(); 5. Run your agent, and observe the results: node hotelAgent.js Info For more information, visit the [JS SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-js) . Last modified February 18, 2026: [docs: make branding consistent across quickstart docs (#2498) (e84a51b660c)](https://github.com/googleapis/genai-toolbox/commit/e84a51b660c36242e89ae8a2259a7e9ee927c673) --- # Go Quickstart (Local) | MCP Toolbox for Databases Go Quickstart (Local) ===================== How to get started running Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Go (v1.24.2 or higher)](https://go.dev/doc/install) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to Toolbox ------------------------------------- In this section, we will write and run an agent that will load the Tools from Toolbox. 1. Initialize a go module: go mod init main 2. In a new terminal, install the [SDK](https://pkg.go.dev/github.com/googleapis/mcp-toolbox-sdk-go) . go get github.com/googleapis/mcp-toolbox-sdk-go 3. Create a new file named `hotelagent.go` and copy the following code to create an agent: * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" "github.com/tmc/langchaingo/llms/googleai" ) // ConvertToLangchainTool converts a generic core.ToolboxTool into a LangChainGo llms.Tool. func ConvertToLangchainTool(toolboxTool *core.ToolboxTool) llms.Tool { // Fetch the tool's input schema inputschema, err := toolboxTool.InputSchema() if err != nil { return llms.Tool{} } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Convert into LangChain's llms.Tool return llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the Google AI client (LLM). llm, err := googleai.New(ctx, googleai.WithAPIKey(genaiKey), googleai.WithDefaultModel("gemini-2.0-flash")) if err != nil { log.Fatalf("Failed to create Google AI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } toolsMap := make(map[string]*core.ToolboxTool, len(tools)) langchainTools := make([]llms.Tool, len(tools)) // Convert the loaded ToolboxTools into the format LangChainGo requires. for i, tool := range tools { langchainTools[i] = ConvertToLangchainTool(tool) toolsMap[tool.Name()] = tool } // Start the conversation history. messageHistory := []llms.MessageContent{ llms.TextParts(llms.ChatMessageTypeSystem, systemPrompt), } for _, query := range queries { messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeHuman, query)) // Make the first call to the LLM, making it aware of the tool. resp, err := llm.GenerateContent(ctx, messageHistory, llms.WithTools(langchainTools)) if err != nil { log.Fatalf("LLM call failed: %v", err) } respChoice := resp.Choices[0] assistantResponse := llms.TextParts(llms.ChatMessageTypeAI, respChoice.Content) for _, tc := range respChoice.ToolCalls { assistantResponse.Parts = append(assistantResponse.Parts, tc) } messageHistory = append(messageHistory, assistantResponse) // Process each tool call requested by the model. for _, tc := range respChoice.ToolCalls { toolName := tc.FunctionCall.Name tool := toolsMap[toolName] var args map[string]any if err := json.Unmarshal([]byte(tc.FunctionCall.Arguments), &args); err != nil { log.Fatalf("Failed to unmarshal arguments for tool '%s': %v", toolName, err) } toolResult, err := tool.Invoke(ctx, args) if err != nil { log.Fatalf("Failed to execute tool '%s': %v", toolName, err) } if toolResult == "" || toolResult == nil { toolResult = "Operation completed successfully with no specific return value." } // Create the tool call response message and add it to the history. toolResponse := llms.MessageContent{ Role: llms.ChatMessageTypeTool, Parts: []llms.ContentPart{ llms.ToolCallResponse{ Name: toolName, Content: fmt.Sprintf("%v", toolResult), }, }, } messageHistory = append(messageHistory, toolResponse) } finalResp, err := llm.GenerateContent(ctx, messageHistory) if err != nil { log.Fatalf("Final LLM call failed after tool execution: %v", err) } // Add the final textual response from the LLM to the history messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeAI, finalResp.Choices[0].Content)) fmt.Println(finalResp.Choices[0].Content) } } package main import ( "context" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/firebase/genkit/go/plugins/googlegenai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { ctx := context.Background() // Create Toolbox Client toolboxClient, err := core.NewToolboxClient("http://127.0.0.1:5000") if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } // Initialize Genkit g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}), genkit.WithDefaultModel("googleai/gemini-2.0-flash"), ) if err != nil { log.Fatalf("Failed to init genkit: %v\n", err) } // Create a conversation history conversationHistory := []*ai.Message{ ai.NewSystemTextMessage(systemPrompt), } // Convert your tool to a Genkit tool. genkitTools := make([]ai.Tool, len(tools)) for i, tool := range tools { newTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } genkitTools[i] = newTool } toolRefs := make([]ai.ToolRef, len(genkitTools)) for i, tool := range genkitTools { toolRefs[i] = tool } for _, query := range queries { conversationHistory = append(conversationHistory, ai.NewUserTextMessage(query)) response, err := genkit.Generate(ctx, g, ai.WithMessages(conversationHistory...), ai.WithTools(toolRefs...), ai.WithReturnToolRequests(true), ) if err != nil { log.Fatalf("%v\n", err) } conversationHistory = append(conversationHistory, response.Message) parts := []*ai.Part{} for _, req := range response.ToolRequests() { tool := genkit.LookupTool(g, req.Name) if tool == nil { log.Fatalf("tool %q not found", req.Name) } output, err := tool.RunRaw(ctx, req.Input) if err != nil { log.Fatalf("tool %q execution failed: %v", tool.Name(), err) } parts = append(parts, ai.NewToolResponsePart(&ai.ToolResponse{ Name: req.Name, Ref: req.Ref, Output: output, })) } if len(parts) > 0 { resp, err := genkit.Generate(ctx, g, ai.WithMessages(append(response.History(), ai.NewMessage(ai.RoleTool, nil, parts...))...), ai.WithTools(toolRefs...), ) if err != nil { log.Fatal(err) } fmt.Println("\n", resp.Text()) conversationHistory = append(conversationHistory, resp.Message) } else { fmt.Println("\n", response.Text()) } } } package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) // ConvertToGenaiTool translates a ToolboxTool into the genai.FunctionDeclaration format. func ConvertToGenaiTool(toolboxTool *core.ToolboxTool) *genai.Tool { inputschema, err := toolboxTool.InputSchema() if err != nil { return &genai.Tool{} } var paramsSchema *genai.Schema _ = json.Unmarshal(inputschema, ¶msSchema) // First, create the function declaration. funcDeclaration := &genai.FunctionDeclaration{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, } // Then, wrap the function declaration in a genai.Tool struct. return &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } func printResponse(resp *genai.GenerateContentResponse) { for _, cand := range resp.Candidates { if cand.Content != nil { for _, part := range cand.Content.Parts { fmt.Println(part.Text) } } } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() apiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" // Initialize the Google GenAI client using the explicit ClientConfig. client, err := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: apiKey, }) if err != nil { log.Fatalf("Failed to create Google GenAI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } genAITools := make([]*genai.Tool, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { genAITools[i] = ConvertToGenaiTool(tool) toolsMap[tool.Name()] = tool } // Set up the generative model with the available tool. modelName := "gemini-2.0-flash" // Create the initial content prompt for the model. messageHistory := []*genai.Content{ genai.NewContentFromText(systemPrompt, genai.RoleUser), } config := &genai.GenerateContentConfig{ Tools: genAITools, ToolConfig: &genai.ToolConfig{ FunctionCallingConfig: &genai.FunctionCallingConfig{ Mode: genai.FunctionCallingConfigModeAny, }, }, } for _, query := range queries { messageHistory = append(messageHistory, genai.NewContentFromText(query, genai.RoleUser)) genContentResp, err := client.Models.GenerateContent(ctx, modelName, messageHistory, config) if err != nil { log.Fatalf("LLM call failed for query '%s': %v", query, err) } if len(genContentResp.Candidates) > 0 && genContentResp.Candidates[0].Content != nil { messageHistory = append(messageHistory, genContentResp.Candidates[0].Content) } functionCalls := genContentResp.FunctionCalls() toolResponseParts := []*genai.Part{} for _, fc := range functionCalls { toolToInvoke, found := toolsMap[fc.Name] if !found { log.Fatalf("Tool '%s' not found in loaded tools map. Check toolset configuration.", fc.Name) } toolResult, invokeErr := toolToInvoke.Invoke(ctx, fc.Args) if invokeErr != nil { log.Fatalf("Failed to execute tool '%s': %v", fc.Name, invokeErr) } // Enhanced Tool Result Handling (retained to prevent nil issues) toolResultString := "" if toolResult != nil { jsonBytes, marshalErr := json.Marshal(toolResult) if marshalErr == nil { toolResultString = string(jsonBytes) } else { toolResultString = fmt.Sprintf("%v", toolResult) } } responseMap := map[string]any{"result": toolResultString} toolResponseParts = append(toolResponseParts, genai.NewPartFromFunctionResponse(fc.Name, responseMap)) } // Add all accumulated tool responses for this turn to the message history. toolResponseContent := genai.NewContentFromParts(toolResponseParts, "function") messageHistory = append(messageHistory, toolResponseContent) finalResponse, err := client.Models.GenerateContent(ctx, modelName, messageHistory, &genai.GenerateContentConfig{}) if err != nil { log.Fatalf("Error calling GenerateContent (with function result): %v", err) } printResponse(finalResponse) // Add the final textual response from the LLM to the history if len(finalResponse.Candidates) > 0 && finalResponse.Candidates[0].Content != nil { messageHistory = append(messageHistory, finalResponse.Candidates[0].Content) } } } package main import ( "context" "encoding/json" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go/v3" ) // ConvertToOpenAITool converts a ToolboxTool into the go-openai library's Tool format. func ConvertToOpenAITool(toolboxTool *core.ToolboxTool) openai.ChatCompletionToolUnionParam { // Get the input schema jsonSchemaBytes, err := toolboxTool.InputSchema() if err != nil { return openai.ChatCompletionToolUnionParam{} } // Unmarshal the JSON bytes into FunctionParameters var paramsSchema openai.FunctionParameters if err := json.Unmarshal(jsonSchemaBytes, ¶msSchema); err != nil { return openai.ChatCompletionToolUnionParam{} } // Create and return the final tool parameter struct. return openai.ChatCompletionToolUnionParam{ OfFunction: &openai.ChatCompletionFunctionToolParam{ Function: openai.FunctionDefinitionParam{ Name: toolboxTool.Name(), Description: openai.String(toolboxTool.Description()), Parameters: paramsSchema, }, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() toolboxURL := "http://localhost:5000" openAIClient := openai.NewClient() // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tool : %v\nMake sure your Toolbox server is running and the tool is configured.", err) } openAITools := make([]openai.ChatCompletionToolUnionParam, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { // Convert the Toolbox tool into the openAI FunctionDeclaration format. openAITools[i] = ConvertToOpenAITool(tool) // Add tool to a map for lookup later toolsMap[tool.Name()] = tool } params := openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{ openai.SystemMessage(systemPrompt), }, Tools: openAITools, Seed: openai.Int(0), Model: openai.ChatModelGPT4o, } for _, query := range queries { params.Messages = append(params.Messages, openai.UserMessage(query)) // Make initial chat completion request completion, err := openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } toolCalls := completion.Choices[0].Message.ToolCalls // Return early if there are no tool calls if len(toolCalls) == 0 { log.Println("No function call") } // If there was a function call, continue the conversation params.Messages = append(params.Messages, completion.Choices[0].Message.ToParam()) for _, toolCall := range toolCalls { toolName := toolCall.Function.Name toolToInvoke := toolsMap[toolName] var args map[string]any err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args) if err != nil { panic(err) } result, err := toolToInvoke.Invoke(ctx, args) if err != nil { log.Fatal("Could not invoke tool", err) } params.Messages = append(params.Messages, openai.ToolMessage(result.(string), toolCall.ID)) } completion, err = openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } params.Messages = append(params.Messages, openai.AssistantMessage(query)) fmt.Println("\n", completion.Choices[0].Message.Content) } } package main import ( "context" "fmt" "log" "os" "strings" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/model/gemini" "google.golang.org/adk/runner" "google.golang.org/adk/session" "google.golang.org/adk/tool" "google.golang.org/genai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queriesAdk = []string{ "Find hotels in Basel. ", "Find hotels with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GEMINI_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the MCP Toolbox client. toolboxClient, err := tbadk.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create MCP Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. toolsetName := "my-toolset" mcpTools, err := toolboxClient.LoadToolset(toolsetName, ctx) if err != nil { log.Fatalf("Failed to load MCP toolset '%s': %v\nMake sure your Toolbox server is running.", toolsetName, err) } // Set up the Gemini Model model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{ APIKey: genaiKey, }) if err != nil { log.Fatalf("Failed to create model: %v", err) } // Type Cast the ToolboxTools tools := make([]tool.Tool, len(mcpTools)) for i := range mcpTools { tools[i] = &mcpTools[i] } // Create an llm agent llmagent, err := llmagent.New(llmagent.Config{ Name: "hotel_assistant", Model: model, Description: "Agent to answer questions about hotels.", Instruction: systemPrompt, Tools: tools, }) if err != nil { log.Fatalf("Failed to create agent: %v", err) } appName := "hotel_assistant" userID := "user-123" // Create a session service sessionService := session.InMemoryService() resp, err := sessionService.Create(ctx, &session.CreateRequest{ AppName: appName, UserID: userID, }) if err != nil { log.Fatalf("Failed to create the session service: %v", err) } session := resp.Session // Configure the runner r, err := runner.New(runner.Config{ AppName: appName, Agent: llmagent, SessionService: sessionService, }) if err != nil { log.Fatalf("Failed to create runner: %v", err) } // Loop through queries to the llm agent for i, query := range queriesAdk { fmt.Printf("\n=== Query %d: %s ===\n", i+1, query) userMsg := genai.NewContentFromText(query, genai.RoleUser) streamingMode := agent.StreamingModeSSE for event, err := range r.Run(ctx, userID, session.ID(), userMsg, agent.RunConfig{ StreamingMode: streamingMode, }) { if err != nil { fmt.Printf("\nAGENT_ERROR: %v\n", err) } else { if event.LLMResponse.Content != nil { for _, p := range event.LLMResponse.Content.Parts { // if its running in streaming mode, don't print the non partial llmResponses if streamingMode != agent.StreamingModeSSE || event.LLMResponse.Partial { fmt.Print(p.Text) } } } } } fmt.Println("\n" + strings.Repeat("-", 80) + "\n") } } 4. Ensure all dependencies are installed: go mod tidy 5. Run your agent, and observe the results: go run hotelagent.go Info For more information, visit the [Go SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-go) . Last modified November 6, 2025: [docs(tbadk): Add documentation for tbadk (#1846) (016c4c02d76)](https://github.com/googleapis/genai-toolbox/commit/016c4c02d7633c629b5025d770ac0443264d5058) --- # Go Quickstart (Local) | MCP Toolbox for Databases Go Quickstart (Local) ===================== How to get started running MCP Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Go (v1.24.2 or higher)](https://go.dev/doc/install) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. 1. Initialize a go module: go mod init main 2. In a new terminal, install the Go SDK Module: Warning Breaking Change Notice: As of version `0.6.0`, this SDK has transitioned to a multi-module structure. * For new versions (`v0.6.0`+): You must import specific modules (e.g., `go get github.com/googleapis/mcp-toolbox-sdk-go/core`). * For older versions (`v0.5.1` and below): The SDK remains a single-module library (`go get github.com/googleapis/mcp-toolbox-sdk-go`). * Please update your imports and `go.mod` accordingly when upgrading. * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/tbadk 3. Create a new file named `hotelagent.go` and copy the following code to create an agent: * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" "github.com/tmc/langchaingo/llms/googleai" ) // ConvertToLangchainTool converts a generic core.ToolboxTool into a LangChainGo llms.Tool. func ConvertToLangchainTool(toolboxTool *core.ToolboxTool) llms.Tool { // Fetch the tool's input schema inputschema, err := toolboxTool.InputSchema() if err != nil { return llms.Tool{} } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Convert into LangChain's llms.Tool return llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the Google AI client (LLM). llm, err := googleai.New(ctx, googleai.WithAPIKey(genaiKey), googleai.WithDefaultModel("gemini-2.0-flash")) if err != nil { log.Fatalf("Failed to create Google AI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } toolsMap := make(map[string]*core.ToolboxTool, len(tools)) langchainTools := make([]llms.Tool, len(tools)) // Convert the loaded ToolboxTools into the format LangChainGo requires. for i, tool := range tools { langchainTools[i] = ConvertToLangchainTool(tool) toolsMap[tool.Name()] = tool } // Start the conversation history. messageHistory := []llms.MessageContent{ llms.TextParts(llms.ChatMessageTypeSystem, systemPrompt), } for _, query := range queries { messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeHuman, query)) // Make the first call to the LLM, making it aware of the tool. resp, err := llm.GenerateContent(ctx, messageHistory, llms.WithTools(langchainTools)) if err != nil { log.Fatalf("LLM call failed: %v", err) } respChoice := resp.Choices[0] assistantResponse := llms.TextParts(llms.ChatMessageTypeAI, respChoice.Content) for _, tc := range respChoice.ToolCalls { assistantResponse.Parts = append(assistantResponse.Parts, tc) } messageHistory = append(messageHistory, assistantResponse) // Process each tool call requested by the model. for _, tc := range respChoice.ToolCalls { toolName := tc.FunctionCall.Name tool := toolsMap[toolName] var args map[string]any if err := json.Unmarshal([]byte(tc.FunctionCall.Arguments), &args); err != nil { log.Fatalf("Failed to unmarshal arguments for tool '%s': %v", toolName, err) } toolResult, err := tool.Invoke(ctx, args) if err != nil { log.Fatalf("Failed to execute tool '%s': %v", toolName, err) } if toolResult == "" || toolResult == nil { toolResult = "Operation completed successfully with no specific return value." } // Create the tool call response message and add it to the history. toolResponse := llms.MessageContent{ Role: llms.ChatMessageTypeTool, Parts: []llms.ContentPart{ llms.ToolCallResponse{ Name: toolName, Content: fmt.Sprintf("%v", toolResult), }, }, } messageHistory = append(messageHistory, toolResponse) } finalResp, err := llm.GenerateContent(ctx, messageHistory) if err != nil { log.Fatalf("Final LLM call failed after tool execution: %v", err) } // Add the final textual response from the LLM to the history messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeAI, finalResp.Choices[0].Content)) fmt.Println(finalResp.Choices[0].Content) } } package main import ( "context" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/firebase/genkit/go/plugins/googlegenai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { ctx := context.Background() // Create Toolbox Client toolboxClient, err := core.NewToolboxClient("http://127.0.0.1:5000") if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } // Initialize Genkit g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}), genkit.WithDefaultModel("googleai/gemini-2.0-flash"), ) if err != nil { log.Fatalf("Failed to init genkit: %v\n", err) } // Create a conversation history conversationHistory := []*ai.Message{ ai.NewSystemTextMessage(systemPrompt), } // Convert your tool to a Genkit tool. genkitTools := make([]ai.Tool, len(tools)) for i, tool := range tools { newTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } genkitTools[i] = newTool } toolRefs := make([]ai.ToolRef, len(genkitTools)) for i, tool := range genkitTools { toolRefs[i] = tool } for _, query := range queries { conversationHistory = append(conversationHistory, ai.NewUserTextMessage(query)) response, err := genkit.Generate(ctx, g, ai.WithMessages(conversationHistory...), ai.WithTools(toolRefs...), ai.WithReturnToolRequests(true), ) if err != nil { log.Fatalf("%v\n", err) } conversationHistory = append(conversationHistory, response.Message) parts := []*ai.Part{} for _, req := range response.ToolRequests() { tool := genkit.LookupTool(g, req.Name) if tool == nil { log.Fatalf("tool %q not found", req.Name) } output, err := tool.RunRaw(ctx, req.Input) if err != nil { log.Fatalf("tool %q execution failed: %v", tool.Name(), err) } parts = append(parts, ai.NewToolResponsePart(&ai.ToolResponse{ Name: req.Name, Ref: req.Ref, Output: output, })) } if len(parts) > 0 { resp, err := genkit.Generate(ctx, g, ai.WithMessages(append(response.History(), ai.NewMessage(ai.RoleTool, nil, parts...))...), ai.WithTools(toolRefs...), ) if err != nil { log.Fatal(err) } fmt.Println("\n", resp.Text()) conversationHistory = append(conversationHistory, resp.Message) } else { fmt.Println("\n", response.Text()) } } } package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) // ConvertToGenaiTool translates a ToolboxTool into the genai.FunctionDeclaration format. func ConvertToGenaiTool(toolboxTool *core.ToolboxTool) *genai.Tool { inputschema, err := toolboxTool.InputSchema() if err != nil { return &genai.Tool{} } var paramsSchema *genai.Schema _ = json.Unmarshal(inputschema, ¶msSchema) // First, create the function declaration. funcDeclaration := &genai.FunctionDeclaration{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, } // Then, wrap the function declaration in a genai.Tool struct. return &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } func printResponse(resp *genai.GenerateContentResponse) { for _, cand := range resp.Candidates { if cand.Content != nil { for _, part := range cand.Content.Parts { fmt.Println(part.Text) } } } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() apiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" // Initialize the Google GenAI client using the explicit ClientConfig. client, err := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: apiKey, }) if err != nil { log.Fatalf("Failed to create Google GenAI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } genAITools := make([]*genai.Tool, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { genAITools[i] = ConvertToGenaiTool(tool) toolsMap[tool.Name()] = tool } // Set up the generative model with the available tool. modelName := "gemini-2.0-flash" // Create the initial content prompt for the model. messageHistory := []*genai.Content{ genai.NewContentFromText(systemPrompt, genai.RoleUser), } config := &genai.GenerateContentConfig{ Tools: genAITools, ToolConfig: &genai.ToolConfig{ FunctionCallingConfig: &genai.FunctionCallingConfig{ Mode: genai.FunctionCallingConfigModeAny, }, }, } for _, query := range queries { messageHistory = append(messageHistory, genai.NewContentFromText(query, genai.RoleUser)) genContentResp, err := client.Models.GenerateContent(ctx, modelName, messageHistory, config) if err != nil { log.Fatalf("LLM call failed for query '%s': %v", query, err) } if len(genContentResp.Candidates) > 0 && genContentResp.Candidates[0].Content != nil { messageHistory = append(messageHistory, genContentResp.Candidates[0].Content) } functionCalls := genContentResp.FunctionCalls() toolResponseParts := []*genai.Part{} for _, fc := range functionCalls { toolToInvoke, found := toolsMap[fc.Name] if !found { log.Fatalf("Tool '%s' not found in loaded tools map. Check toolset configuration.", fc.Name) } toolResult, invokeErr := toolToInvoke.Invoke(ctx, fc.Args) if invokeErr != nil { log.Fatalf("Failed to execute tool '%s': %v", fc.Name, invokeErr) } // Enhanced Tool Result Handling (retained to prevent nil issues) toolResultString := "" if toolResult != nil { jsonBytes, marshalErr := json.Marshal(toolResult) if marshalErr == nil { toolResultString = string(jsonBytes) } else { toolResultString = fmt.Sprintf("%v", toolResult) } } responseMap := map[string]any{"result": toolResultString} toolResponseParts = append(toolResponseParts, genai.NewPartFromFunctionResponse(fc.Name, responseMap)) } // Add all accumulated tool responses for this turn to the message history. toolResponseContent := genai.NewContentFromParts(toolResponseParts, "function") messageHistory = append(messageHistory, toolResponseContent) finalResponse, err := client.Models.GenerateContent(ctx, modelName, messageHistory, &genai.GenerateContentConfig{}) if err != nil { log.Fatalf("Error calling GenerateContent (with function result): %v", err) } printResponse(finalResponse) // Add the final textual response from the LLM to the history if len(finalResponse.Candidates) > 0 && finalResponse.Candidates[0].Content != nil { messageHistory = append(messageHistory, finalResponse.Candidates[0].Content) } } } package main import ( "context" "encoding/json" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go/v3" ) // ConvertToOpenAITool converts a ToolboxTool into the go-openai library's Tool format. func ConvertToOpenAITool(toolboxTool *core.ToolboxTool) openai.ChatCompletionToolUnionParam { // Get the input schema jsonSchemaBytes, err := toolboxTool.InputSchema() if err != nil { return openai.ChatCompletionToolUnionParam{} } // Unmarshal the JSON bytes into FunctionParameters var paramsSchema openai.FunctionParameters if err := json.Unmarshal(jsonSchemaBytes, ¶msSchema); err != nil { return openai.ChatCompletionToolUnionParam{} } // Create and return the final tool parameter struct. return openai.ChatCompletionToolUnionParam{ OfFunction: &openai.ChatCompletionFunctionToolParam{ Function: openai.FunctionDefinitionParam{ Name: toolboxTool.Name(), Description: openai.String(toolboxTool.Description()), Parameters: paramsSchema, }, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() toolboxURL := "http://localhost:5000" openAIClient := openai.NewClient() // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tool : %v\nMake sure your Toolbox server is running and the tool is configured.", err) } openAITools := make([]openai.ChatCompletionToolUnionParam, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { // Convert the Toolbox tool into the openAI FunctionDeclaration format. openAITools[i] = ConvertToOpenAITool(tool) // Add tool to a map for lookup later toolsMap[tool.Name()] = tool } params := openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{ openai.SystemMessage(systemPrompt), }, Tools: openAITools, Seed: openai.Int(0), Model: openai.ChatModelGPT4o, } for _, query := range queries { params.Messages = append(params.Messages, openai.UserMessage(query)) // Make initial chat completion request completion, err := openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } toolCalls := completion.Choices[0].Message.ToolCalls // Return early if there are no tool calls if len(toolCalls) == 0 { log.Println("No function call") } // If there was a function call, continue the conversation params.Messages = append(params.Messages, completion.Choices[0].Message.ToParam()) for _, toolCall := range toolCalls { toolName := toolCall.Function.Name toolToInvoke := toolsMap[toolName] var args map[string]any err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args) if err != nil { panic(err) } result, err := toolToInvoke.Invoke(ctx, args) if err != nil { log.Fatal("Could not invoke tool", err) } params.Messages = append(params.Messages, openai.ToolMessage(result.(string), toolCall.ID)) } completion, err = openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } params.Messages = append(params.Messages, openai.AssistantMessage(query)) fmt.Println("\n", completion.Choices[0].Message.Content) } } package main import ( "context" "fmt" "log" "os" "strings" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/model/gemini" "google.golang.org/adk/runner" "google.golang.org/adk/session" "google.golang.org/adk/tool" "google.golang.org/genai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queriesAdk = []string{ "Find hotels in Basel. ", "Find hotels with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GEMINI_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the MCP Toolbox client. toolboxClient, err := tbadk.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create MCP Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. toolsetName := "my-toolset" mcpTools, err := toolboxClient.LoadToolset(toolsetName, ctx) if err != nil { log.Fatalf("Failed to load MCP toolset '%s': %v\nMake sure your Toolbox server is running.", toolsetName, err) } // Set up the Gemini Model model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{ APIKey: genaiKey, }) if err != nil { log.Fatalf("Failed to create model: %v", err) } // Type Cast the ToolboxTools tools := make([]tool.Tool, len(mcpTools)) for i := range mcpTools { tools[i] = &mcpTools[i] } // Create an llm agent llmagent, err := llmagent.New(llmagent.Config{ Name: "hotel_assistant", Model: model, Description: "Agent to answer questions about hotels.", Instruction: systemPrompt, Tools: tools, }) if err != nil { log.Fatalf("Failed to create agent: %v", err) } appName := "hotel_assistant" userID := "user-123" // Create a session service sessionService := session.InMemoryService() resp, err := sessionService.Create(ctx, &session.CreateRequest{ AppName: appName, UserID: userID, }) if err != nil { log.Fatalf("Failed to create the session service: %v", err) } session := resp.Session // Configure the runner r, err := runner.New(runner.Config{ AppName: appName, Agent: llmagent, SessionService: sessionService, }) if err != nil { log.Fatalf("Failed to create runner: %v", err) } // Loop through queries to the llm agent for i, query := range queriesAdk { fmt.Printf("\n=== Query %d: %s ===\n", i+1, query) userMsg := genai.NewContentFromText(query, genai.RoleUser) streamingMode := agent.StreamingModeSSE for event, err := range r.Run(ctx, userID, session.ID(), userMsg, agent.RunConfig{ StreamingMode: streamingMode, }) { if err != nil { fmt.Printf("\nAGENT_ERROR: %v\n", err) } else { if event.LLMResponse.Content != nil { for _, p := range event.LLMResponse.Content.Parts { // if its running in streaming mode, don't print the non partial llmResponses if streamingMode != agent.StreamingModeSSE || event.LLMResponse.Partial { fmt.Print(p.Text) } } } } } fmt.Println("\n" + strings.Repeat("-", 80) + "\n") } } 4. Ensure all dependencies are installed: go mod tidy 5. Run your agent, and observe the results: go run hotelagent.go Info For more information, visit the [Go SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-go) . Last modified February 25, 2026: [doc: Fix ADK quickstart rendering with shortcodes (#2541) (182d63c7a08)](https://github.com/googleapis/genai-toolbox/commit/182d63c7a080de7f673ad4364ddfde863405c6cb) --- # Quickstart (MCP) | MCP Toolbox for Databases Quickstart (MCP) ================ How to get started running Toolbox locally with MCP Inspector. Overview -------- [Model Context Protocol](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to LLMs. Check out this page on how to [connect to Toolbox via MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect_via_mcp/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be access by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the [Tools](https://mcp-toolbox.dev/v0.25.0/resources/tools/) section. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Step 3: Connect to MCP Inspector -------------------------------- 1. Run the MCP Inspector: npx @modelcontextprotocol/inspector 2. Type `y` when it asks to install the inspector package. 3. It should show the following when the MCP Inspector is up and running (please take note of ``): Starting MCP inspector... ⚙️ Proxy server listening on localhost:6277 🔑 Session token: Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth 🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN= 4. Open the above link in your browser. 5. For `Transport Type`, select `Streamable HTTP`. 6. For `URL`, type in `http://127.0.0.1:5000/mcp`. 7. For `Configuration` -> `Proxy Session Token`, make sure `` is present. 8. Click Connect. ![inspector](https://mcp-toolbox.dev/v0.25.0/getting-started/mcp_quickstart/inspector.png) 9. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. ![inspector_tools](https://mcp-toolbox.dev/v0.25.0/getting-started/mcp_quickstart/inspector_tools.png) 10. Test out your tools here! Last modified January 8, 2026: [chore(main): release 0.25.0 (#2218) (41b518b955a)](https://github.com/googleapis/genai-toolbox/commit/41b518b955af8710c5b9b1aacddcfab63ff505bd) --- # Prompts using Gemini CLI | MCP Toolbox for Databases Prompts using Gemini CLI ======================== How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create the required tables using the following commands: CREATE TABLE users ( id SERIAL PRIMARY KEY, username VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE restaurants ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, location VARCHAR(100) ); CREATE TABLE reviews ( id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id), restaurant_id INT REFERENCES restaurants(id), rating INT CHECK (rating >= 1 AND rating <= 5), review_text TEXT, is_published BOOLEAN DEFAULT false, moderation_status VARCHAR(50) DEFAULT 'pending_manual_review', created_at TIMESTAMPTZ DEFAULT NOW() ); 6. Insert dummy data into the tables. INSERT INTO users (id, username, email) VALUES (123, 'jane_d', '[email protected]'), (124, 'john_s', '[email protected]'), (125, 'sam_b', '[email protected]'); INSERT INTO restaurants (id, name, location) VALUES (455, 'Pizza Palace', '123 Main St'), (456, 'The Corner Bistro', '456 Oak Ave'), (457, 'Sushi Spot', '789 Pine Ln'); INSERT INTO reviews (user_id, restaurant_id, rating, review_text, is_published, moderation_status) VALUES (124, 455, 5, 'Best pizza in town! The crust was perfect.', true, 'approved'), (125, 457, 4, 'Great sushi, very fresh. A bit pricey but worth it.', true, 'approved'), (123, 457, 5, 'Absolutely loved the dragon roll. Will be back!', true, 'approved'), (123, 456, 4, 'The atmosphere was lovely and the food was great. My photo upload might have been weird though.', false, 'pending_manual_review'), (125, 456, 1, 'This review contains inappropriate language.', false, 'rejected'); 7. End the database session: \q Step 2: Configure Toolbox ------------------------- Create a file named `tools.yaml`. This file defines the database connection, the SQL tools available, and the prompts the agents will use. kind: sources name: my-foodiefind-db type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: find_user_by_email type: postgres-sql source: my-foodiefind-db description: Find a user's ID by their email address. parameters: - name: email type: string description: The email address of the user to find. statement: SELECT id FROM users WHERE email = $1; --- kind: tools name: find_restaurant_by_name type: postgres-sql source: my-foodiefind-db description: Find a restaurant's ID by its exact name. parameters: - name: name type: string description: The name of the restaurant to find. statement: SELECT id FROM restaurants WHERE name = $1; --- kind: tools name: find_review_by_user_and_restaurant type: postgres-sql source: my-foodiefind-db description: Find the full record for a specific review using the user's ID and the restaurant's ID. parameters: - name: user_id type: integer description: The numerical ID of the user. - name: restaurant_id type: integer description: The numerical ID of the restaurant. statement: SELECT * FROM reviews WHERE user_id = $1 AND restaurant_id = $2; --- kind: prompts name: investigate_missing_review description: "Investigates a user's missing review by finding the user, restaurant, and the review itself, then analyzing its status." arguments: - name: "user_email" description: "The email of the user who wrote the review." - name: "restaurant_name" description: "The name of the restaurant being reviewed." messages: - content: >- **Goal:** Find the review written by the user with email '{{.user_email}}' for the restaurant named '{{.restaurant_name}}' and understand its status. **Workflow:** 1. Use the `find_user_by_email` tool with the email '{{.user_email}}' to get the `user_id`. 2. Use the `find_restaurant_by_name` tool with the name '{{.restaurant_name}}' to get the `restaurant_id`. 3. Use the `find_review_by_user_and_restaurant` tool with the `user_id` and `restaurant_id` you just found. 4. Analyze the results from the final tool call. Examine the `is_published` and `moderation_status` fields and explain the review's status to the user in a clear, human-readable sentence. Step 3: Connect to Gemini CLI ----------------------------- Configure the Gemini CLI to talk to your local Toolbox MCP server. 1. Open or create your Gemini settings file: `~/.gemini/settings.json`. 2. Add the following configuration to the file: { "mcpServers": { "MCPToolbox": { "httpUrl": "http://localhost:5000/mcp" } }, "mcp": { "allowed": ["MCPToolbox"] } } 3. Start Gemini CLI using gemini In case Gemini CLI is already running, use `/mcp refresh` to refresh the MCP server. 4. Use gemini slash commands to run your prompt: /investigate_missing_review --user_email="[email protected]" --restaurant_name="The Corner Bistro" Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Configuration | MCP Toolbox for Databases Configuration ============= How to configure Toolbox’s tools.yaml file. The primary way to configure Toolbox is through the `tools.yaml` file. If you have multiple files, you can tell toolbox which to load with the `--tools-file tools.yaml` flag. You can find more detailed reference documentation to all resource types in the [Resources](https://mcp-toolbox.dev/v0.24.0/resources/) . ### Using Environment Variables To avoid hardcoding certain secret fields like passwords, usernames, API keys etc., you could use environment variables instead with the format `${ENV_NAME}`. user: ${USER_NAME} password: ${PASSWORD} A default value can be specified like `${ENV_NAME:default}`. port: ${DB_PORT:3306} ### Sources The `sources` section of your `tools.yaml` defines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} For more details on configuring different types of sources, see the [Sources](https://mcp-toolbox.dev/v0.24.0/resources/sources/) . ### Tools The `tools` section of your `tools.yaml` defines the actions your agent can take: what kind of tool it is, which source(s) it affects, what parameters it uses, etc. tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; For more details on configuring different types of tools, see the [Tools](https://mcp-toolbox.dev/v0.24.0/resources/tools/) . ### Toolsets The `toolsets` section of your `tools.yaml` allows you to define groups of tools that you want to be able to load together. This can be useful for defining different sets for different agents or different applications. toolsets: my_first_toolset: - my_first_tool - my_second_tool my_second_toolset: - my_second_tool - my_third_tool You can load toolsets by name: # This will load all tools all_tools = client.load_toolset() # This will only load the tools listed in 'my_second_toolset' my_second_toolset = client.load_toolset("my_second_toolset") ### Prompts The `prompts` section of your `tools.yaml` defines the templates containing structured messages and instructions for interacting with language models. prompts: code_review: description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review" For more details on configuring different types of prompts, see the [Prompts](https://mcp-toolbox.dev/v0.24.0/resources/prompts/) . Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Configuration | MCP Toolbox for Databases Configuration ============= How to configure Toolbox’s tools.yaml file. The primary way to configure Toolbox is through the `tools.yaml` file. If you have multiple files, you can tell toolbox which to load with the `--tools-file tools.yaml` flag. You can find more detailed reference documentation to all resource types in the [Resources](https://mcp-toolbox.dev/v0.25.0/resources/) . ### Using Environment Variables To avoid hardcoding certain secret fields like passwords, usernames, API keys etc., you could use environment variables instead with the format `${ENV_NAME}`. user: ${USER_NAME} password: ${PASSWORD} A default value can be specified like `${ENV_NAME:default}`. port: ${DB_PORT:3306} ### Sources The `sources` section of your `tools.yaml` defines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} For more details on configuring different types of sources, see the [Sources](https://mcp-toolbox.dev/v0.25.0/resources/sources/) . ### Tools The `tools` section of your `tools.yaml` defines the actions your agent can take: what kind of tool it is, which source(s) it affects, what parameters it uses, etc. tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; For more details on configuring different types of tools, see the [Tools](https://mcp-toolbox.dev/v0.25.0/resources/tools/) . ### Toolsets The `toolsets` section of your `tools.yaml` allows you to define groups of tools that you want to be able to load together. This can be useful for defining different sets for different agents or different applications. toolsets: my_first_toolset: - my_first_tool - my_second_tool my_second_toolset: - my_second_tool - my_third_tool You can load toolsets by name: # This will load all tools all_tools = client.load_toolset() # This will only load the tools listed in 'my_second_toolset' my_second_toolset = client.load_toolset("my_second_toolset") ### Prompts The `prompts` section of your `tools.yaml` defines the templates containing structured messages and instructions for interacting with language models. prompts: code_review: description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review" For more details on configuring different types of prompts, see the [Prompts](https://mcp-toolbox.dev/v0.25.0/resources/prompts/) . Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # JS Quickstart (Local) | MCP Toolbox for Databases JS Quickstart (Local) ===================== How to get started running MCP Toolbox locally with [JavaScript](https://github.com/googleapis/mcp-toolbox-sdk-js) , PostgreSQL, and orchestration frameworks such as [LangChain](https://js.langchain.com/docs/introduction/) , [GenkitJS](https://genkit.dev/docs/get-started/) , [LlamaIndex](https://ts.llamaindex.ai/) and [GoogleGenAI](https://github.com/googleapis/js-genai) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Node.js (v18 or higher)](https://nodejs.org/) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. 1. (Optional) Initialize a Node.js project: npm init -y 2. In a new terminal, install the SDK package. * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/core npm install @toolbox-sdk/adk 3. Install other required dependencies * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK npm install langchain @langchain/google-genai npm install genkit @genkit-ai/googleai npm install llamaindex @llamaindex/google @llamaindex/workflow npm install @google/genai npm install @google/adk 4. Create a new file named `hotelAgent.js` and copy the following code to create an agent: * LangChain * GenkitJS * LlamaIndex * GoogleGenAI * ADK import { ChatGoogleGenerativeAI } from "@langchain/google-genai"; import { ToolboxClient } from "@toolbox-sdk/core"; import { tool } from "@langchain/core/tools"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { MemorySaver } from "@langchain/langgraph"; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const model = new ChatGoogleGenerativeAI({ model: "gemini-2.0-flash", }); const client = new ToolboxClient("http://127.0.0.1:5000"); const toolboxTools = await client.loadToolset("my-toolset"); // Define the basics of the tool: name, description, schema and core logic const getTool = (toolboxTool) => tool(toolboxTool, { name: toolboxTool.getName(), description: toolboxTool.getDescription(), schema: toolboxTool.getParamSchema() }); const tools = toolboxTools.map(getTool); const agent = createReactAgent({ llm: model, tools: tools, checkpointer: new MemorySaver(), systemPrompt: prompt, }); const langGraphConfig = { configurable: { thread_id: "test-thread", }, }; for (const query of queries) { const agentOutput = await agent.invoke( { messages: [\ {\ role: "user",\ content: query,\ },\ ], verbose: true, }, langGraphConfig ); const response = agentOutput.messages[agentOutput.messages.length - 1].content; console.log(response); } } main(); import { ToolboxClient } from "@toolbox-sdk/core"; import { genkit } from "genkit"; import { googleAI } from '@genkit-ai/googleai'; const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { const toolboxClient = new ToolboxClient("http://127.0.0.1:5000"); const ai = genkit({ plugins: [\ googleAI({\ apiKey: process.env.GEMINI_API_KEY || GOOGLE_API_KEY\ })\ ], model: googleAI.model('gemini-2.0-flash'), }); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const toolMap = Object.fromEntries( toolboxTools.map((tool) => { const definedTool = ai.defineTool( { name: tool.getName(), description: tool.getDescription(), inputSchema: tool.getParamSchema(), }, tool ); return [tool.getName(), definedTool]; }) ); const tools = Object.values(toolMap); let conversationHistory = [{ role: "system", content: [{ text: systemPrompt }] }]; for (const query of queries) { conversationHistory.push({ role: "user", content: [{ text: query }] }); let response = await ai.generate({ messages: conversationHistory, tools: tools, }); conversationHistory.push(response.message); const toolRequests = response.toolRequests; if (toolRequests?.length > 0) { // Execute tools concurrently and collect their responses. const toolResponses = await Promise.all( toolRequests.map(async (call) => { try { const toolOutput = await toolMap[call.name].invoke(call.input); return { role: "tool", content: [{ toolResponse: { name: call.name, output: toolOutput } }] }; } catch (e) { console.error(`Error executing tool ${call.name}:`, e); return { role: "tool", content: [{ toolResponse: { name: call.name, output: { error: e.message } } }] }; } }) ); conversationHistory.push(...toolResponses); // Call the AI again with the tool results. response = await ai.generate({ messages: conversationHistory, tools }); conversationHistory.push(response.message); } console.log(response.text); } } main(); import { gemini, GEMINI_MODEL } from "@llamaindex/google"; import { agent } from "@llamaindex/workflow"; import { createMemory, staticBlock, tool } from "llamaindex"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches — this is very important for operations. For any bookings or cancellations, please provide the appropriate confirmation. Update check-in or check-out dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; export async function main() { // Connect to MCP Toolbox const client = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await client.loadToolset("my-toolset"); const tools = toolboxTools.map((toolboxTool) => { return tool({ name: toolboxTool.getName(), description: toolboxTool.getDescription(), parameters: toolboxTool.getParamSchema(), execute: toolboxTool, }); }); // Initialize LLM const llm = gemini({ model: GEMINI_MODEL.GEMINI_2_0_FLASH, apiKey: GOOGLE_API_KEY, }); const memory = createMemory({ memoryBlocks: [\ staticBlock({\ content: prompt,\ }),\ ], }); // Create the Agent const myAgent = agent({ tools: tools, llm, memory, systemPrompt: prompt, }); for (const query of queries) { const result = await myAgent.run(query); const output = result.data.result; console.log(`\nUser: ${query}`); if (typeof output === "string") { console.log(output.trim()); } else if (typeof output === "object" && "text" in output) { console.log(output.text.trim()); } else { console.log(JSON.stringify(output)); } } //You may observe some extra logs during execution due to the run method provided by Llama. console.log("Agent run finished."); } main(); import { GoogleGenAI } from "@google/genai"; import { ToolboxClient } from "@toolbox-sdk/core"; const TOOLBOX_URL = "http://127.0.0.1:5000"; // Update if needed const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, you MUST use the available tools to find information. Mention its name, id, location and price tier. Always mention hotel id while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels in Basel with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; function mapZodTypeToOpenAPIType(zodTypeName) { const typeMap = { 'ZodString': 'string', 'ZodNumber': 'number', 'ZodBoolean': 'boolean', 'ZodArray': 'array', 'ZodObject': 'object', }; return typeMap[zodTypeName] || 'string'; } export async function main() { const toolboxClient = new ToolboxClient(TOOLBOX_URL); const toolboxTools = await toolboxClient.loadToolset("my-toolset"); const geminiTools = [{\ functionDeclarations: toolboxTools.map(tool => {\ \ const schema = tool.getParamSchema();\ const properties = {};\ const required = [];\ \ \ for (const [key, param] of Object.entries(schema.shape)) {\ properties[key] = {\ type: mapZodTypeToOpenAPIType(param.constructor.name),\ description: param.description || '',\ };\ required.push(key)\ }\ \ return {\ name: tool.getName(),\ description: tool.getDescription(),\ parameters: { type: 'object', properties, required },\ };\ })\ }]; const genAI = new GoogleGenAI({ apiKey: GOOGLE_API_KEY }); const chat = genAI.chats.create({ model: "gemini-2.5-flash", config: { systemInstruction: prompt, tools: geminiTools, } }); for (const query of queries) { let currentResult = await chat.sendMessage({ message: query }); let finalResponseGiven = false while (!finalResponseGiven) { const response = currentResult; const functionCalls = response.functionCalls || []; if (functionCalls.length === 0) { console.log(response.text) finalResponseGiven = true; } else { const toolResponses = []; for (const call of functionCalls) { const toolName = call.name const toolToExecute = toolboxTools.find(t => t.getName() === toolName); if (toolToExecute) { try { const functionResult = await toolToExecute(call.args); toolResponses.push({ functionResponse: { name: call.name, response: { result: functionResult } } }); } catch (e) { console.error(`Error executing tool '${toolName}':`, e); toolResponses.push({ functionResponse: { name: call.name, response: { error: e.message } } }); } } } currentResult = await chat.sendMessage({ message: toolResponses }); } } } } main(); import { InMemoryRunner, LlmAgent, LogLevel } from '@google/adk'; import { ToolboxClient } from '@toolbox-sdk/adk'; const prompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. `; const queries = [\ "Find hotels with Basel in its name.",\ "Can you book the Hilton Basel for me?",\ "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",\ "My check in dates would be from April 10, 2024 to April 19, 2024.",\ ]; process.env.GOOGLE_GENAI_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key export async function main() { const userId = 'test_user'; const client = new ToolboxClient('http://127.0.0.1:5000'); const tools = await client.loadToolset("my-toolset"); const rootAgent = new LlmAgent({ name: 'hotel_agent', model: 'gemini-2.5-flash', description: 'Agent for hotel bookings and administration.', instruction: prompt, tools: tools, }); const appName = rootAgent.name; const runner = new InMemoryRunner({ agent: rootAgent, appName, logLevel: LogLevel.ERROR, }); const session = await runner.sessionService.createSession({ appName, userId }); for (const query of queries) { await runPrompt(runner, userId, session.id, query); } } async function runPrompt(runner, userId, sessionId, prompt) { const content = { role: 'user', parts: [{ text: prompt }] }; const stream = runner.runAsync({ userId, sessionId, newMessage: content }); const responses = []; for await (const response of stream) { responses.push(response); } const accumulatedResponse = responses .flatMap((e) => e.content?.parts?.map((p) => p.text) ?? []) .join(''); console.log(`\nMODEL RESPONSE: ${accumulatedResponse}\n`); } main(); 5. Run your agent, and observe the results: node hotelAgent.js Info For more information, visit the [JS SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-js) . Last modified February 18, 2026: [docs: make branding consistent across quickstart docs (#2498) (e84a51b660c)](https://github.com/googleapis/genai-toolbox/commit/e84a51b660c36242e89ae8a2259a7e9ee927c673) --- # Quickstart (MCP) | MCP Toolbox for Databases Quickstart (MCP) ================ How to get started running Toolbox locally with MCP Inspector. Overview -------- [Model Context Protocol](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to LLMs. Check out this page on how to [connect to Toolbox via MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect_via_mcp/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be access by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; search-hotels-by-location: kind: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; book-hotel: kind: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; update-hotel: kind: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; cancel-hotel: kind: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; toolsets: my-toolset: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the [Tools](https://mcp-toolbox.dev/v0.26.0/resources/tools/) section. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Step 3: Connect to MCP Inspector -------------------------------- 1. Run the MCP Inspector: npx @modelcontextprotocol/inspector 2. Type `y` when it asks to install the inspector package. 3. It should show the following when the MCP Inspector is up and running (please take note of ``): Starting MCP inspector... ⚙️ Proxy server listening on localhost:6277 🔑 Session token: Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth 🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN= 4. Open the above link in your browser. 5. For `Transport Type`, select `Streamable HTTP`. 6. For `URL`, type in `http://127.0.0.1:5000/mcp`. 7. For `Configuration` -> `Proxy Session Token`, make sure `` is present. 8. Click Connect. ![inspector](https://mcp-toolbox.dev/v0.26.0/getting-started/mcp_quickstart/inspector.png) 9. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. ![inspector_tools](https://mcp-toolbox.dev/v0.26.0/getting-started/mcp_quickstart/inspector_tools.png) 10. Test out your tools here! Last modified January 22, 2026: [chore(main): release 0.26.0 (#2286) (86bf7bf8d06)](https://github.com/googleapis/genai-toolbox/commit/86bf7bf8d068f00adccd7223dd113743aed83ab5) --- # Quickstart (MCP) | MCP Toolbox for Databases Quickstart (MCP) ================ How to get started running Toolbox locally with MCP Inspector. Overview -------- [Model Context Protocol](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to LLMs. Check out this page on how to [connect to Toolbox via MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect_via_mcp/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be access by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the [Tools](https://mcp-toolbox.dev/v0.27.0/resources/tools/) section. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Step 3: Connect to MCP Inspector -------------------------------- 1. Run the MCP Inspector: npx @modelcontextprotocol/inspector 2. Type `y` when it asks to install the inspector package. 3. It should show the following when the MCP Inspector is up and running (please take note of ``): Starting MCP inspector... ⚙️ Proxy server listening on localhost:6277 🔑 Session token: Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth 🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN= 4. Open the above link in your browser. 5. For `Transport Type`, select `Streamable HTTP`. 6. For `URL`, type in `http://127.0.0.1:5000/mcp`. 7. For `Configuration` -> `Proxy Session Token`, make sure `` is present. 8. Click Connect. ![inspector](https://mcp-toolbox.dev/v0.27.0/getting-started/mcp_quickstart/inspector.png) 9. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. ![inspector_tools](https://mcp-toolbox.dev/v0.27.0/getting-started/mcp_quickstart/inspector_tools.png) 10. Test out your tools here! Last modified February 12, 2026: [chore(main): release 0.27.0 (#2363) (c5524d32f58)](https://github.com/googleapis/genai-toolbox/commit/c5524d32f580fed81c8b90448e2f17e719710ff9) --- # Prompts using Gemini CLI | MCP Toolbox for Databases Prompts using Gemini CLI ======================== How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create the required tables using the following commands: CREATE TABLE users ( id SERIAL PRIMARY KEY, username VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE restaurants ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, location VARCHAR(100) ); CREATE TABLE reviews ( id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id), restaurant_id INT REFERENCES restaurants(id), rating INT CHECK (rating >= 1 AND rating <= 5), review_text TEXT, is_published BOOLEAN DEFAULT false, moderation_status VARCHAR(50) DEFAULT 'pending_manual_review', created_at TIMESTAMPTZ DEFAULT NOW() ); 6. Insert dummy data into the tables. INSERT INTO users (id, username, email) VALUES (123, 'jane_d', '[email protected]'), (124, 'john_s', '[email protected]'), (125, 'sam_b', '[email protected]'); INSERT INTO restaurants (id, name, location) VALUES (455, 'Pizza Palace', '123 Main St'), (456, 'The Corner Bistro', '456 Oak Ave'), (457, 'Sushi Spot', '789 Pine Ln'); INSERT INTO reviews (user_id, restaurant_id, rating, review_text, is_published, moderation_status) VALUES (124, 455, 5, 'Best pizza in town! The crust was perfect.', true, 'approved'), (125, 457, 4, 'Great sushi, very fresh. A bit pricey but worth it.', true, 'approved'), (123, 457, 5, 'Absolutely loved the dragon roll. Will be back!', true, 'approved'), (123, 456, 4, 'The atmosphere was lovely and the food was great. My photo upload might have been weird though.', false, 'pending_manual_review'), (125, 456, 1, 'This review contains inappropriate language.', false, 'rejected'); 7. End the database session: \q Step 2: Configure Toolbox ------------------------- Create a file named `tools.yaml`. This file defines the database connection, the SQL tools available, and the prompts the agents will use. kind: sources name: my-foodiefind-db type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: find_user_by_email type: postgres-sql source: my-foodiefind-db description: Find a user's ID by their email address. parameters: - name: email type: string description: The email address of the user to find. statement: SELECT id FROM users WHERE email = $1; --- kind: tools name: find_restaurant_by_name type: postgres-sql source: my-foodiefind-db description: Find a restaurant's ID by its exact name. parameters: - name: name type: string description: The name of the restaurant to find. statement: SELECT id FROM restaurants WHERE name = $1; --- kind: tools name: find_review_by_user_and_restaurant type: postgres-sql source: my-foodiefind-db description: Find the full record for a specific review using the user's ID and the restaurant's ID. parameters: - name: user_id type: integer description: The numerical ID of the user. - name: restaurant_id type: integer description: The numerical ID of the restaurant. statement: SELECT * FROM reviews WHERE user_id = $1 AND restaurant_id = $2; --- kind: prompts name: investigate_missing_review description: "Investigates a user's missing review by finding the user, restaurant, and the review itself, then analyzing its status." arguments: - name: "user_email" description: "The email of the user who wrote the review." - name: "restaurant_name" description: "The name of the restaurant being reviewed." messages: - content: >- **Goal:** Find the review written by the user with email '{{.user_email}}' for the restaurant named '{{.restaurant_name}}' and understand its status. **Workflow:** 1. Use the `find_user_by_email` tool with the email '{{.user_email}}' to get the `user_id`. 2. Use the `find_restaurant_by_name` tool with the name '{{.restaurant_name}}' to get the `restaurant_id`. 3. Use the `find_review_by_user_and_restaurant` tool with the `user_id` and `restaurant_id` you just found. 4. Analyze the results from the final tool call. Examine the `is_published` and `moderation_status` fields and explain the review's status to the user in a clear, human-readable sentence. Step 3: Connect to Gemini CLI ----------------------------- Configure the Gemini CLI to talk to your local Toolbox MCP server. 1. Open or create your Gemini settings file: `~/.gemini/settings.json`. 2. Add the following configuration to the file: { "mcpServers": { "MCPToolbox": { "httpUrl": "http://localhost:5000/mcp" } }, "mcp": { "allowed": ["MCPToolbox"] } } 3. Start Gemini CLI using gemini In case Gemini CLI is already running, use `/mcp refresh` to refresh the MCP server. 4. Use gemini slash commands to run your prompt: /investigate_missing_review --user_email="[email protected]" --restaurant_name="The Corner Bistro" Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Configuration | MCP Toolbox for Databases Configuration ============= How to configure Toolbox’s tools.yaml file. The primary way to configure Toolbox is through the `tools.yaml` file. If you have multiple files, you can tell toolbox which to load with the `--tools-file tools.yaml` flag. You can find more detailed reference documentation to all resource types in the [Resources](https://mcp-toolbox.dev/v0.26.0/resources/) . ### Using Environment Variables To avoid hardcoding certain secret fields like passwords, usernames, API keys etc., you could use environment variables instead with the format `${ENV_NAME}`. user: ${USER_NAME} password: ${PASSWORD} A default value can be specified like `${ENV_NAME:default}`. port: ${DB_PORT:3306} ### Sources The `sources` section of your `tools.yaml` defines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against. sources: my-pg-source: kind: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} For more details on configuring different types of sources, see the [Sources](https://mcp-toolbox.dev/v0.26.0/resources/sources/) . ### Tools The `tools` section of your `tools.yaml` defines the actions your agent can take: what kind of tool it is, which source(s) it affects, what parameters it uses, etc. tools: search-hotels-by-name: kind: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; For more details on configuring different types of tools, see the [Tools](https://mcp-toolbox.dev/v0.26.0/resources/tools/) . ### Toolsets The `toolsets` section of your `tools.yaml` allows you to define groups of tools that you want to be able to load together. This can be useful for defining different sets for different agents or different applications. toolsets: my_first_toolset: - my_first_tool - my_second_tool my_second_toolset: - my_second_tool - my_third_tool You can load toolsets by name: # This will load all tools all_tools = client.load_toolset() # This will only load the tools listed in 'my_second_toolset' my_second_toolset = client.load_toolset("my_second_toolset") ### Prompts The `prompts` section of your `tools.yaml` defines the templates containing structured messages and instructions for interacting with language models. prompts: code_review: description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review" For more details on configuring different types of prompts, see the [Prompts](https://mcp-toolbox.dev/v0.26.0/resources/prompts/) . Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Concepts | MCP Toolbox for Databases Concepts ======== Some core concepts in Toolbox * * * ##### [Telemetry](https://mcp-toolbox.dev/v0.24.0/concepts/telemetry/) An overview of telemetry and observability in Toolbox. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Concepts | MCP Toolbox for Databases Concepts ======== Some core concepts in Toolbox * * * ##### [Telemetry](https://mcp-toolbox.dev/v0.25.0/concepts/telemetry/) An overview of telemetry and observability in Toolbox. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Prompts using Gemini CLI | MCP Toolbox for Databases Prompts using Gemini CLI ======================== How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create the required tables using the following commands: CREATE TABLE users ( id SERIAL PRIMARY KEY, username VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE restaurants ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, location VARCHAR(100) ); CREATE TABLE reviews ( id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id), restaurant_id INT REFERENCES restaurants(id), rating INT CHECK (rating >= 1 AND rating <= 5), review_text TEXT, is_published BOOLEAN DEFAULT false, moderation_status VARCHAR(50) DEFAULT 'pending_manual_review', created_at TIMESTAMPTZ DEFAULT NOW() ); 6. Insert dummy data into the tables. INSERT INTO users (id, username, email) VALUES (123, 'jane_d', '[email protected]'), (124, 'john_s', '[email protected]'), (125, 'sam_b', '[email protected]'); INSERT INTO restaurants (id, name, location) VALUES (455, 'Pizza Palace', '123 Main St'), (456, 'The Corner Bistro', '456 Oak Ave'), (457, 'Sushi Spot', '789 Pine Ln'); INSERT INTO reviews (user_id, restaurant_id, rating, review_text, is_published, moderation_status) VALUES (124, 455, 5, 'Best pizza in town! The crust was perfect.', true, 'approved'), (125, 457, 4, 'Great sushi, very fresh. A bit pricey but worth it.', true, 'approved'), (123, 457, 5, 'Absolutely loved the dragon roll. Will be back!', true, 'approved'), (123, 456, 4, 'The atmosphere was lovely and the food was great. My photo upload might have been weird though.', false, 'pending_manual_review'), (125, 456, 1, 'This review contains inappropriate language.', false, 'rejected'); 7. End the database session: \q Step 2: Configure Toolbox ------------------------- Create a file named `tools.yaml`. This file defines the database connection, the SQL tools available, and the prompts the agents will use. kind: sources name: my-foodiefind-db type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: find_user_by_email type: postgres-sql source: my-foodiefind-db description: Find a user's ID by their email address. parameters: - name: email type: string description: The email address of the user to find. statement: SELECT id FROM users WHERE email = $1; --- kind: tools name: find_restaurant_by_name type: postgres-sql source: my-foodiefind-db description: Find a restaurant's ID by its exact name. parameters: - name: name type: string description: The name of the restaurant to find. statement: SELECT id FROM restaurants WHERE name = $1; --- kind: tools name: find_review_by_user_and_restaurant type: postgres-sql source: my-foodiefind-db description: Find the full record for a specific review using the user's ID and the restaurant's ID. parameters: - name: user_id type: integer description: The numerical ID of the user. - name: restaurant_id type: integer description: The numerical ID of the restaurant. statement: SELECT * FROM reviews WHERE user_id = $1 AND restaurant_id = $2; --- kind: prompts name: investigate_missing_review description: "Investigates a user's missing review by finding the user, restaurant, and the review itself, then analyzing its status." arguments: - name: "user_email" description: "The email of the user who wrote the review." - name: "restaurant_name" description: "The name of the restaurant being reviewed." messages: - content: >- **Goal:** Find the review written by the user with email '{{.user_email}}' for the restaurant named '{{.restaurant_name}}' and understand its status. **Workflow:** 1. Use the `find_user_by_email` tool with the email '{{.user_email}}' to get the `user_id`. 2. Use the `find_restaurant_by_name` tool with the name '{{.restaurant_name}}' to get the `restaurant_id`. 3. Use the `find_review_by_user_and_restaurant` tool with the `user_id` and `restaurant_id` you just found. 4. Analyze the results from the final tool call. Examine the `is_published` and `moderation_status` fields and explain the review's status to the user in a clear, human-readable sentence. Step 3: Connect to Gemini CLI ----------------------------- Configure the Gemini CLI to talk to your local Toolbox MCP server. 1. Open or create your Gemini settings file: `~/.gemini/settings.json`. 2. Add the following configuration to the file: { "mcpServers": { "MCPToolbox": { "httpUrl": "http://localhost:5000/mcp" } }, "mcp": { "allowed": ["MCPToolbox"] } } 3. Start Gemini CLI using gemini In case Gemini CLI is already running, use `/mcp refresh` to refresh the MCP server. 4. Use gemini slash commands to run your prompt: /investigate_missing_review --user_email="[email protected]" --restaurant_name="The Corner Bistro" Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Go Quickstart (Local) | MCP Toolbox for Databases Go Quickstart (Local) ===================== How to get started running MCP Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Go (v1.24.2 or higher)](https://go.dev/doc/install) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. 1. Initialize a go module: go mod init main 2. In a new terminal, install the Go SDK Module: Warning Breaking Change Notice: As of version `0.6.0`, this SDK has transitioned to a multi-module structure. * For new versions (`v0.6.0`+): You must import specific modules (e.g., `go get github.com/googleapis/mcp-toolbox-sdk-go/core`). * For older versions (`v0.5.1` and below): The SDK remains a single-module library (`go get github.com/googleapis/mcp-toolbox-sdk-go`). * Please update your imports and `go.mod` accordingly when upgrading. * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/tbadk 3. Create a new file named `hotelagent.go` and copy the following code to create an agent: * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" "github.com/tmc/langchaingo/llms/googleai" ) // ConvertToLangchainTool converts a generic core.ToolboxTool into a LangChainGo llms.Tool. func ConvertToLangchainTool(toolboxTool *core.ToolboxTool) llms.Tool { // Fetch the tool's input schema inputschema, err := toolboxTool.InputSchema() if err != nil { return llms.Tool{} } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Convert into LangChain's llms.Tool return llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the Google AI client (LLM). llm, err := googleai.New(ctx, googleai.WithAPIKey(genaiKey), googleai.WithDefaultModel("gemini-2.0-flash")) if err != nil { log.Fatalf("Failed to create Google AI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } toolsMap := make(map[string]*core.ToolboxTool, len(tools)) langchainTools := make([]llms.Tool, len(tools)) // Convert the loaded ToolboxTools into the format LangChainGo requires. for i, tool := range tools { langchainTools[i] = ConvertToLangchainTool(tool) toolsMap[tool.Name()] = tool } // Start the conversation history. messageHistory := []llms.MessageContent{ llms.TextParts(llms.ChatMessageTypeSystem, systemPrompt), } for _, query := range queries { messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeHuman, query)) // Make the first call to the LLM, making it aware of the tool. resp, err := llm.GenerateContent(ctx, messageHistory, llms.WithTools(langchainTools)) if err != nil { log.Fatalf("LLM call failed: %v", err) } respChoice := resp.Choices[0] assistantResponse := llms.TextParts(llms.ChatMessageTypeAI, respChoice.Content) for _, tc := range respChoice.ToolCalls { assistantResponse.Parts = append(assistantResponse.Parts, tc) } messageHistory = append(messageHistory, assistantResponse) // Process each tool call requested by the model. for _, tc := range respChoice.ToolCalls { toolName := tc.FunctionCall.Name tool := toolsMap[toolName] var args map[string]any if err := json.Unmarshal([]byte(tc.FunctionCall.Arguments), &args); err != nil { log.Fatalf("Failed to unmarshal arguments for tool '%s': %v", toolName, err) } toolResult, err := tool.Invoke(ctx, args) if err != nil { log.Fatalf("Failed to execute tool '%s': %v", toolName, err) } if toolResult == "" || toolResult == nil { toolResult = "Operation completed successfully with no specific return value." } // Create the tool call response message and add it to the history. toolResponse := llms.MessageContent{ Role: llms.ChatMessageTypeTool, Parts: []llms.ContentPart{ llms.ToolCallResponse{ Name: toolName, Content: fmt.Sprintf("%v", toolResult), }, }, } messageHistory = append(messageHistory, toolResponse) } finalResp, err := llm.GenerateContent(ctx, messageHistory) if err != nil { log.Fatalf("Final LLM call failed after tool execution: %v", err) } // Add the final textual response from the LLM to the history messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeAI, finalResp.Choices[0].Content)) fmt.Println(finalResp.Choices[0].Content) } } package main import ( "context" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/firebase/genkit/go/plugins/googlegenai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { ctx := context.Background() // Create Toolbox Client toolboxClient, err := core.NewToolboxClient("http://127.0.0.1:5000") if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } // Initialize Genkit g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}), genkit.WithDefaultModel("googleai/gemini-2.0-flash"), ) if err != nil { log.Fatalf("Failed to init genkit: %v\n", err) } // Create a conversation history conversationHistory := []*ai.Message{ ai.NewSystemTextMessage(systemPrompt), } // Convert your tool to a Genkit tool. genkitTools := make([]ai.Tool, len(tools)) for i, tool := range tools { newTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } genkitTools[i] = newTool } toolRefs := make([]ai.ToolRef, len(genkitTools)) for i, tool := range genkitTools { toolRefs[i] = tool } for _, query := range queries { conversationHistory = append(conversationHistory, ai.NewUserTextMessage(query)) response, err := genkit.Generate(ctx, g, ai.WithMessages(conversationHistory...), ai.WithTools(toolRefs...), ai.WithReturnToolRequests(true), ) if err != nil { log.Fatalf("%v\n", err) } conversationHistory = append(conversationHistory, response.Message) parts := []*ai.Part{} for _, req := range response.ToolRequests() { tool := genkit.LookupTool(g, req.Name) if tool == nil { log.Fatalf("tool %q not found", req.Name) } output, err := tool.RunRaw(ctx, req.Input) if err != nil { log.Fatalf("tool %q execution failed: %v", tool.Name(), err) } parts = append(parts, ai.NewToolResponsePart(&ai.ToolResponse{ Name: req.Name, Ref: req.Ref, Output: output, })) } if len(parts) > 0 { resp, err := genkit.Generate(ctx, g, ai.WithMessages(append(response.History(), ai.NewMessage(ai.RoleTool, nil, parts...))...), ai.WithTools(toolRefs...), ) if err != nil { log.Fatal(err) } fmt.Println("\n", resp.Text()) conversationHistory = append(conversationHistory, resp.Message) } else { fmt.Println("\n", response.Text()) } } } package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) // ConvertToGenaiTool translates a ToolboxTool into the genai.FunctionDeclaration format. func ConvertToGenaiTool(toolboxTool *core.ToolboxTool) *genai.Tool { inputschema, err := toolboxTool.InputSchema() if err != nil { return &genai.Tool{} } var paramsSchema *genai.Schema _ = json.Unmarshal(inputschema, ¶msSchema) // First, create the function declaration. funcDeclaration := &genai.FunctionDeclaration{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, } // Then, wrap the function declaration in a genai.Tool struct. return &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } func printResponse(resp *genai.GenerateContentResponse) { for _, cand := range resp.Candidates { if cand.Content != nil { for _, part := range cand.Content.Parts { fmt.Println(part.Text) } } } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() apiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" // Initialize the Google GenAI client using the explicit ClientConfig. client, err := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: apiKey, }) if err != nil { log.Fatalf("Failed to create Google GenAI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } genAITools := make([]*genai.Tool, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { genAITools[i] = ConvertToGenaiTool(tool) toolsMap[tool.Name()] = tool } // Set up the generative model with the available tool. modelName := "gemini-2.0-flash" // Create the initial content prompt for the model. messageHistory := []*genai.Content{ genai.NewContentFromText(systemPrompt, genai.RoleUser), } config := &genai.GenerateContentConfig{ Tools: genAITools, ToolConfig: &genai.ToolConfig{ FunctionCallingConfig: &genai.FunctionCallingConfig{ Mode: genai.FunctionCallingConfigModeAny, }, }, } for _, query := range queries { messageHistory = append(messageHistory, genai.NewContentFromText(query, genai.RoleUser)) genContentResp, err := client.Models.GenerateContent(ctx, modelName, messageHistory, config) if err != nil { log.Fatalf("LLM call failed for query '%s': %v", query, err) } if len(genContentResp.Candidates) > 0 && genContentResp.Candidates[0].Content != nil { messageHistory = append(messageHistory, genContentResp.Candidates[0].Content) } functionCalls := genContentResp.FunctionCalls() toolResponseParts := []*genai.Part{} for _, fc := range functionCalls { toolToInvoke, found := toolsMap[fc.Name] if !found { log.Fatalf("Tool '%s' not found in loaded tools map. Check toolset configuration.", fc.Name) } toolResult, invokeErr := toolToInvoke.Invoke(ctx, fc.Args) if invokeErr != nil { log.Fatalf("Failed to execute tool '%s': %v", fc.Name, invokeErr) } // Enhanced Tool Result Handling (retained to prevent nil issues) toolResultString := "" if toolResult != nil { jsonBytes, marshalErr := json.Marshal(toolResult) if marshalErr == nil { toolResultString = string(jsonBytes) } else { toolResultString = fmt.Sprintf("%v", toolResult) } } responseMap := map[string]any{"result": toolResultString} toolResponseParts = append(toolResponseParts, genai.NewPartFromFunctionResponse(fc.Name, responseMap)) } // Add all accumulated tool responses for this turn to the message history. toolResponseContent := genai.NewContentFromParts(toolResponseParts, "function") messageHistory = append(messageHistory, toolResponseContent) finalResponse, err := client.Models.GenerateContent(ctx, modelName, messageHistory, &genai.GenerateContentConfig{}) if err != nil { log.Fatalf("Error calling GenerateContent (with function result): %v", err) } printResponse(finalResponse) // Add the final textual response from the LLM to the history if len(finalResponse.Candidates) > 0 && finalResponse.Candidates[0].Content != nil { messageHistory = append(messageHistory, finalResponse.Candidates[0].Content) } } } package main import ( "context" "encoding/json" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go/v3" ) // ConvertToOpenAITool converts a ToolboxTool into the go-openai library's Tool format. func ConvertToOpenAITool(toolboxTool *core.ToolboxTool) openai.ChatCompletionToolUnionParam { // Get the input schema jsonSchemaBytes, err := toolboxTool.InputSchema() if err != nil { return openai.ChatCompletionToolUnionParam{} } // Unmarshal the JSON bytes into FunctionParameters var paramsSchema openai.FunctionParameters if err := json.Unmarshal(jsonSchemaBytes, ¶msSchema); err != nil { return openai.ChatCompletionToolUnionParam{} } // Create and return the final tool parameter struct. return openai.ChatCompletionToolUnionParam{ OfFunction: &openai.ChatCompletionFunctionToolParam{ Function: openai.FunctionDefinitionParam{ Name: toolboxTool.Name(), Description: openai.String(toolboxTool.Description()), Parameters: paramsSchema, }, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() toolboxURL := "http://localhost:5000" openAIClient := openai.NewClient() // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tool : %v\nMake sure your Toolbox server is running and the tool is configured.", err) } openAITools := make([]openai.ChatCompletionToolUnionParam, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { // Convert the Toolbox tool into the openAI FunctionDeclaration format. openAITools[i] = ConvertToOpenAITool(tool) // Add tool to a map for lookup later toolsMap[tool.Name()] = tool } params := openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{ openai.SystemMessage(systemPrompt), }, Tools: openAITools, Seed: openai.Int(0), Model: openai.ChatModelGPT4o, } for _, query := range queries { params.Messages = append(params.Messages, openai.UserMessage(query)) // Make initial chat completion request completion, err := openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } toolCalls := completion.Choices[0].Message.ToolCalls // Return early if there are no tool calls if len(toolCalls) == 0 { log.Println("No function call") } // If there was a function call, continue the conversation params.Messages = append(params.Messages, completion.Choices[0].Message.ToParam()) for _, toolCall := range toolCalls { toolName := toolCall.Function.Name toolToInvoke := toolsMap[toolName] var args map[string]any err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args) if err != nil { panic(err) } result, err := toolToInvoke.Invoke(ctx, args) if err != nil { log.Fatal("Could not invoke tool", err) } params.Messages = append(params.Messages, openai.ToolMessage(result.(string), toolCall.ID)) } completion, err = openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } params.Messages = append(params.Messages, openai.AssistantMessage(query)) fmt.Println("\n", completion.Choices[0].Message.Content) } } package main import ( "context" "fmt" "log" "os" "strings" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/model/gemini" "google.golang.org/adk/runner" "google.golang.org/adk/session" "google.golang.org/adk/tool" "google.golang.org/genai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queriesAdk = []string{ "Find hotels in Basel. ", "Find hotels with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GEMINI_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the MCP Toolbox client. toolboxClient, err := tbadk.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create MCP Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. toolsetName := "my-toolset" mcpTools, err := toolboxClient.LoadToolset(toolsetName, ctx) if err != nil { log.Fatalf("Failed to load MCP toolset '%s': %v\nMake sure your Toolbox server is running.", toolsetName, err) } // Set up the Gemini Model model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{ APIKey: genaiKey, }) if err != nil { log.Fatalf("Failed to create model: %v", err) } // Type Cast the ToolboxTools tools := make([]tool.Tool, len(mcpTools)) for i := range mcpTools { tools[i] = &mcpTools[i] } // Create an llm agent llmagent, err := llmagent.New(llmagent.Config{ Name: "hotel_assistant", Model: model, Description: "Agent to answer questions about hotels.", Instruction: systemPrompt, Tools: tools, }) if err != nil { log.Fatalf("Failed to create agent: %v", err) } appName := "hotel_assistant" userID := "user-123" // Create a session service sessionService := session.InMemoryService() resp, err := sessionService.Create(ctx, &session.CreateRequest{ AppName: appName, UserID: userID, }) if err != nil { log.Fatalf("Failed to create the session service: %v", err) } session := resp.Session // Configure the runner r, err := runner.New(runner.Config{ AppName: appName, Agent: llmagent, SessionService: sessionService, }) if err != nil { log.Fatalf("Failed to create runner: %v", err) } // Loop through queries to the llm agent for i, query := range queriesAdk { fmt.Printf("\n=== Query %d: %s ===\n", i+1, query) userMsg := genai.NewContentFromText(query, genai.RoleUser) streamingMode := agent.StreamingModeSSE for event, err := range r.Run(ctx, userID, session.ID(), userMsg, agent.RunConfig{ StreamingMode: streamingMode, }) { if err != nil { fmt.Printf("\nAGENT_ERROR: %v\n", err) } else { if event.LLMResponse.Content != nil { for _, p := range event.LLMResponse.Content.Parts { // if its running in streaming mode, don't print the non partial llmResponses if streamingMode != agent.StreamingModeSSE || event.LLMResponse.Partial { fmt.Print(p.Text) } } } } } fmt.Println("\n" + strings.Repeat("-", 80) + "\n") } } 4. Ensure all dependencies are installed: go mod tidy 5. Run your agent, and observe the results: go run hotelagent.go Info For more information, visit the [Go SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-go) . Last modified February 25, 2026: [doc: Fix ADK quickstart rendering with shortcodes (#2541) (182d63c7a08)](https://github.com/googleapis/genai-toolbox/commit/182d63c7a080de7f673ad4364ddfde863405c6cb) --- # Quickstart (MCP) | MCP Toolbox for Databases Quickstart (MCP) ================ How to get started running Toolbox locally with MCP Inspector. Overview -------- [Model Context Protocol](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to LLMs. Check out this page on how to [connect to Toolbox via MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect_via_mcp/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be access by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the [Tools](https://mcp-toolbox.dev/v0.28.0/resources/tools/) section. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Step 3: Connect to MCP Inspector -------------------------------- 1. Run the MCP Inspector: npx @modelcontextprotocol/inspector 2. Type `y` when it asks to install the inspector package. 3. It should show the following when the MCP Inspector is up and running (please take note of ``): Starting MCP inspector... ⚙️ Proxy server listening on localhost:6277 🔑 Session token: Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth 🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN= 4. Open the above link in your browser. 5. For `Transport Type`, select `Streamable HTTP`. 6. For `URL`, type in `http://127.0.0.1:5000/mcp`. 7. For `Configuration` -> `Proxy Session Token`, make sure `` is present. 8. Click Connect. ![inspector](https://mcp-toolbox.dev/v0.28.0/getting-started/mcp_quickstart/inspector.png) 9. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. ![inspector_tools](https://mcp-toolbox.dev/v0.28.0/getting-started/mcp_quickstart/inspector_tools.png) 10. Test out your tools here! Last modified March 2, 2026: [chore(main): release 0.28.0 (#2472) (81253a0bd70)](https://github.com/googleapis/genai-toolbox/commit/81253a0bd7049a2e2681ef13631a768cb402040e) --- # Go Quickstart (Local) | MCP Toolbox for Databases Go Quickstart (Local) ===================== How to get started running MCP Toolbox locally with [Go](https://github.com/googleapis/mcp-toolbox-sdk-go) , PostgreSQL, and orchestration frameworks such as [LangChain Go](https://tmc.github.io/langchaingo/docs/) , [GenkitGo](https://genkit.dev/go/docs/get-started-go/) , [Go GenAI](https://github.com/googleapis/go-genai) and [OpenAI Go](https://github.com/openai/openai-go) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [Go (v1.24.2 or higher)](https://go.dev/doc/install) . 2. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . ### Cloud Setup (Optional) If you plan to use **Google Cloud’s Vertex AI** with your agent (e.g., using `vertexai=True` or a Google GenAI model), follow these one-time setup steps for local development: 1. [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 2. [Set up Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) 3. Set your project and enable Vertex AI gcloud config set project YOUR_PROJECT_ID gcloud services enable aiplatform.googleapis.com Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure MCP Toolbox ----------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the `Resources` section of the docs. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. Step 3: Connect your agent to MCP Toolbox ----------------------------------------- In this section, we will write and run an agent that will load the Tools from MCP Toolbox. 1. Initialize a go module: go mod init main 2. In a new terminal, install the Go SDK Module: Warning Breaking Change Notice: As of version `0.6.0`, this SDK has transitioned to a multi-module structure. * For new versions (`v0.6.0`+): You must import specific modules (e.g., `go get github.com/googleapis/mcp-toolbox-sdk-go/core`). * For older versions (`v0.5.1` and below): The SDK remains a single-module library (`go get github.com/googleapis/mcp-toolbox-sdk-go`). * Please update your imports and `go.mod` accordingly when upgrading. * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/core go get github.com/googleapis/mcp-toolbox-sdk-go/tbadk 3. Create a new file named `hotelagent.go` and copy the following code to create an agent: * LangChain Go * Genkit Go * Go GenAI * OpenAI Go * ADK Go package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/tmc/langchaingo/llms" "github.com/tmc/langchaingo/llms/googleai" ) // ConvertToLangchainTool converts a generic core.ToolboxTool into a LangChainGo llms.Tool. func ConvertToLangchainTool(toolboxTool *core.ToolboxTool) llms.Tool { // Fetch the tool's input schema inputschema, err := toolboxTool.InputSchema() if err != nil { return llms.Tool{} } var paramsSchema map[string]any _ = json.Unmarshal(inputschema, ¶msSchema) // Convert into LangChain's llms.Tool return llms.Tool{ Type: "function", Function: &llms.FunctionDefinition{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the Google AI client (LLM). llm, err := googleai.New(ctx, googleai.WithAPIKey(genaiKey), googleai.WithDefaultModel("gemini-2.0-flash")) if err != nil { log.Fatalf("Failed to create Google AI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } toolsMap := make(map[string]*core.ToolboxTool, len(tools)) langchainTools := make([]llms.Tool, len(tools)) // Convert the loaded ToolboxTools into the format LangChainGo requires. for i, tool := range tools { langchainTools[i] = ConvertToLangchainTool(tool) toolsMap[tool.Name()] = tool } // Start the conversation history. messageHistory := []llms.MessageContent{ llms.TextParts(llms.ChatMessageTypeSystem, systemPrompt), } for _, query := range queries { messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeHuman, query)) // Make the first call to the LLM, making it aware of the tool. resp, err := llm.GenerateContent(ctx, messageHistory, llms.WithTools(langchainTools)) if err != nil { log.Fatalf("LLM call failed: %v", err) } respChoice := resp.Choices[0] assistantResponse := llms.TextParts(llms.ChatMessageTypeAI, respChoice.Content) for _, tc := range respChoice.ToolCalls { assistantResponse.Parts = append(assistantResponse.Parts, tc) } messageHistory = append(messageHistory, assistantResponse) // Process each tool call requested by the model. for _, tc := range respChoice.ToolCalls { toolName := tc.FunctionCall.Name tool := toolsMap[toolName] var args map[string]any if err := json.Unmarshal([]byte(tc.FunctionCall.Arguments), &args); err != nil { log.Fatalf("Failed to unmarshal arguments for tool '%s': %v", toolName, err) } toolResult, err := tool.Invoke(ctx, args) if err != nil { log.Fatalf("Failed to execute tool '%s': %v", toolName, err) } if toolResult == "" || toolResult == nil { toolResult = "Operation completed successfully with no specific return value." } // Create the tool call response message and add it to the history. toolResponse := llms.MessageContent{ Role: llms.ChatMessageTypeTool, Parts: []llms.ContentPart{ llms.ToolCallResponse{ Name: toolName, Content: fmt.Sprintf("%v", toolResult), }, }, } messageHistory = append(messageHistory, toolResponse) } finalResp, err := llm.GenerateContent(ctx, messageHistory) if err != nil { log.Fatalf("Final LLM call failed after tool execution: %v", err) } // Add the final textual response from the LLM to the history messageHistory = append(messageHistory, llms.TextParts(llms.ChatMessageTypeAI, finalResp.Choices[0].Content)) fmt.Println(finalResp.Choices[0].Content) } } package main import ( "context" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit" "github.com/firebase/genkit/go/ai" "github.com/firebase/genkit/go/genkit" "github.com/firebase/genkit/go/plugins/googlegenai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { ctx := context.Background() // Create Toolbox Client toolboxClient, err := core.NewToolboxClient("http://127.0.0.1:5000") if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } // Initialize Genkit g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}), genkit.WithDefaultModel("googleai/gemini-2.0-flash"), ) if err != nil { log.Fatalf("Failed to init genkit: %v\n", err) } // Create a conversation history conversationHistory := []*ai.Message{ ai.NewSystemTextMessage(systemPrompt), } // Convert your tool to a Genkit tool. genkitTools := make([]ai.Tool, len(tools)) for i, tool := range tools { newTool, err := tbgenkit.ToGenkitTool(tool, g) if err != nil { log.Fatalf("Failed to convert tool: %v\n", err) } genkitTools[i] = newTool } toolRefs := make([]ai.ToolRef, len(genkitTools)) for i, tool := range genkitTools { toolRefs[i] = tool } for _, query := range queries { conversationHistory = append(conversationHistory, ai.NewUserTextMessage(query)) response, err := genkit.Generate(ctx, g, ai.WithMessages(conversationHistory...), ai.WithTools(toolRefs...), ai.WithReturnToolRequests(true), ) if err != nil { log.Fatalf("%v\n", err) } conversationHistory = append(conversationHistory, response.Message) parts := []*ai.Part{} for _, req := range response.ToolRequests() { tool := genkit.LookupTool(g, req.Name) if tool == nil { log.Fatalf("tool %q not found", req.Name) } output, err := tool.RunRaw(ctx, req.Input) if err != nil { log.Fatalf("tool %q execution failed: %v", tool.Name(), err) } parts = append(parts, ai.NewToolResponsePart(&ai.ToolResponse{ Name: req.Name, Ref: req.Ref, Output: output, })) } if len(parts) > 0 { resp, err := genkit.Generate(ctx, g, ai.WithMessages(append(response.History(), ai.NewMessage(ai.RoleTool, nil, parts...))...), ai.WithTools(toolRefs...), ) if err != nil { log.Fatal(err) } fmt.Println("\n", resp.Text()) conversationHistory = append(conversationHistory, resp.Message) } else { fmt.Println("\n", response.Text()) } } } package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/googleapis/mcp-toolbox-sdk-go/core" "google.golang.org/genai" ) // ConvertToGenaiTool translates a ToolboxTool into the genai.FunctionDeclaration format. func ConvertToGenaiTool(toolboxTool *core.ToolboxTool) *genai.Tool { inputschema, err := toolboxTool.InputSchema() if err != nil { return &genai.Tool{} } var paramsSchema *genai.Schema _ = json.Unmarshal(inputschema, ¶msSchema) // First, create the function declaration. funcDeclaration := &genai.FunctionDeclaration{ Name: toolboxTool.Name(), Description: toolboxTool.Description(), Parameters: paramsSchema, } // Then, wrap the function declaration in a genai.Tool struct. return &genai.Tool{ FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration}, } } func printResponse(resp *genai.GenerateContentResponse) { for _, cand := range resp.Candidates { if cand.Content != nil { for _, part := range cand.Content.Parts { fmt.Println(part.Text) } } } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() apiKey := os.Getenv("GOOGLE_API_KEY") toolboxURL := "http://localhost:5000" // Initialize the Google GenAI client using the explicit ClientConfig. client, err := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: apiKey, }) if err != nil { log.Fatalf("Failed to create Google GenAI client: %v", err) } // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tool using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tools: %v\nMake sure your Toolbox server is running and the tool is configured.", err) } genAITools := make([]*genai.Tool, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { genAITools[i] = ConvertToGenaiTool(tool) toolsMap[tool.Name()] = tool } // Set up the generative model with the available tool. modelName := "gemini-2.0-flash" // Create the initial content prompt for the model. messageHistory := []*genai.Content{ genai.NewContentFromText(systemPrompt, genai.RoleUser), } config := &genai.GenerateContentConfig{ Tools: genAITools, ToolConfig: &genai.ToolConfig{ FunctionCallingConfig: &genai.FunctionCallingConfig{ Mode: genai.FunctionCallingConfigModeAny, }, }, } for _, query := range queries { messageHistory = append(messageHistory, genai.NewContentFromText(query, genai.RoleUser)) genContentResp, err := client.Models.GenerateContent(ctx, modelName, messageHistory, config) if err != nil { log.Fatalf("LLM call failed for query '%s': %v", query, err) } if len(genContentResp.Candidates) > 0 && genContentResp.Candidates[0].Content != nil { messageHistory = append(messageHistory, genContentResp.Candidates[0].Content) } functionCalls := genContentResp.FunctionCalls() toolResponseParts := []*genai.Part{} for _, fc := range functionCalls { toolToInvoke, found := toolsMap[fc.Name] if !found { log.Fatalf("Tool '%s' not found in loaded tools map. Check toolset configuration.", fc.Name) } toolResult, invokeErr := toolToInvoke.Invoke(ctx, fc.Args) if invokeErr != nil { log.Fatalf("Failed to execute tool '%s': %v", fc.Name, invokeErr) } // Enhanced Tool Result Handling (retained to prevent nil issues) toolResultString := "" if toolResult != nil { jsonBytes, marshalErr := json.Marshal(toolResult) if marshalErr == nil { toolResultString = string(jsonBytes) } else { toolResultString = fmt.Sprintf("%v", toolResult) } } responseMap := map[string]any{"result": toolResultString} toolResponseParts = append(toolResponseParts, genai.NewPartFromFunctionResponse(fc.Name, responseMap)) } // Add all accumulated tool responses for this turn to the message history. toolResponseContent := genai.NewContentFromParts(toolResponseParts, "function") messageHistory = append(messageHistory, toolResponseContent) finalResponse, err := client.Models.GenerateContent(ctx, modelName, messageHistory, &genai.GenerateContentConfig{}) if err != nil { log.Fatalf("Error calling GenerateContent (with function result): %v", err) } printResponse(finalResponse) // Add the final textual response from the LLM to the history if len(finalResponse.Candidates) > 0 && finalResponse.Candidates[0].Content != nil { messageHistory = append(messageHistory, finalResponse.Candidates[0].Content) } } } package main import ( "context" "encoding/json" "fmt" "log" "github.com/googleapis/mcp-toolbox-sdk-go/core" openai "github.com/openai/openai-go/v3" ) // ConvertToOpenAITool converts a ToolboxTool into the go-openai library's Tool format. func ConvertToOpenAITool(toolboxTool *core.ToolboxTool) openai.ChatCompletionToolUnionParam { // Get the input schema jsonSchemaBytes, err := toolboxTool.InputSchema() if err != nil { return openai.ChatCompletionToolUnionParam{} } // Unmarshal the JSON bytes into FunctionParameters var paramsSchema openai.FunctionParameters if err := json.Unmarshal(jsonSchemaBytes, ¶msSchema); err != nil { return openai.ChatCompletionToolUnionParam{} } // Create and return the final tool parameter struct. return openai.ChatCompletionToolUnionParam{ OfFunction: &openai.ChatCompletionFunctionToolParam{ Function: openai.FunctionDefinitionParam{ Name: toolboxTool.Name(), Description: openai.String(toolboxTool.Description()), Parameters: paramsSchema, }, }, } } const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queries = []string{ "Find hotels in Basel with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { // Setup ctx := context.Background() toolboxURL := "http://localhost:5000" openAIClient := openai.NewClient() // Initialize the MCP Toolbox client. toolboxClient, err := core.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. tools, err := toolboxClient.LoadToolset("my-toolset", ctx) if err != nil { log.Fatalf("Failed to load tool : %v\nMake sure your Toolbox server is running and the tool is configured.", err) } openAITools := make([]openai.ChatCompletionToolUnionParam, len(tools)) toolsMap := make(map[string]*core.ToolboxTool, len(tools)) for i, tool := range tools { // Convert the Toolbox tool into the openAI FunctionDeclaration format. openAITools[i] = ConvertToOpenAITool(tool) // Add tool to a map for lookup later toolsMap[tool.Name()] = tool } params := openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{ openai.SystemMessage(systemPrompt), }, Tools: openAITools, Seed: openai.Int(0), Model: openai.ChatModelGPT4o, } for _, query := range queries { params.Messages = append(params.Messages, openai.UserMessage(query)) // Make initial chat completion request completion, err := openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } toolCalls := completion.Choices[0].Message.ToolCalls // Return early if there are no tool calls if len(toolCalls) == 0 { log.Println("No function call") } // If there was a function call, continue the conversation params.Messages = append(params.Messages, completion.Choices[0].Message.ToParam()) for _, toolCall := range toolCalls { toolName := toolCall.Function.Name toolToInvoke := toolsMap[toolName] var args map[string]any err := json.Unmarshal([]byte(toolCall.Function.Arguments), &args) if err != nil { panic(err) } result, err := toolToInvoke.Invoke(ctx, args) if err != nil { log.Fatal("Could not invoke tool", err) } params.Messages = append(params.Messages, openai.ToolMessage(result.(string), toolCall.ID)) } completion, err = openAIClient.Chat.Completions.New(ctx, params) if err != nil { panic(err) } params.Messages = append(params.Messages, openai.AssistantMessage(query)) fmt.Println("\n", completion.Choices[0].Message.Content) } } package main import ( "context" "fmt" "log" "os" "strings" "github.com/googleapis/mcp-toolbox-sdk-go/tbadk" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/model/gemini" "google.golang.org/adk/runner" "google.golang.org/adk/session" "google.golang.org/adk/tool" "google.golang.org/genai" ) const systemPrompt = ` You're a helpful hotel assistant. You handle hotel searching, booking, and cancellations. When the user searches for a hotel, mention its name, id, location and price tier. Always mention hotel ids while performing any searches. This is very important for any operations. For any bookings or cancellations, please provide the appropriate confirmation. Be sure to update checkin or checkout dates if mentioned by the user. Don't ask for confirmations from the user. ` var queriesAdk = []string{ "Find hotels in Basel. ", "Find hotels with Basel in its name.", "Can you book the hotel Hilton Basel for me?", "Oh wait, this is too expensive. Please cancel it.", "Please book the Hyatt Regency instead.", "My check in dates would be from April 10, 2024 to April 19, 2024.", } func main() { genaiKey := os.Getenv("GEMINI_API_KEY") toolboxURL := "http://localhost:5000" ctx := context.Background() // Initialize the MCP Toolbox client. toolboxClient, err := tbadk.NewToolboxClient(toolboxURL) if err != nil { log.Fatalf("Failed to create MCP Toolbox client: %v", err) } // Load the tools using the MCP Toolbox SDK. toolsetName := "my-toolset" mcpTools, err := toolboxClient.LoadToolset(toolsetName, ctx) if err != nil { log.Fatalf("Failed to load MCP toolset '%s': %v\nMake sure your Toolbox server is running.", toolsetName, err) } // Set up the Gemini Model model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{ APIKey: genaiKey, }) if err != nil { log.Fatalf("Failed to create model: %v", err) } // Type Cast the ToolboxTools tools := make([]tool.Tool, len(mcpTools)) for i := range mcpTools { tools[i] = &mcpTools[i] } // Create an llm agent llmagent, err := llmagent.New(llmagent.Config{ Name: "hotel_assistant", Model: model, Description: "Agent to answer questions about hotels.", Instruction: systemPrompt, Tools: tools, }) if err != nil { log.Fatalf("Failed to create agent: %v", err) } appName := "hotel_assistant" userID := "user-123" // Create a session service sessionService := session.InMemoryService() resp, err := sessionService.Create(ctx, &session.CreateRequest{ AppName: appName, UserID: userID, }) if err != nil { log.Fatalf("Failed to create the session service: %v", err) } session := resp.Session // Configure the runner r, err := runner.New(runner.Config{ AppName: appName, Agent: llmagent, SessionService: sessionService, }) if err != nil { log.Fatalf("Failed to create runner: %v", err) } // Loop through queries to the llm agent for i, query := range queriesAdk { fmt.Printf("\n=== Query %d: %s ===\n", i+1, query) userMsg := genai.NewContentFromText(query, genai.RoleUser) streamingMode := agent.StreamingModeSSE for event, err := range r.Run(ctx, userID, session.ID(), userMsg, agent.RunConfig{ StreamingMode: streamingMode, }) { if err != nil { fmt.Printf("\nAGENT_ERROR: %v\n", err) } else { if event.LLMResponse.Content != nil { for _, p := range event.LLMResponse.Content.Parts { // if its running in streaming mode, don't print the non partial llmResponses if streamingMode != agent.StreamingModeSSE || event.LLMResponse.Partial { fmt.Print(p.Text) } } } } } fmt.Println("\n" + strings.Repeat("-", 80) + "\n") } } 4. Ensure all dependencies are installed: go mod tidy 5. Run your agent, and observe the results: go run hotelagent.go Info For more information, visit the [Go SDK repo](https://github.com/googleapis/mcp-toolbox-sdk-go) . Last modified February 25, 2026: [doc: Fix ADK quickstart rendering with shortcodes (#2541) (182d63c7a08)](https://github.com/googleapis/genai-toolbox/commit/182d63c7a080de7f673ad4364ddfde863405c6cb) --- # Concepts | MCP Toolbox for Databases Concepts ======== Some core concepts in Toolbox * * * ##### [Telemetry](https://mcp-toolbox.dev/v0.26.0/concepts/telemetry/) An overview of telemetry and observability in Toolbox. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Telemetry | MCP Toolbox for Databases Telemetry ========= An overview of telemetry and observability in Toolbox. About ----- Telemetry data such as logs, metrics, and traces will help developers understand the internal state of the system. This page walks though different types of telemetry and observability available in Toolbox. Toolbox exports telemetry data of logs via standard out/err, and traces/metrics through [OpenTelemetry](https://opentelemetry.io/) . Additional flags can be passed to Toolbox to enable different logging behavior, or to export metrics through a specific [exporter](https://mcp-toolbox.dev/v0.24.0/concepts/telemetry/#exporter) . Logging ------- The following flags can be used to customize Toolbox logging: | **Flag** | **Description** | | --- | --- | | `--log-level` | Preferred log level, allowed values: `debug`, `info`, `warn`, `error`. Default: `info`. | | `--logging-format` | Preferred logging format, allowed values: `standard`, `json`. Default: `standard`. | **Example:** ./toolbox --tools-file "tools.yaml" --log-level warn --logging-format json ### Level Toolbox supports the following log levels, including: | **Log level** | **Description** | | --- | --- | | Debug | Debug logs typically contain information that is only useful during the debugging phase and may be of little value during production. | | Info | Info logs include information about successful operations within the application, such as a successful start, pause, or exit of the application. | | Warn | Warning logs are slightly less severe than error conditions. While it does not cause an error, it indicates that an operation might fail in the future if action is not taken now. | | Error | Error log is assigned to event logs that contain an application error message. | Toolbox will only output logs that are equal or more severe to the level that it is set. Below are the log levels that Toolbox supports in the order of severity. ### Format Toolbox supports both standard and structured logging format. The standard logging outputs log as string: 2024-11-12T15:08:11.451377-08:00 INFO "Initialized 0 sources.\n" The structured logging outputs log as JSON: { "timestamp":"2024-11-04T16:45:11.987299-08:00", "severity":"ERROR", "logging.googleapis.com/sourceLocation":{...}, "message":"unable to parse tool file at \"tools.yaml\": \"cloud-sql-postgres1\" is not a valid kind of data source" } Tip `logging.googleapis.com/sourceLocation` shows the source code location information associated with the log entry, if any. Telemetry --------- Toolbox is supports exporting metrics and traces to any OpenTelemetry compatible exporter. ### Metrics A metric is a measurement of a service captured at runtime. The collected data can be used to provide important insights into the service. Toolbox provides the following custom metrics: | **Metric Name** | **Description** | | --- | --- | | `toolbox.server.toolset.get.count` | Counts the number of toolset manifest requests served | | `toolbox.server.tool.get.count` | Counts the number of tool manifest requests served | | `toolbox.server.tool.get.invoke` | Counts the number of tool invocation requests served | | `toolbox.server.mcp.sse.count` | Counts the number of mcp sse connection requests served | | `toolbox.server.mcp.post.count` | Counts the number of mcp post requests served | All custom metrics have the following attributes/labels: | **Metric Attributes** | **Description** | | --- | --- | | `toolbox.name` | Name of the toolset or tool, if applicable. | | `toolbox.operation.status` | Operation status code, for example: `success`, `failure`. | | `toolbox.sse.sessionId` | Session id for sse connection, if applicable. | | `toolbox.method` | Method of JSON-RPC request, if applicable. | ### Traces A trace is a tree of spans that shows the path that a request makes through an application. Spans generated by Toolbox server is prefixed with `toolbox/server/`. For example, when user run Toolbox, it will generate spans for the following, with `toolbox/server/init` as the root span: ![traces](https://mcp-toolbox.dev/v0.24.0/concepts/telemetry/telemetry_traces.png) ### Resource Attributes All metrics and traces generated within Toolbox will be associated with a unified [resource](https://opentelemetry.io/docs/languages/go/resources/) . The list of resource attributes included are: | **Resource Name** | **Description** | | --- | --- | | [TelemetrySDK](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithTelemetrySDK) | TelemetrySDK version info. | | [OS](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithOS) | OS attributes including OS description and OS type. | | [Container](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainer) | Container attributes including container ID, if applicable. | | [Host](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithHost) | Host attributes including host name. | | [SchemaURL](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithSchemaURL) | Sets the schema URL for the configured resource. | | `service.name` | Open telemetry service name. Defaulted to `toolbox`. User can set the service name via flag mentioned above to distinguish between different toolbox service. | | `service.version` | The version of Toolbox used. | ### Exporter An exporter is responsible for processing and exporting telemetry data. Toolbox generates telemetry data within the OpenTelemetry Protocol (OTLP), and user can choose to use exporters that are designed to support the OpenTelemetry Protocol. Within Toolbox, we provide two types of exporter implementation to choose from, either the Google Cloud Exporter that will send data directly to the backend, or the OTLP Exporter along with a Collector that will act as a proxy to collect and export data to the telemetry backend of user’s choice. ![telemetry_flow](https://mcp-toolbox.dev/v0.24.0/concepts/telemetry/telemetry_flow.png) #### Google Cloud Exporter The Google Cloud Exporter directly exports telemetry to Google Cloud Monitoring. It utilizes the [GCP Metric Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/metric) and [GCP Trace Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/trace) . Note If you’re using Google Cloud Monitoring, the following APIs will need to be enabled: * [Cloud Logging API](https://cloud.google.com/logging/docs/api/enable-api) * [Cloud Monitoring API](https://cloud.google.com/monitoring/api/enable-api) * [Cloud Trace API](https://console.cloud.google.com/apis/enableflow?apiid=cloudtrace.googleapis.com) #### OTLP Exporter This implementation uses the default OTLP Exporter over HTTP for [metrics](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) and [traces](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) . You can use this exporter if you choose to export your telemetry data to a Collector. ### Collector A collector acts as a proxy between the application and the telemetry backend. It receives telemetry data, transforms it, and then exports data to backends that can store it permanently. Toolbox provide an option to export telemetry data to user’s choice of backend(s) that are compatible with the Open Telemetry Protocol (OTLP). If you would like to use a collector, please refer to this [Export Telemetry using the Otel Collector](https://mcp-toolbox.dev/v0.24.0/how-to/export_telemetry/) . ### Flags The following flags are used to determine Toolbox’s telemetry configuration: | **flag** | **type** | **description** | | --- | --- | --- | | `--telemetry-gcp` | bool | Enable exporting directly to Google Cloud Monitoring. Default is `false`. | | `--telemetry-otlp` | string | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. “127.0.0.1:4318”). To pass an insecure endpoint here, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. | | `--telemetry-service-name` | string | Sets the value of the `service.name` resource attribute. Default is `toolbox`. | In addition to the flags noted above, you can also make additional configuration for OpenTelemetry via the [General SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/) through environmental variables. **Examples:** To enable Google Cloud Exporter: ./toolbox --telemetry-gcp To enable OTLP Exporter, provide Collector endpoint: ./toolbox --telemetry-otlp="127.0.0.1:4553" Last modified December 18, 2025: [docs: telemetry docs to provide endpoint without scheme or path (#2179) (6e873494314)](https://github.com/googleapis/genai-toolbox/commit/6e8734943147dc919800db98af7987f2302c937d) --- # Prompts using Gemini CLI | MCP Toolbox for Databases Prompts using Gemini CLI ======================== How to get started using Toolbox prompts locally with PostgreSQL and [Gemini CLI](https://pypi.org/project/gemini-cli/) . Before you begin ---------------- This guide assumes you have already done the following: 1. Installed [PostgreSQL 16+ and the `psql` client](https://www.postgresql.org/download/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be accessed by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. Info #### **Having trouble connecting?** * **Password Prompt:** If you are prompted for a password for the `postgres` user and do not know it (or a blank password doesn’t work), your PostgreSQL installation might require a password or a different authentication method. * **`FATAL: role "postgres" does not exist`:** This error means the default `postgres` superuser role isn’t available under that name on your system. * **`Connection refused`:** Ensure your PostgreSQL server is actually running. You can typically check with `sudo systemctl status postgresql` and start it with `sudo systemctl start postgresql` on Linux systems. #### **Common Solution** For password issues or if the `postgres` role seems inaccessible directly, try switching to the `postgres` operating system user first. This user often has permission to connect without a password for local connections (this is called peer authentication). sudo -i -u postgres psql -h 127.0.0.1 Once you are in the `psql` shell using this method, you can proceed with the database creation steps below. Afterwards, type `\q` to exit `psql`, and then `exit` to return to your normal user shell. If desired, once connected to `psql` as the `postgres` OS user, you can set a password for the `postgres` _database_ user using: `ALTER USER postgres WITH PASSWORD 'your_chosen_password';`. This would allow direct connection with `-U postgres` and a password next time. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q (If you used `sudo -i -u postgres` and then `psql`, remember you might also need to type `exit` after `\q` to leave the `postgres` user’s shell session.) 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create the required tables using the following commands: CREATE TABLE users ( id SERIAL PRIMARY KEY, username VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE restaurants ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, location VARCHAR(100) ); CREATE TABLE reviews ( id SERIAL PRIMARY KEY, user_id INT REFERENCES users(id), restaurant_id INT REFERENCES restaurants(id), rating INT CHECK (rating >= 1 AND rating <= 5), review_text TEXT, is_published BOOLEAN DEFAULT false, moderation_status VARCHAR(50) DEFAULT 'pending_manual_review', created_at TIMESTAMPTZ DEFAULT NOW() ); 6. Insert dummy data into the tables. INSERT INTO users (id, username, email) VALUES (123, 'jane_d', '[email protected]'), (124, 'john_s', '[email protected]'), (125, 'sam_b', '[email protected]'); INSERT INTO restaurants (id, name, location) VALUES (455, 'Pizza Palace', '123 Main St'), (456, 'The Corner Bistro', '456 Oak Ave'), (457, 'Sushi Spot', '789 Pine Ln'); INSERT INTO reviews (user_id, restaurant_id, rating, review_text, is_published, moderation_status) VALUES (124, 455, 5, 'Best pizza in town! The crust was perfect.', true, 'approved'), (125, 457, 4, 'Great sushi, very fresh. A bit pricey but worth it.', true, 'approved'), (123, 457, 5, 'Absolutely loved the dragon roll. Will be back!', true, 'approved'), (123, 456, 4, 'The atmosphere was lovely and the food was great. My photo upload might have been weird though.', false, 'pending_manual_review'), (125, 456, 1, 'This review contains inappropriate language.', false, 'rejected'); 7. End the database session: \q Step 2: Configure Toolbox ------------------------- Create a file named `tools.yaml`. This file defines the database connection, the SQL tools available, and the prompts the agents will use. kind: sources name: my-foodiefind-db type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: find_user_by_email type: postgres-sql source: my-foodiefind-db description: Find a user's ID by their email address. parameters: - name: email type: string description: The email address of the user to find. statement: SELECT id FROM users WHERE email = $1; --- kind: tools name: find_restaurant_by_name type: postgres-sql source: my-foodiefind-db description: Find a restaurant's ID by its exact name. parameters: - name: name type: string description: The name of the restaurant to find. statement: SELECT id FROM restaurants WHERE name = $1; --- kind: tools name: find_review_by_user_and_restaurant type: postgres-sql source: my-foodiefind-db description: Find the full record for a specific review using the user's ID and the restaurant's ID. parameters: - name: user_id type: integer description: The numerical ID of the user. - name: restaurant_id type: integer description: The numerical ID of the restaurant. statement: SELECT * FROM reviews WHERE user_id = $1 AND restaurant_id = $2; --- kind: prompts name: investigate_missing_review description: "Investigates a user's missing review by finding the user, restaurant, and the review itself, then analyzing its status." arguments: - name: "user_email" description: "The email of the user who wrote the review." - name: "restaurant_name" description: "The name of the restaurant being reviewed." messages: - content: >- **Goal:** Find the review written by the user with email '{{.user_email}}' for the restaurant named '{{.restaurant_name}}' and understand its status. **Workflow:** 1. Use the `find_user_by_email` tool with the email '{{.user_email}}' to get the `user_id`. 2. Use the `find_restaurant_by_name` tool with the name '{{.restaurant_name}}' to get the `restaurant_id`. 3. Use the `find_review_by_user_and_restaurant` tool with the `user_id` and `restaurant_id` you just found. 4. Analyze the results from the final tool call. Examine the `is_published` and `moderation_status` fields and explain the review's status to the user in a clear, human-readable sentence. Step 3: Connect to Gemini CLI ----------------------------- Configure the Gemini CLI to talk to your local Toolbox MCP server. 1. Open or create your Gemini settings file: `~/.gemini/settings.json`. 2. Add the following configuration to the file: { "mcpServers": { "MCPToolbox": { "httpUrl": "http://localhost:5000/mcp" } }, "mcp": { "allowed": ["MCPToolbox"] } } 3. Start Gemini CLI using gemini In case Gemini CLI is already running, use `/mcp refresh` to refresh the MCP server. 4. Use gemini slash commands to run your prompt: /investigate_missing_review --user_email="[email protected]" --restaurant_name="The Corner Bistro" Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Configuration | MCP Toolbox for Databases Configuration ============= How to configure Toolbox’s tools.yaml file. The primary way to configure Toolbox is through the `tools.yaml` file. If you have multiple files, you can tell toolbox which to load with the `--tools-file tools.yaml` flag. You can find more detailed reference documentation to all resource types in the [Resources](https://mcp-toolbox.dev/v0.28.0/resources/) . ### Using Environment Variables To avoid hardcoding certain secret fields like passwords, usernames, API keys etc., you could use environment variables instead with the format `${ENV_NAME}`. user: ${USER_NAME} password: ${PASSWORD} A default value can be specified like `${ENV_NAME:default}`. port: ${DB_PORT:3306} ### Sources The `sources` section of your `tools.yaml` defines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} For more details on configuring different types of sources, see the [Sources](https://mcp-toolbox.dev/v0.28.0/resources/sources/) . ### Tools The `tools` section of your `tools.yaml` defines the actions your agent can take: what type of tool it is, which source(s) it affects, what parameters it uses, etc. kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; For more details on configuring different types of tools, see the [Tools](https://mcp-toolbox.dev/v0.28.0/resources/tools/) . ### Toolsets The `toolsets` section of your `tools.yaml` allows you to define groups of tools that you want to be able to load together. This can be useful for defining different sets for different agents or different applications. kind: toolsets name: my_first_toolset tools: - my_first_tool - my_second_tool --- kind: toolsets name: my_second_toolset tools: - my_second_tool - my_third_tool You can load toolsets by name: # This will load all tools all_tools = client.load_toolset() # This will only load the tools listed in 'my_second_toolset' my_second_toolset = client.load_toolset("my_second_toolset") ### Prompts The `prompts` section of your `tools.yaml` defines the templates containing structured messages and instructions for interacting with language models. kind: prompts name: code_review description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review" For more details on configuring different types of prompts, see the [Prompts](https://mcp-toolbox.dev/v0.28.0/resources/prompts/) . Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Telemetry | MCP Toolbox for Databases Telemetry ========= An overview of telemetry and observability in Toolbox. About ----- Telemetry data such as logs, metrics, and traces will help developers understand the internal state of the system. This page walks though different types of telemetry and observability available in Toolbox. Toolbox exports telemetry data of logs via standard out/err, and traces/metrics through [OpenTelemetry](https://opentelemetry.io/) . Additional flags can be passed to Toolbox to enable different logging behavior, or to export metrics through a specific [exporter](https://mcp-toolbox.dev/v0.25.0/concepts/telemetry/#exporter) . Logging ------- The following flags can be used to customize Toolbox logging: | **Flag** | **Description** | | --- | --- | | `--log-level` | Preferred log level, allowed values: `debug`, `info`, `warn`, `error`. Default: `info`. | | `--logging-format` | Preferred logging format, allowed values: `standard`, `json`. Default: `standard`. | **Example:** ./toolbox --tools-file "tools.yaml" --log-level warn --logging-format json ### Level Toolbox supports the following log levels, including: | **Log level** | **Description** | | --- | --- | | Debug | Debug logs typically contain information that is only useful during the debugging phase and may be of little value during production. | | Info | Info logs include information about successful operations within the application, such as a successful start, pause, or exit of the application. | | Warn | Warning logs are slightly less severe than error conditions. While it does not cause an error, it indicates that an operation might fail in the future if action is not taken now. | | Error | Error log is assigned to event logs that contain an application error message. | Toolbox will only output logs that are equal or more severe to the level that it is set. Below are the log levels that Toolbox supports in the order of severity. ### Format Toolbox supports both standard and structured logging format. The standard logging outputs log as string: 2024-11-12T15:08:11.451377-08:00 INFO "Initialized 0 sources.\n" The structured logging outputs log as JSON: { "timestamp":"2024-11-04T16:45:11.987299-08:00", "severity":"ERROR", "logging.googleapis.com/sourceLocation":{...}, "message":"unable to parse tool file at \"tools.yaml\": \"cloud-sql-postgres1\" is not a valid kind of data source" } Tip `logging.googleapis.com/sourceLocation` shows the source code location information associated with the log entry, if any. Telemetry --------- Toolbox is supports exporting metrics and traces to any OpenTelemetry compatible exporter. ### Metrics A metric is a measurement of a service captured at runtime. The collected data can be used to provide important insights into the service. Toolbox provides the following custom metrics: | **Metric Name** | **Description** | | --- | --- | | `toolbox.server.toolset.get.count` | Counts the number of toolset manifest requests served | | `toolbox.server.tool.get.count` | Counts the number of tool manifest requests served | | `toolbox.server.tool.get.invoke` | Counts the number of tool invocation requests served | | `toolbox.server.mcp.sse.count` | Counts the number of mcp sse connection requests served | | `toolbox.server.mcp.post.count` | Counts the number of mcp post requests served | All custom metrics have the following attributes/labels: | **Metric Attributes** | **Description** | | --- | --- | | `toolbox.name` | Name of the toolset or tool, if applicable. | | `toolbox.operation.status` | Operation status code, for example: `success`, `failure`. | | `toolbox.sse.sessionId` | Session id for sse connection, if applicable. | | `toolbox.method` | Method of JSON-RPC request, if applicable. | ### Traces A trace is a tree of spans that shows the path that a request makes through an application. Spans generated by Toolbox server is prefixed with `toolbox/server/`. For example, when user run Toolbox, it will generate spans for the following, with `toolbox/server/init` as the root span: ![traces](https://mcp-toolbox.dev/v0.25.0/concepts/telemetry/telemetry_traces.png) ### Resource Attributes All metrics and traces generated within Toolbox will be associated with a unified [resource](https://opentelemetry.io/docs/languages/go/resources/) . The list of resource attributes included are: | **Resource Name** | **Description** | | --- | --- | | [TelemetrySDK](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithTelemetrySDK) | TelemetrySDK version info. | | [OS](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithOS) | OS attributes including OS description and OS type. | | [Container](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainer) | Container attributes including container ID, if applicable. | | [Host](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithHost) | Host attributes including host name. | | [SchemaURL](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithSchemaURL) | Sets the schema URL for the configured resource. | | `service.name` | Open telemetry service name. Defaulted to `toolbox`. User can set the service name via flag mentioned above to distinguish between different toolbox service. | | `service.version` | The version of Toolbox used. | ### Exporter An exporter is responsible for processing and exporting telemetry data. Toolbox generates telemetry data within the OpenTelemetry Protocol (OTLP), and user can choose to use exporters that are designed to support the OpenTelemetry Protocol. Within Toolbox, we provide two types of exporter implementation to choose from, either the Google Cloud Exporter that will send data directly to the backend, or the OTLP Exporter along with a Collector that will act as a proxy to collect and export data to the telemetry backend of user’s choice. ![telemetry_flow](https://mcp-toolbox.dev/v0.25.0/concepts/telemetry/telemetry_flow.png) #### Google Cloud Exporter The Google Cloud Exporter directly exports telemetry to Google Cloud Monitoring. It utilizes the [GCP Metric Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/metric) and [GCP Trace Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/trace) . Note If you’re using Google Cloud Monitoring, the following APIs will need to be enabled: * [Cloud Logging API](https://cloud.google.com/logging/docs/api/enable-api) * [Cloud Monitoring API](https://cloud.google.com/monitoring/api/enable-api) * [Cloud Trace API](https://console.cloud.google.com/apis/enableflow?apiid=cloudtrace.googleapis.com) #### OTLP Exporter This implementation uses the default OTLP Exporter over HTTP for [metrics](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) and [traces](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) . You can use this exporter if you choose to export your telemetry data to a Collector. ### Collector A collector acts as a proxy between the application and the telemetry backend. It receives telemetry data, transforms it, and then exports data to backends that can store it permanently. Toolbox provide an option to export telemetry data to user’s choice of backend(s) that are compatible with the Open Telemetry Protocol (OTLP). If you would like to use a collector, please refer to this [Export Telemetry using the Otel Collector](https://mcp-toolbox.dev/v0.25.0/how-to/export_telemetry/) . ### Flags The following flags are used to determine Toolbox’s telemetry configuration: | **flag** | **type** | **description** | | --- | --- | --- | | `--telemetry-gcp` | bool | Enable exporting directly to Google Cloud Monitoring. Default is `false`. | | `--telemetry-otlp` | string | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. “127.0.0.1:4318”). To pass an insecure endpoint here, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. | | `--telemetry-service-name` | string | Sets the value of the `service.name` resource attribute. Default is `toolbox`. | In addition to the flags noted above, you can also make additional configuration for OpenTelemetry via the [General SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/) through environmental variables. **Examples:** To enable Google Cloud Exporter: ./toolbox --telemetry-gcp To enable OTLP Exporter, provide Collector endpoint: ./toolbox --telemetry-otlp="127.0.0.1:4553" Last modified December 18, 2025: [docs: telemetry docs to provide endpoint without scheme or path (#2179) (6e873494314)](https://github.com/googleapis/genai-toolbox/commit/6e8734943147dc919800db98af7987f2302c937d) --- # Quickstart (MCP) | MCP Toolbox for Databases Quickstart (MCP) ================ How to get started running Toolbox locally with MCP Inspector. Overview -------- [Model Context Protocol](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to LLMs. Check out this page on how to [connect to Toolbox via MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect_via_mcp/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be access by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the [Tools](https://mcp-toolbox.dev/v0.29.0/resources/tools/) section. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Step 3: Connect to MCP Inspector -------------------------------- 1. Run the MCP Inspector: npx @modelcontextprotocol/inspector 2. Type `y` when it asks to install the inspector package. 3. It should show the following when the MCP Inspector is up and running (please take note of ``): Starting MCP inspector... ⚙️ Proxy server listening on localhost:6277 🔑 Session token: Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth 🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN= 4. Open the above link in your browser. 5. For `Transport Type`, select `Streamable HTTP`. 6. For `URL`, type in `http://127.0.0.1:5000/mcp`. 7. For `Configuration` -> `Proxy Session Token`, make sure `` is present. 8. Click Connect. ![inspector](https://mcp-toolbox.dev/v0.29.0/getting-started/mcp_quickstart/inspector.png) 9. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. ![inspector_tools](https://mcp-toolbox.dev/v0.29.0/getting-started/mcp_quickstart/inspector_tools.png) 10. Test out your tools here! Last modified March 13, 2026: [chore(main): release 0.29.0 (#2608) (39832a0faa6)](https://github.com/googleapis/genai-toolbox/commit/39832a0faa6e967734f4cf2283ec270aa17fc363) --- # Telemetry | MCP Toolbox for Databases Telemetry ========= An overview of telemetry and observability in Toolbox. About ----- Telemetry data such as logs, metrics, and traces will help developers understand the internal state of the system. This page walks though different types of telemetry and observability available in Toolbox. Toolbox exports telemetry data of logs via standard out/err, and traces/metrics through [OpenTelemetry](https://opentelemetry.io/) . Additional flags can be passed to Toolbox to enable different logging behavior, or to export metrics through a specific [exporter](https://mcp-toolbox.dev/v0.26.0/concepts/telemetry/#exporter) . Logging ------- The following flags can be used to customize Toolbox logging: | **Flag** | **Description** | | --- | --- | | `--log-level` | Preferred log level, allowed values: `debug`, `info`, `warn`, `error`. Default: `info`. | | `--logging-format` | Preferred logging format, allowed values: `standard`, `json`. Default: `standard`. | **Example:** ./toolbox --tools-file "tools.yaml" --log-level warn --logging-format json ### Level Toolbox supports the following log levels, including: | **Log level** | **Description** | | --- | --- | | Debug | Debug logs typically contain information that is only useful during the debugging phase and may be of little value during production. | | Info | Info logs include information about successful operations within the application, such as a successful start, pause, or exit of the application. | | Warn | Warning logs are slightly less severe than error conditions. While it does not cause an error, it indicates that an operation might fail in the future if action is not taken now. | | Error | Error log is assigned to event logs that contain an application error message. | Toolbox will only output logs that are equal or more severe to the level that it is set. Below are the log levels that Toolbox supports in the order of severity. ### Format Toolbox supports both standard and structured logging format. The standard logging outputs log as string: 2024-11-12T15:08:11.451377-08:00 INFO "Initialized 0 sources.\n" The structured logging outputs log as JSON: { "timestamp":"2024-11-04T16:45:11.987299-08:00", "severity":"ERROR", "logging.googleapis.com/sourceLocation":{...}, "message":"unable to parse tool file at \"tools.yaml\": \"cloud-sql-postgres1\" is not a valid kind of data source" } Tip `logging.googleapis.com/sourceLocation` shows the source code location information associated with the log entry, if any. Telemetry --------- Toolbox is supports exporting metrics and traces to any OpenTelemetry compatible exporter. ### Metrics A metric is a measurement of a service captured at runtime. The collected data can be used to provide important insights into the service. Toolbox provides the following custom metrics: | **Metric Name** | **Description** | | --- | --- | | `toolbox.server.toolset.get.count` | Counts the number of toolset manifest requests served | | `toolbox.server.tool.get.count` | Counts the number of tool manifest requests served | | `toolbox.server.tool.get.invoke` | Counts the number of tool invocation requests served | | `toolbox.server.mcp.sse.count` | Counts the number of mcp sse connection requests served | | `toolbox.server.mcp.post.count` | Counts the number of mcp post requests served | All custom metrics have the following attributes/labels: | **Metric Attributes** | **Description** | | --- | --- | | `toolbox.name` | Name of the toolset or tool, if applicable. | | `toolbox.operation.status` | Operation status code, for example: `success`, `failure`. | | `toolbox.sse.sessionId` | Session id for sse connection, if applicable. | | `toolbox.method` | Method of JSON-RPC request, if applicable. | ### Traces A trace is a tree of spans that shows the path that a request makes through an application. Spans generated by Toolbox server is prefixed with `toolbox/server/`. For example, when user run Toolbox, it will generate spans for the following, with `toolbox/server/init` as the root span: ![traces](https://mcp-toolbox.dev/v0.26.0/concepts/telemetry/telemetry_traces.png) ### Resource Attributes All metrics and traces generated within Toolbox will be associated with a unified [resource](https://opentelemetry.io/docs/languages/go/resources/) . The list of resource attributes included are: | **Resource Name** | **Description** | | --- | --- | | [TelemetrySDK](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithTelemetrySDK) | TelemetrySDK version info. | | [OS](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithOS) | OS attributes including OS description and OS type. | | [Container](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainer) | Container attributes including container ID, if applicable. | | [Host](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithHost) | Host attributes including host name. | | [SchemaURL](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithSchemaURL) | Sets the schema URL for the configured resource. | | `service.name` | Open telemetry service name. Defaulted to `toolbox`. User can set the service name via flag mentioned above to distinguish between different toolbox service. | | `service.version` | The version of Toolbox used. | ### Exporter An exporter is responsible for processing and exporting telemetry data. Toolbox generates telemetry data within the OpenTelemetry Protocol (OTLP), and user can choose to use exporters that are designed to support the OpenTelemetry Protocol. Within Toolbox, we provide two types of exporter implementation to choose from, either the Google Cloud Exporter that will send data directly to the backend, or the OTLP Exporter along with a Collector that will act as a proxy to collect and export data to the telemetry backend of user’s choice. ![telemetry_flow](https://mcp-toolbox.dev/v0.26.0/concepts/telemetry/telemetry_flow.png) #### Google Cloud Exporter The Google Cloud Exporter directly exports telemetry to Google Cloud Monitoring. It utilizes the [GCP Metric Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/metric) and [GCP Trace Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/trace) . Note If you’re using Google Cloud Monitoring, the following APIs will need to be enabled: * [Cloud Logging API](https://cloud.google.com/logging/docs/api/enable-api) * [Cloud Monitoring API](https://cloud.google.com/monitoring/api/enable-api) * [Cloud Trace API](https://console.cloud.google.com/apis/enableflow?apiid=cloudtrace.googleapis.com) #### OTLP Exporter This implementation uses the default OTLP Exporter over HTTP for [metrics](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) and [traces](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) . You can use this exporter if you choose to export your telemetry data to a Collector. ### Collector A collector acts as a proxy between the application and the telemetry backend. It receives telemetry data, transforms it, and then exports data to backends that can store it permanently. Toolbox provide an option to export telemetry data to user’s choice of backend(s) that are compatible with the Open Telemetry Protocol (OTLP). If you would like to use a collector, please refer to this [Export Telemetry using the Otel Collector](https://mcp-toolbox.dev/v0.26.0/how-to/export_telemetry/) . ### Flags The following flags are used to determine Toolbox’s telemetry configuration: | **flag** | **type** | **description** | | --- | --- | --- | | `--telemetry-gcp` | bool | Enable exporting directly to Google Cloud Monitoring. Default is `false`. | | `--telemetry-otlp` | string | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. “127.0.0.1:4318”). To pass an insecure endpoint here, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. | | `--telemetry-service-name` | string | Sets the value of the `service.name` resource attribute. Default is `toolbox`. | In addition to the flags noted above, you can also make additional configuration for OpenTelemetry via the [General SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/) through environmental variables. **Examples:** To enable Google Cloud Exporter: ./toolbox --telemetry-gcp To enable OTLP Exporter, provide Collector endpoint: ./toolbox --telemetry-otlp="127.0.0.1:4553" Last modified December 18, 2025: [docs: telemetry docs to provide endpoint without scheme or path (#2179) (6e873494314)](https://github.com/googleapis/genai-toolbox/commit/6e8734943147dc919800db98af7987f2302c937d) --- # Quickstart (MCP) | MCP Toolbox for Databases Quickstart (MCP) ================ How to get started running Toolbox locally with MCP Inspector. Overview -------- [Model Context Protocol](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to LLMs. Check out this page on how to [connect to Toolbox via MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect_via_mcp/) . Step 1: Set up your database ---------------------------- In this section, we will create a database, insert some data that needs to be access by our agent, and create a database user for Toolbox to connect with. 1. Connect to postgres using the `psql` command: psql -h 127.0.0.1 -U postgres Here, `postgres` denotes the default postgres superuser. 2. Create a new database and a new user: Tip For a real application, it’s best to follow the principle of least permission and only grant the privileges your application needs. CREATE USER toolbox_user WITH PASSWORD 'my-password'; CREATE DATABASE toolbox_db; GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; ALTER DATABASE toolbox_db OWNER TO toolbox_user; 3. End the database session: \q 4. Connect to your database with your new user: psql -h 127.0.0.1 -U toolbox_user -d toolbox_db 5. Create a table using the following command: CREATE TABLE hotels( id INTEGER NOT NULL PRIMARY KEY, name VARCHAR NOT NULL, location VARCHAR NOT NULL, price_tier VARCHAR NOT NULL, checkin_date DATE NOT NULL, checkout_date DATE NOT NULL, booked BIT NOT NULL ); 6. Insert data into the table. INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) VALUES (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); 7. End the database session: \q Step 2: Install and configure Toolbox ------------------------------------- In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. 1. Download the latest version of Toolbox as a binary: Tip Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/$OS/toolbox 2. Make the binary executable: chmod +x toolbox 3. Write the following into a `tools.yaml` file. Be sure to update any fields such as `user`, `password`, or `database` that you may have customized in the previous step. Tip In practice, use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: toolbox_user password: my-password --- kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; --- kind: tools name: search-hotels-by-location type: postgres-sql source: my-pg-source description: Search for hotels based on location. parameters: - name: location type: string description: The location of the hotel. statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; --- kind: tools name: book-hotel type: postgres-sql source: my-pg-source description: >- Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. parameters: - name: hotel_id type: string description: The ID of the hotel to book. statement: UPDATE hotels SET booked = B'1' WHERE id = $1; --- kind: tools name: update-hotel type: postgres-sql source: my-pg-source description: >- Update a hotel's check-in and check-out dates by its ID. Returns a message indicating whether the hotel was successfully updated or not. parameters: - name: hotel_id type: string description: The ID of the hotel to update. - name: checkin_date type: string description: The new check-in date of the hotel. - name: checkout_date type: string description: The new check-out date of the hotel. statement: >- UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 as date) WHERE id = $1; --- kind: tools name: cancel-hotel type: postgres-sql source: my-pg-source description: Cancel a hotel by its ID. parameters: - name: hotel_id type: string description: The ID of the hotel to cancel. statement: UPDATE hotels SET booked = B'0' WHERE id = $1; --- kind: toolsets name: my-toolset tools: - search-hotels-by-name - search-hotels-by-location - book-hotel - update-hotel - cancel-hotel For more info on tools, check out the [Tools](https://mcp-toolbox.dev/v0.30.0/resources/tools/) section. 4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ./toolbox --tools-file "tools.yaml" Step 3: Connect to MCP Inspector -------------------------------- 1. Run the MCP Inspector: npx @modelcontextprotocol/inspector 2. Type `y` when it asks to install the inspector package. 3. It should show the following when the MCP Inspector is up and running (please take note of ``): Starting MCP inspector... ⚙️ Proxy server listening on localhost:6277 🔑 Session token: Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth 🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN= 4. Open the above link in your browser. 5. For `Transport Type`, select `Streamable HTTP`. 6. For `URL`, type in `http://127.0.0.1:5000/mcp`. 7. For `Configuration` -> `Proxy Session Token`, make sure `` is present. 8. Click Connect. ![inspector](https://mcp-toolbox.dev/v0.30.0/getting-started/mcp_quickstart/inspector.png) 9. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. ![inspector_tools](https://mcp-toolbox.dev/v0.30.0/getting-started/mcp_quickstart/inspector_tools.png) 10. Test out your tools here! Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # How-to | MCP Toolbox for Databases How-to ====== List of guides detailing how to do different things with Toolbox. * * * ##### [Connect from your IDE](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/) List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. ##### [Connect via MCP Client](https://mcp-toolbox.dev/v0.24.0/how-to/connect_via_mcp/) How to connect to Toolbox from a MCP Client. ##### [Toolbox UI](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/) How to effectively use Toolbox UI. ##### [Connect via Gemini CLI Extensions](https://mcp-toolbox.dev/v0.24.0/how-to/connect_via_geminicli/) Connect to Toolbox via Gemini CLI Extensions. ##### [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.24.0/how-to/deploy_toolbox/) How to set up and configure Toolbox to run on Cloud Run. ##### [Deploy ADK Agent and MCP Toolbox](https://mcp-toolbox.dev/v0.24.0/how-to/deploy_adk_agent/) How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. ##### [Deploy to Kubernetes](https://mcp-toolbox.dev/v0.24.0/how-to/deploy_gke/) How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). ##### [Deploy using Docker Compose](https://mcp-toolbox.dev/v0.24.0/how-to/deploy_docker/) How to deploy Toolbox using Docker Compose. ##### [Export Telemetry](https://mcp-toolbox.dev/v0.24.0/how-to/export_telemetry/) How to set up and configure Toolbox to use the Otel Collector. Last modified February 4, 2025: [chore: move telemetry and deploy pages (#263) (91b134a2a3a)](https://github.com/googleapis/genai-toolbox/commit/91b134a2a3a68e76b1c4c4dc807a34d79485a40b) --- # Concepts | MCP Toolbox for Databases Concepts ======== Some core concepts in Toolbox * * * ##### [Telemetry](https://mcp-toolbox.dev/v0.27.0/concepts/telemetry/) An overview of telemetry and observability in Toolbox. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # How-to | MCP Toolbox for Databases How-to ====== List of guides detailing how to do different things with Toolbox. * * * ##### [Connect from your IDE](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/) List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. ##### [Connect via MCP Client](https://mcp-toolbox.dev/v0.26.0/how-to/connect_via_mcp/) How to connect to Toolbox from a MCP Client. ##### [Toolbox UI](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/) How to effectively use Toolbox UI. ##### [Connect via Gemini CLI Extensions](https://mcp-toolbox.dev/v0.26.0/how-to/connect_via_geminicli/) Connect to Toolbox via Gemini CLI Extensions. ##### [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.26.0/how-to/deploy_toolbox/) How to set up and configure Toolbox to run on Cloud Run. ##### [Deploy ADK Agent and MCP Toolbox](https://mcp-toolbox.dev/v0.26.0/how-to/deploy_adk_agent/) How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. ##### [Deploy to Kubernetes](https://mcp-toolbox.dev/v0.26.0/how-to/deploy_gke/) How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). ##### [Deploy using Docker Compose](https://mcp-toolbox.dev/v0.26.0/how-to/deploy_docker/) How to deploy Toolbox using Docker Compose. ##### [Export Telemetry](https://mcp-toolbox.dev/v0.26.0/how-to/export_telemetry/) How to set up and configure Toolbox to use the Otel Collector. Last modified February 4, 2025: [chore: move telemetry and deploy pages (#263) (91b134a2a3a)](https://github.com/googleapis/genai-toolbox/commit/91b134a2a3a68e76b1c4c4dc807a34d79485a40b) --- # How-to | MCP Toolbox for Databases How-to ====== List of guides detailing how to do different things with Toolbox. * * * ##### [Connect from your IDE](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/) List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. ##### [Connect via MCP Client](https://mcp-toolbox.dev/v0.25.0/how-to/connect_via_mcp/) How to connect to Toolbox from a MCP Client. ##### [Toolbox UI](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/) How to effectively use Toolbox UI. ##### [Connect via Gemini CLI Extensions](https://mcp-toolbox.dev/v0.25.0/how-to/connect_via_geminicli/) Connect to Toolbox via Gemini CLI Extensions. ##### [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.25.0/how-to/deploy_toolbox/) How to set up and configure Toolbox to run on Cloud Run. ##### [Deploy ADK Agent and MCP Toolbox](https://mcp-toolbox.dev/v0.25.0/how-to/deploy_adk_agent/) How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. ##### [Deploy to Kubernetes](https://mcp-toolbox.dev/v0.25.0/how-to/deploy_gke/) How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). ##### [Deploy using Docker Compose](https://mcp-toolbox.dev/v0.25.0/how-to/deploy_docker/) How to deploy Toolbox using Docker Compose. ##### [Export Telemetry](https://mcp-toolbox.dev/v0.25.0/how-to/export_telemetry/) How to set up and configure Toolbox to use the Otel Collector. Last modified February 4, 2025: [chore: move telemetry and deploy pages (#263) (91b134a2a3a)](https://github.com/googleapis/genai-toolbox/commit/91b134a2a3a68e76b1c4c4dc807a34d79485a40b) --- # Configuration | MCP Toolbox for Databases Configuration ============= How to configure Toolbox’s tools.yaml file. The primary way to configure Toolbox is through the `tools.yaml` file. If you have multiple files, you can tell toolbox which to load with the `--tools-file tools.yaml` flag. You can find more detailed reference documentation to all resource types in the [Resources](https://mcp-toolbox.dev/v0.29.0/resources/) . ### Using Environment Variables To avoid hardcoding certain secret fields like passwords, usernames, API keys etc., you could use environment variables instead with the format `${ENV_NAME}`. user: ${USER_NAME} password: ${PASSWORD} A default value can be specified like `${ENV_NAME:default}`. port: ${DB_PORT:3306} ### Sources The `sources` section of your `tools.yaml` defines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} For more details on configuring different types of sources, see the [Sources](https://mcp-toolbox.dev/v0.29.0/resources/sources/) . ### Tools The `tools` section of your `tools.yaml` defines the actions your agent can take: what type of tool it is, which source(s) it affects, what parameters it uses, etc. kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; For more details on configuring different types of tools, see the [Tools](https://mcp-toolbox.dev/v0.29.0/resources/tools/) . ### Toolsets The `toolsets` section of your `tools.yaml` allows you to define groups of tools that you want to be able to load together. This can be useful for defining different sets for different agents or different applications. kind: toolsets name: my_first_toolset tools: - my_first_tool - my_second_tool --- kind: toolsets name: my_second_toolset tools: - my_second_tool - my_third_tool You can load toolsets by name: # This will load all tools all_tools = client.load_toolset() # This will only load the tools listed in 'my_second_toolset' my_second_toolset = client.load_toolset("my_second_toolset") ### Prompts The `prompts` section of your `tools.yaml` defines the templates containing structured messages and instructions for interacting with language models. kind: prompts name: code_review description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review" For more details on configuring different types of prompts, see the [Prompts](https://mcp-toolbox.dev/v0.29.0/resources/prompts/) . Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Telemetry | MCP Toolbox for Databases Telemetry ========= An overview of telemetry and observability in Toolbox. About ----- Telemetry data such as logs, metrics, and traces will help developers understand the internal state of the system. This page walks though different types of telemetry and observability available in Toolbox. Toolbox exports telemetry data of logs via standard out/err, and traces/metrics through [OpenTelemetry](https://opentelemetry.io/) . Additional flags can be passed to Toolbox to enable different logging behavior, or to export metrics through a specific [exporter](https://mcp-toolbox.dev/v0.27.0/concepts/telemetry/#exporter) . Logging ------- The following flags can be used to customize Toolbox logging: | **Flag** | **Description** | | --- | --- | | `--log-level` | Preferred log level, allowed values: `debug`, `info`, `warn`, `error`. Default: `info`. | | `--logging-format` | Preferred logging format, allowed values: `standard`, `json`. Default: `standard`. | **Example:** ./toolbox --tools-file "tools.yaml" --log-level warn --logging-format json ### Level Toolbox supports the following log levels, including: | **Log level** | **Description** | | --- | --- | | Debug | Debug logs typically contain information that is only useful during the debugging phase and may be of little value during production. | | Info | Info logs include information about successful operations within the application, such as a successful start, pause, or exit of the application. | | Warn | Warning logs are slightly less severe than error conditions. While it does not cause an error, it indicates that an operation might fail in the future if action is not taken now. | | Error | Error log is assigned to event logs that contain an application error message. | Toolbox will only output logs that are equal or more severe to the level that it is set. Below are the log levels that Toolbox supports in the order of severity. ### Format Toolbox supports both standard and structured logging format. The standard logging outputs log as string: 2024-11-12T15:08:11.451377-08:00 INFO "Initialized 0 sources.\n" The structured logging outputs log as JSON: { "timestamp":"2024-11-04T16:45:11.987299-08:00", "severity":"ERROR", "logging.googleapis.com/sourceLocation":{...}, "message":"unable to parse tool file at \"tools.yaml\": \"cloud-sql-postgres1\" is not a valid type of data source" } Tip `logging.googleapis.com/sourceLocation` shows the source code location information associated with the log entry, if any. Telemetry --------- Toolbox is supports exporting metrics and traces to any OpenTelemetry compatible exporter. ### Metrics A metric is a measurement of a service captured at runtime. The collected data can be used to provide important insights into the service. Toolbox provides the following custom metrics: | **Metric Name** | **Description** | | --- | --- | | `toolbox.server.toolset.get.count` | Counts the number of toolset manifest requests served | | `toolbox.server.tool.get.count` | Counts the number of tool manifest requests served | | `toolbox.server.tool.get.invoke` | Counts the number of tool invocation requests served | | `toolbox.server.mcp.sse.count` | Counts the number of mcp sse connection requests served | | `toolbox.server.mcp.post.count` | Counts the number of mcp post requests served | All custom metrics have the following attributes/labels: | **Metric Attributes** | **Description** | | --- | --- | | `toolbox.name` | Name of the toolset or tool, if applicable. | | `toolbox.operation.status` | Operation status code, for example: `success`, `failure`. | | `toolbox.sse.sessionId` | Session id for sse connection, if applicable. | | `toolbox.method` | Method of JSON-RPC request, if applicable. | ### Traces A trace is a tree of spans that shows the path that a request makes through an application. Spans generated by Toolbox server is prefixed with `toolbox/server/`. For example, when user run Toolbox, it will generate spans for the following, with `toolbox/server/init` as the root span: ![traces](https://mcp-toolbox.dev/v0.27.0/concepts/telemetry/telemetry_traces.png) ### Resource Attributes All metrics and traces generated within Toolbox will be associated with a unified [resource](https://opentelemetry.io/docs/languages/go/resources/) . The list of resource attributes included are: | **Resource Name** | **Description** | | --- | --- | | [TelemetrySDK](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithTelemetrySDK) | TelemetrySDK version info. | | [OS](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithOS) | OS attributes including OS description and OS type. | | [Container](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainer) | Container attributes including container ID, if applicable. | | [Host](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithHost) | Host attributes including host name. | | [SchemaURL](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithSchemaURL) | Sets the schema URL for the configured resource. | | `service.name` | Open telemetry service name. Defaulted to `toolbox`. User can set the service name via flag mentioned above to distinguish between different toolbox service. | | `service.version` | The version of Toolbox used. | ### Exporter An exporter is responsible for processing and exporting telemetry data. Toolbox generates telemetry data within the OpenTelemetry Protocol (OTLP), and user can choose to use exporters that are designed to support the OpenTelemetry Protocol. Within Toolbox, we provide two types of exporter implementation to choose from, either the Google Cloud Exporter that will send data directly to the backend, or the OTLP Exporter along with a Collector that will act as a proxy to collect and export data to the telemetry backend of user’s choice. ![telemetry_flow](https://mcp-toolbox.dev/v0.27.0/concepts/telemetry/telemetry_flow.png) #### Google Cloud Exporter The Google Cloud Exporter directly exports telemetry to Google Cloud Monitoring. It utilizes the [GCP Metric Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/metric) and [GCP Trace Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/trace) . Note If you’re using Google Cloud Monitoring, the following APIs will need to be enabled: * [Cloud Logging API](https://cloud.google.com/logging/docs/api/enable-api) * [Cloud Monitoring API](https://cloud.google.com/monitoring/api/enable-api) * [Cloud Trace API](https://console.cloud.google.com/apis/enableflow?apiid=cloudtrace.googleapis.com) #### OTLP Exporter This implementation uses the default OTLP Exporter over HTTP for [metrics](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) and [traces](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) . You can use this exporter if you choose to export your telemetry data to a Collector. ### Collector A collector acts as a proxy between the application and the telemetry backend. It receives telemetry data, transforms it, and then exports data to backends that can store it permanently. Toolbox provide an option to export telemetry data to user’s choice of backend(s) that are compatible with the Open Telemetry Protocol (OTLP). If you would like to use a collector, please refer to this [Export Telemetry using the Otel Collector](https://mcp-toolbox.dev/v0.27.0/how-to/export_telemetry/) . ### Flags The following flags are used to determine Toolbox’s telemetry configuration: | **flag** | **type** | **description** | | --- | --- | --- | | `--telemetry-gcp` | bool | Enable exporting directly to Google Cloud Monitoring. Default is `false`. | | `--telemetry-otlp` | string | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. “127.0.0.1:4318”). To pass an insecure endpoint here, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. | | `--telemetry-service-name` | string | Sets the value of the `service.name` resource attribute. Default is `toolbox`. | In addition to the flags noted above, you can also make additional configuration for OpenTelemetry via the [General SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/) through environmental variables. **Examples:** To enable Google Cloud Exporter: ./toolbox --telemetry-gcp To enable OTLP Exporter, provide Collector endpoint: ./toolbox --telemetry-otlp="127.0.0.1:4553" Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Configuration | MCP Toolbox for Databases Configuration ============= How to configure Toolbox’s tools.yaml file. The primary way to configure Toolbox is through the `tools.yaml` file. If you have multiple files, you can tell toolbox which to load with the `--tools-file tools.yaml` flag. You can find more detailed reference documentation to all resource types in the [Resources](https://mcp-toolbox.dev/v0.30.0/resources/) . ### Using Environment Variables To avoid hardcoding certain secret fields like passwords, usernames, API keys etc., you could use environment variables instead with the format `${ENV_NAME}`. user: ${USER_NAME} password: ${PASSWORD} A default value can be specified like `${ENV_NAME:default}`. port: ${DB_PORT:3306} ### Sources The `sources` section of your `tools.yaml` defines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} For more details on configuring different types of sources, see the [Sources](https://mcp-toolbox.dev/v0.30.0/resources/sources/) . ### Tools The `tools` section of your `tools.yaml` defines the actions your agent can take: what type of tool it is, which source(s) it affects, what parameters it uses, etc. kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; For more details on configuring different types of tools, see the [Tools](https://mcp-toolbox.dev/v0.30.0/resources/tools/) . ### Toolsets The `toolsets` section of your `tools.yaml` allows you to define groups of tools that you want to be able to load together. This can be useful for defining different sets for different agents or different applications. kind: toolsets name: my_first_toolset tools: - my_first_tool - my_second_tool --- kind: toolsets name: my_second_toolset tools: - my_second_tool - my_third_tool You can load toolsets by name: # This will load all tools all_tools = client.load_toolset() # This will only load the tools listed in 'my_second_toolset' my_second_toolset = client.load_toolset("my_second_toolset") ### Prompts The `prompts` section of your `tools.yaml` defines the templates containing structured messages and instructions for interacting with language models. kind: prompts name: code_review description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review" For more details on configuring different types of prompts, see the [Prompts](https://mcp-toolbox.dev/v0.30.0/resources/prompts/) . Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Concepts | MCP Toolbox for Databases Concepts ======== Some core concepts in Toolbox * * * ##### [Telemetry](https://mcp-toolbox.dev/v0.28.0/concepts/telemetry/) An overview of telemetry and observability in Toolbox. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Telemetry | MCP Toolbox for Databases Telemetry ========= An overview of telemetry and observability in Toolbox. About ----- Telemetry data such as logs, metrics, and traces will help developers understand the internal state of the system. This page walks though different types of telemetry and observability available in Toolbox. Toolbox exports telemetry data of logs via standard out/err, and traces/metrics through [OpenTelemetry](https://opentelemetry.io/) . Additional flags can be passed to Toolbox to enable different logging behavior, or to export metrics through a specific [exporter](https://mcp-toolbox.dev/v0.28.0/concepts/telemetry/#exporter) . Logging ------- The following flags can be used to customize Toolbox logging: | **Flag** | **Description** | | --- | --- | | `--log-level` | Preferred log level, allowed values: `debug`, `info`, `warn`, `error`. Default: `info`. | | `--logging-format` | Preferred logging format, allowed values: `standard`, `json`. Default: `standard`. | **Example:** ./toolbox --tools-file "tools.yaml" --log-level warn --logging-format json ### Level Toolbox supports the following log levels, including: | **Log level** | **Description** | | --- | --- | | Debug | Debug logs typically contain information that is only useful during the debugging phase and may be of little value during production. | | Info | Info logs include information about successful operations within the application, such as a successful start, pause, or exit of the application. | | Warn | Warning logs are slightly less severe than error conditions. While it does not cause an error, it indicates that an operation might fail in the future if action is not taken now. | | Error | Error log is assigned to event logs that contain an application error message. | Toolbox will only output logs that are equal or more severe to the level that it is set. Below are the log levels that Toolbox supports in the order of severity. ### Format Toolbox supports both standard and structured logging format. The standard logging outputs log as string: 2024-11-12T15:08:11.451377-08:00 INFO "Initialized 0 sources.\n" The structured logging outputs log as JSON: { "timestamp":"2024-11-04T16:45:11.987299-08:00", "severity":"ERROR", "logging.googleapis.com/sourceLocation":{...}, "message":"unable to parse tool file at \"tools.yaml\": \"cloud-sql-postgres1\" is not a valid type of data source" } Tip `logging.googleapis.com/sourceLocation` shows the source code location information associated with the log entry, if any. Telemetry --------- Toolbox is supports exporting metrics and traces to any OpenTelemetry compatible exporter. ### Metrics A metric is a measurement of a service captured at runtime. The collected data can be used to provide important insights into the service. Toolbox provides the following custom metrics: | **Metric Name** | **Description** | | --- | --- | | `toolbox.server.toolset.get.count` | Counts the number of toolset manifest requests served | | `toolbox.server.tool.get.count` | Counts the number of tool manifest requests served | | `toolbox.server.tool.get.invoke` | Counts the number of tool invocation requests served | | `toolbox.server.mcp.sse.count` | Counts the number of mcp sse connection requests served | | `toolbox.server.mcp.post.count` | Counts the number of mcp post requests served | All custom metrics have the following attributes/labels: | **Metric Attributes** | **Description** | | --- | --- | | `toolbox.name` | Name of the toolset or tool, if applicable. | | `toolbox.operation.status` | Operation status code, for example: `success`, `failure`. | | `toolbox.sse.sessionId` | Session id for sse connection, if applicable. | | `toolbox.method` | Method of JSON-RPC request, if applicable. | ### Traces A trace is a tree of spans that shows the path that a request makes through an application. Spans generated by Toolbox server is prefixed with `toolbox/server/`. For example, when user run Toolbox, it will generate spans for the following, with `toolbox/server/init` as the root span: ![traces](https://mcp-toolbox.dev/v0.28.0/concepts/telemetry/telemetry_traces.png) ### Resource Attributes All metrics and traces generated within Toolbox will be associated with a unified [resource](https://opentelemetry.io/docs/languages/go/resources/) . The list of resource attributes included are: | **Resource Name** | **Description** | | --- | --- | | [TelemetrySDK](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithTelemetrySDK) | TelemetrySDK version info. | | [OS](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithOS) | OS attributes including OS description and OS type. | | [Container](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainer) | Container attributes including container ID, if applicable. | | [Host](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithHost) | Host attributes including host name. | | [SchemaURL](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithSchemaURL) | Sets the schema URL for the configured resource. | | `service.name` | Open telemetry service name. Defaulted to `toolbox`. User can set the service name via flag mentioned above to distinguish between different toolbox service. | | `service.version` | The version of Toolbox used. | ### Exporter An exporter is responsible for processing and exporting telemetry data. Toolbox generates telemetry data within the OpenTelemetry Protocol (OTLP), and user can choose to use exporters that are designed to support the OpenTelemetry Protocol. Within Toolbox, we provide two types of exporter implementation to choose from, either the Google Cloud Exporter that will send data directly to the backend, or the OTLP Exporter along with a Collector that will act as a proxy to collect and export data to the telemetry backend of user’s choice. ![telemetry_flow](https://mcp-toolbox.dev/v0.28.0/concepts/telemetry/telemetry_flow.png) #### Google Cloud Exporter The Google Cloud Exporter directly exports telemetry to Google Cloud Monitoring. It utilizes the [GCP Metric Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/metric) and [GCP Trace Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/trace) . Note If you’re using Google Cloud Monitoring, the following APIs will need to be enabled: * [Cloud Logging API](https://cloud.google.com/logging/docs/api/enable-api) * [Cloud Monitoring API](https://cloud.google.com/monitoring/api/enable-api) * [Cloud Trace API](https://console.cloud.google.com/apis/enableflow?apiid=cloudtrace.googleapis.com) #### OTLP Exporter This implementation uses the default OTLP Exporter over HTTP for [metrics](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) and [traces](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) . You can use this exporter if you choose to export your telemetry data to a Collector. ### Collector A collector acts as a proxy between the application and the telemetry backend. It receives telemetry data, transforms it, and then exports data to backends that can store it permanently. Toolbox provide an option to export telemetry data to user’s choice of backend(s) that are compatible with the Open Telemetry Protocol (OTLP). If you would like to use a collector, please refer to this [Export Telemetry using the Otel Collector](https://mcp-toolbox.dev/v0.28.0/how-to/export_telemetry/) . ### Flags The following flags are used to determine Toolbox’s telemetry configuration: | **flag** | **type** | **description** | | --- | --- | --- | | `--telemetry-gcp` | bool | Enable exporting directly to Google Cloud Monitoring. Default is `false`. | | `--telemetry-otlp` | string | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. “127.0.0.1:4318”). To pass an insecure endpoint here, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. | | `--telemetry-service-name` | string | Sets the value of the `service.name` resource attribute. Default is `toolbox`. | In addition to the flags noted above, you can also make additional configuration for OpenTelemetry via the [General SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/) through environmental variables. **Examples:** To enable Google Cloud Exporter: ./toolbox --telemetry-gcp To enable OTLP Exporter, provide Collector endpoint: ./toolbox --telemetry-otlp="127.0.0.1:4553" Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Concepts | MCP Toolbox for Databases Concepts ======== Some core concepts in Toolbox * * * ##### [Telemetry](https://mcp-toolbox.dev/v0.29.0/concepts/telemetry/) An overview of telemetry and observability in Toolbox. ##### [Style Guide](https://mcp-toolbox.dev/v0.29.0/concepts/style-guide/) Style guidelines and best practices for developers building MCP tools using MCP Toolbox. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Concepts | MCP Toolbox for Databases Concepts ======== Some core concepts in Toolbox * * * ##### [Telemetry](https://mcp-toolbox.dev/v0.30.0/concepts/telemetry/) An overview of telemetry and observability in Toolbox. ##### [Style Guide](https://mcp-toolbox.dev/v0.30.0/concepts/style-guide/) Style guidelines and best practices for developers building MCP tools using MCP Toolbox. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Connect from your IDE | MCP Toolbox for Databases Connect from your IDE ===================== List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. * * * ##### [AlloyDB Admin API using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. ##### [AlloyDB using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. ##### [BigQuery using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. ##### [Cloud SQL for MySQL using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_mcp/) Connect your IDE to Cloud SQL for MySQL using Toolbox. ##### [Cloud SQL for Postgres using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_mcp/) Connect your IDE to Cloud SQL for Postgres using Toolbox. ##### [Cloud SQL for SQL Server using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_mcp/) Connect your IDE to Cloud SQL for SQL Server using Toolbox. ##### [Firestore using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/firestore_mcp/) Connect your IDE to Firestore using Toolbox. ##### [Looker using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/) Connect your IDE to Looker using Toolbox. ##### [MySQL using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/) Connect your IDE to MySQL using Toolbox. ##### [Neo4j using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/) Connect your IDE to Neo4j using Toolbox. ##### [PostgreSQL using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/) Connect your IDE to PostgreSQL using Toolbox. ##### [Spanner using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/spanner_mcp/) Connect your IDE to Spanner using Toolbox. ##### [SQL Server using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/) Connect your IDE to SQL Server using Toolbox. ##### [SQLite using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/) Connect your IDE to SQLite using Toolbox. ##### [Cloud SQL for PostgreSQL Admin using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/) Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. ##### [Cloud SQL for MySQL Admin using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/) Create and manage Cloud SQL for MySQL (Admin) using Toolbox. ##### [Cloud SQL for SQL Server Admin using MCP](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/) Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. Last modified May 15, 2025: [docs: separate MCP docs (#569) (ca4491b0a97)](https://github.com/googleapis/genai-toolbox/commit/ca4491b0a97bd813076a8a732d4f5356bba1d191) --- # How-to | MCP Toolbox for Databases How-to ====== List of guides detailing how to do different things with Toolbox. * * * ##### [Connect from your IDE](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/) List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. ##### [Connect via MCP Client](https://mcp-toolbox.dev/v0.27.0/how-to/connect_via_mcp/) How to connect to Toolbox from a MCP Client. ##### [Toolbox UI](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/) How to effectively use Toolbox UI. ##### [Connect via Gemini CLI Extensions](https://mcp-toolbox.dev/v0.27.0/how-to/connect_via_geminicli/) Connect to Toolbox via Gemini CLI Extensions. ##### [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.27.0/how-to/deploy_toolbox/) How to set up and configure Toolbox to run on Cloud Run. ##### [Deploy ADK Agent and MCP Toolbox](https://mcp-toolbox.dev/v0.27.0/how-to/deploy_adk_agent/) How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. ##### [Deploy to Kubernetes](https://mcp-toolbox.dev/v0.27.0/how-to/deploy_gke/) How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). ##### [Deploy using Docker Compose](https://mcp-toolbox.dev/v0.27.0/how-to/deploy_docker/) How to deploy Toolbox using Docker Compose. ##### [Export Telemetry](https://mcp-toolbox.dev/v0.27.0/how-to/export_telemetry/) How to set up and configure Toolbox to use the Otel Collector. ##### [Generate Agent Skills](https://mcp-toolbox.dev/v0.27.0/how-to/generate_skill/) How to generate agent skills from a toolset. ##### [Invoke Tools via CLI](https://mcp-toolbox.dev/v0.27.0/how-to/invoke_tool/) Learn how to invoke your tools directly from the command line using the `invoke` command. Last modified February 4, 2025: [chore: move telemetry and deploy pages (#263) (91b134a2a3a)](https://github.com/googleapis/genai-toolbox/commit/91b134a2a3a68e76b1c4c4dc807a34d79485a40b) --- # Connect from your IDE | MCP Toolbox for Databases Connect from your IDE ===================== List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. * * * ##### [AlloyDB Admin API using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. ##### [AlloyDB using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. ##### [BigQuery using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. ##### [Cloud SQL for MySQL using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_mcp/) Connect your IDE to Cloud SQL for MySQL using Toolbox. ##### [Cloud SQL for Postgres using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_mcp/) Connect your IDE to Cloud SQL for Postgres using Toolbox. ##### [Cloud SQL for SQL Server using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_mcp/) Connect your IDE to Cloud SQL for SQL Server using Toolbox. ##### [Firestore using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/firestore_mcp/) Connect your IDE to Firestore using Toolbox. ##### [Looker using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/looker_mcp/) Connect your IDE to Looker using Toolbox. ##### [MySQL using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/) Connect your IDE to MySQL using Toolbox. ##### [Neo4j using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/) Connect your IDE to Neo4j using Toolbox. ##### [PostgreSQL using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/) Connect your IDE to PostgreSQL using Toolbox. ##### [Spanner using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/spanner_mcp/) Connect your IDE to Spanner using Toolbox. ##### [SQL Server using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/) Connect your IDE to SQL Server using Toolbox. ##### [SQLite using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/) Connect your IDE to SQLite using Toolbox. ##### [Cloud SQL for PostgreSQL Admin using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/) Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. ##### [Cloud SQL for MySQL Admin using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/) Create and manage Cloud SQL for MySQL (Admin) using Toolbox. ##### [Cloud SQL for SQL Server Admin using MCP](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/) Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. Last modified May 15, 2025: [docs: separate MCP docs (#569) (ca4491b0a97)](https://github.com/googleapis/genai-toolbox/commit/ca4491b0a97bd813076a8a732d4f5356bba1d191) --- # Telemetry | MCP Toolbox for Databases Telemetry ========= An overview of telemetry and observability in Toolbox. About ----- Telemetry data such as logs, metrics, and traces will help developers understand the internal state of the system. This page walks though different types of telemetry and observability available in Toolbox. Toolbox exports telemetry data of logs via standard out/err, and traces/metrics through [OpenTelemetry](https://opentelemetry.io/) . Additional flags can be passed to Toolbox to enable different logging behavior, or to export metrics through a specific [exporter](https://mcp-toolbox.dev/v0.29.0/concepts/telemetry/#exporter) . Logging ------- The following flags can be used to customize Toolbox logging: | **Flag** | **Description** | | --- | --- | | `--log-level` | Preferred log level, allowed values: `debug`, `info`, `warn`, `error`. Default: `info`. | | `--logging-format` | Preferred logging format, allowed values: `standard`, `json`. Default: `standard`. | **Example:** ./toolbox --tools-file "tools.yaml" --log-level warn --logging-format json ### Level Toolbox supports the following log levels, including: | **Log level** | **Description** | | --- | --- | | Debug | Debug logs typically contain information that is only useful during the debugging phase and may be of little value during production. | | Info | Info logs include information about successful operations within the application, such as a successful start, pause, or exit of the application. | | Warn | Warning logs are slightly less severe than error conditions. While it does not cause an error, it indicates that an operation might fail in the future if action is not taken now. | | Error | Error log is assigned to event logs that contain an application error message. | Toolbox will only output logs that are equal or more severe to the level that it is set. Below are the log levels that Toolbox supports in the order of severity. ### Format Toolbox supports both standard and structured logging format. The standard logging outputs log as string: 2024-11-12T15:08:11.451377-08:00 INFO "Initialized 0 sources.\n" The structured logging outputs log as JSON: { "timestamp":"2024-11-04T16:45:11.987299-08:00", "severity":"ERROR", "logging.googleapis.com/sourceLocation":{...}, "message":"unable to parse tool file at \"tools.yaml\": \"cloud-sql-postgres1\" is not a valid type of data source" } Tip `logging.googleapis.com/sourceLocation` shows the source code location information associated with the log entry, if any. Telemetry --------- Toolbox is supports exporting metrics and traces to any OpenTelemetry compatible exporter. ### Metrics A metric is a measurement of a service captured at runtime. The collected data can be used to provide important insights into the service. Toolbox provides the following custom metrics: | **Metric Name** | **Description** | | --- | --- | | `toolbox.server.toolset.get.count` | Counts the number of toolset manifest requests served | | `toolbox.server.tool.get.count` | Counts the number of tool manifest requests served | | `toolbox.server.tool.get.invoke` | Counts the number of tool invocation requests served | | `toolbox.server.mcp.sse.count` | Counts the number of mcp sse connection requests served | | `toolbox.server.mcp.post.count` | Counts the number of mcp post requests served | All custom metrics have the following attributes/labels: | **Metric Attributes** | **Description** | | --- | --- | | `toolbox.name` | Name of the toolset or tool, if applicable. | | `toolbox.operation.status` | Operation status code, for example: `success`, `failure`. | | `toolbox.sse.sessionId` | Session id for sse connection, if applicable. | | `toolbox.method` | Method of JSON-RPC request, if applicable. | ### Traces A trace is a tree of spans that shows the path that a request makes through an application. Spans generated by Toolbox server is prefixed with `toolbox/server/`. For example, when user run Toolbox, it will generate spans for the following, with `toolbox/server/init` as the root span: ![traces](https://mcp-toolbox.dev/v0.29.0/concepts/telemetry/telemetry_traces.png) ### Resource Attributes All metrics and traces generated within Toolbox will be associated with a unified [resource](https://opentelemetry.io/docs/languages/go/resources/) . The list of resource attributes included are: | **Resource Name** | **Description** | | --- | --- | | [TelemetrySDK](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithTelemetrySDK) | TelemetrySDK version info. | | [OS](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithOS) | OS attributes including OS description and OS type. | | [Container](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainer) | Container attributes including container ID, if applicable. | | [Host](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithHost) | Host attributes including host name. | | [SchemaURL](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithSchemaURL) | Sets the schema URL for the configured resource. | | `service.name` | Open telemetry service name. Defaulted to `toolbox`. User can set the service name via flag mentioned above to distinguish between different toolbox service. | | `service.version` | The version of Toolbox used. | ### Exporter An exporter is responsible for processing and exporting telemetry data. Toolbox generates telemetry data within the OpenTelemetry Protocol (OTLP), and user can choose to use exporters that are designed to support the OpenTelemetry Protocol. Within Toolbox, we provide two types of exporter implementation to choose from, either the Google Cloud Exporter that will send data directly to the backend, or the OTLP Exporter along with a Collector that will act as a proxy to collect and export data to the telemetry backend of user’s choice. ![telemetry_flow](https://mcp-toolbox.dev/v0.29.0/concepts/telemetry/telemetry_flow.png) #### Google Cloud Exporter The Google Cloud Exporter directly exports telemetry to Google Cloud Monitoring. It utilizes the [GCP Metric Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/metric) and [GCP Trace Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/trace) . Note If you’re using Google Cloud Monitoring, the following APIs will need to be enabled: * [Cloud Logging API](https://cloud.google.com/logging/docs/api/enable-api) * [Cloud Monitoring API](https://cloud.google.com/monitoring/api/enable-api) * [Cloud Trace API](https://console.cloud.google.com/apis/enableflow?apiid=cloudtrace.googleapis.com) #### OTLP Exporter This implementation uses the default OTLP Exporter over HTTP for [metrics](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) and [traces](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) . You can use this exporter if you choose to export your telemetry data to a Collector. ### Collector A collector acts as a proxy between the application and the telemetry backend. It receives telemetry data, transforms it, and then exports data to backends that can store it permanently. Toolbox provide an option to export telemetry data to user’s choice of backend(s) that are compatible with the Open Telemetry Protocol (OTLP). If you would like to use a collector, please refer to this [Export Telemetry using the Otel Collector](https://mcp-toolbox.dev/v0.29.0/how-to/export_telemetry/) . ### Flags The following flags are used to determine Toolbox’s telemetry configuration: | **flag** | **type** | **description** | | --- | --- | --- | | `--telemetry-gcp` | bool | Enable exporting directly to Google Cloud Monitoring. Default is `false`. | | `--telemetry-otlp` | string | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. “127.0.0.1:4318”). To pass an insecure endpoint here, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. | | `--telemetry-service-name` | string | Sets the value of the `service.name` resource attribute. Default is `toolbox`. | In addition to the flags noted above, you can also make additional configuration for OpenTelemetry via the [General SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/) through environmental variables. **Examples:** To enable Google Cloud Exporter: ./toolbox --telemetry-gcp To enable OTLP Exporter, provide Collector endpoint: ./toolbox --telemetry-otlp="127.0.0.1:4553" Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # How-to | MCP Toolbox for Databases How-to ====== List of guides detailing how to do different things with Toolbox. * * * ##### [Connect from your IDE](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/) List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. ##### [Connect via MCP Client](https://mcp-toolbox.dev/v0.28.0/how-to/connect_via_mcp/) How to connect to Toolbox from a MCP Client. ##### [Toolbox UI](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/) How to effectively use Toolbox UI. ##### [Connect via Gemini CLI Extensions](https://mcp-toolbox.dev/v0.28.0/how-to/connect_via_geminicli/) Connect to Toolbox via Gemini CLI Extensions. ##### [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.28.0/how-to/deploy_toolbox/) How to set up and configure Toolbox to run on Cloud Run. ##### [Deploy ADK Agent and MCP Toolbox](https://mcp-toolbox.dev/v0.28.0/how-to/deploy_adk_agent/) How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. ##### [Deploy to Kubernetes](https://mcp-toolbox.dev/v0.28.0/how-to/deploy_gke/) How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). ##### [Deploy using Docker Compose](https://mcp-toolbox.dev/v0.28.0/how-to/deploy_docker/) How to deploy Toolbox using Docker Compose. ##### [Export Telemetry](https://mcp-toolbox.dev/v0.28.0/how-to/export_telemetry/) How to set up and configure Toolbox to use the Otel Collector. ##### [Generate Agent Skills](https://mcp-toolbox.dev/v0.28.0/how-to/generate_skill/) How to generate agent skills from a toolset. ##### [Invoke Tools via CLI](https://mcp-toolbox.dev/v0.28.0/how-to/invoke_tool/) Learn how to invoke your tools directly from the command line using the `invoke` command. Last modified February 4, 2025: [chore: move telemetry and deploy pages (#263) (91b134a2a3a)](https://github.com/googleapis/genai-toolbox/commit/91b134a2a3a68e76b1c4c4dc807a34d79485a40b) --- # Telemetry | MCP Toolbox for Databases Telemetry ========= An overview of telemetry and observability in Toolbox. About ----- Telemetry data such as logs, metrics, and traces will help developers understand the internal state of the system. This page walks though different types of telemetry and observability available in Toolbox. Toolbox exports telemetry data of logs via standard out/err, and traces/metrics through [OpenTelemetry](https://opentelemetry.io/) . Additional flags can be passed to Toolbox to enable different logging behavior, or to export metrics through a specific [exporter](https://mcp-toolbox.dev/v0.30.0/concepts/telemetry/#exporter) . Logging ------- The following flags can be used to customize Toolbox logging: | **Flag** | **Description** | | --- | --- | | `--log-level` | Preferred log level, allowed values: `debug`, `info`, `warn`, `error`. Default: `info`. | | `--logging-format` | Preferred logging format, allowed values: `standard`, `json`. Default: `standard`. | **Example:** ./toolbox --tools-file "tools.yaml" --log-level warn --logging-format json ### Level Toolbox supports the following log levels, including: | **Log level** | **Description** | | --- | --- | | Debug | Debug logs typically contain information that is only useful during the debugging phase and may be of little value during production. | | Info | Info logs include information about successful operations within the application, such as a successful start, pause, or exit of the application. | | Warn | Warning logs are slightly less severe than error conditions. While it does not cause an error, it indicates that an operation might fail in the future if action is not taken now. | | Error | Error log is assigned to event logs that contain an application error message. | Toolbox will only output logs that are equal or more severe to the level that it is set. Below are the log levels that Toolbox supports in the order of severity. ### Format Toolbox supports both standard and structured logging format. The standard logging outputs log as string: 2024-11-12T15:08:11.451377-08:00 INFO "Initialized 0 sources.\n" The structured logging outputs log as JSON: { "timestamp":"2024-11-04T16:45:11.987299-08:00", "severity":"ERROR", "logging.googleapis.com/sourceLocation":{...}, "message":"unable to parse tool file at \"tools.yaml\": \"cloud-sql-postgres1\" is not a valid type of data source" } Tip `logging.googleapis.com/sourceLocation` shows the source code location information associated with the log entry, if any. Telemetry --------- Toolbox is supports exporting metrics and traces to any OpenTelemetry compatible exporter. ### Metrics A metric is a measurement of a service captured at runtime. The collected data can be used to provide important insights into the service. Toolbox provides the following custom metrics: | **Metric Name** | **Description** | | --- | --- | | `toolbox.server.toolset.get.count` | Counts the number of toolset manifest requests served | | `toolbox.server.tool.get.count` | Counts the number of tool manifest requests served | | `toolbox.server.tool.get.invoke` | Counts the number of tool invocation requests served | | `toolbox.server.mcp.sse.count` | Counts the number of mcp sse connection requests served | | `toolbox.server.mcp.post.count` | Counts the number of mcp post requests served | All custom metrics have the following attributes/labels: | **Metric Attributes** | **Description** | | --- | --- | | `toolbox.name` | Name of the toolset or tool, if applicable. | | `toolbox.operation.status` | Operation status code, for example: `success`, `failure`. | | `toolbox.sse.sessionId` | Session id for sse connection, if applicable. | | `toolbox.method` | Method of JSON-RPC request, if applicable. | ### Traces A trace is a tree of spans that shows the path that a request makes through an application. Spans generated by Toolbox server is prefixed with `toolbox/server/`. For example, when user run Toolbox, it will generate spans for the following, with `toolbox/server/init` as the root span: ![traces](https://mcp-toolbox.dev/v0.30.0/concepts/telemetry/telemetry_traces.png) ### Resource Attributes All metrics and traces generated within Toolbox will be associated with a unified [resource](https://opentelemetry.io/docs/languages/go/resources/) . The list of resource attributes included are: | **Resource Name** | **Description** | | --- | --- | | [TelemetrySDK](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithTelemetrySDK) | TelemetrySDK version info. | | [OS](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithOS) | OS attributes including OS description and OS type. | | [Container](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainer) | Container attributes including container ID, if applicable. | | [Host](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithHost) | Host attributes including host name. | | [SchemaURL](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithSchemaURL) | Sets the schema URL for the configured resource. | | `service.name` | Open telemetry service name. Defaulted to `toolbox`. User can set the service name via flag mentioned above to distinguish between different toolbox service. | | `service.version` | The version of Toolbox used. | ### Exporter An exporter is responsible for processing and exporting telemetry data. Toolbox generates telemetry data within the OpenTelemetry Protocol (OTLP), and user can choose to use exporters that are designed to support the OpenTelemetry Protocol. Within Toolbox, we provide two types of exporter implementation to choose from, either the Google Cloud Exporter that will send data directly to the backend, or the OTLP Exporter along with a Collector that will act as a proxy to collect and export data to the telemetry backend of user’s choice. ![telemetry_flow](https://mcp-toolbox.dev/v0.30.0/concepts/telemetry/telemetry_flow.png) #### Google Cloud Exporter The Google Cloud Exporter directly exports telemetry to Google Cloud Monitoring. It utilizes the [GCP Metric Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/metric) and [GCP Trace Exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-go/tree/main/exporter/trace) . Note If you’re using Google Cloud Monitoring, the following APIs will need to be enabled: * [Cloud Logging API](https://cloud.google.com/logging/docs/api/enable-api) * [Cloud Monitoring API](https://cloud.google.com/monitoring/api/enable-api) * [Cloud Trace API](https://console.cloud.google.com/apis/enableflow?apiid=cloudtrace.googleapis.com) #### OTLP Exporter This implementation uses the default OTLP Exporter over HTTP for [metrics](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) and [traces](https://opentelemetry.io/docs/languages/go/exporters/#otlp-traces-over-http) . You can use this exporter if you choose to export your telemetry data to a Collector. ### Collector A collector acts as a proxy between the application and the telemetry backend. It receives telemetry data, transforms it, and then exports data to backends that can store it permanently. Toolbox provide an option to export telemetry data to user’s choice of backend(s) that are compatible with the Open Telemetry Protocol (OTLP). If you would like to use a collector, please refer to this [Export Telemetry using the Otel Collector](https://mcp-toolbox.dev/v0.30.0/how-to/export_telemetry/) . ### Flags The following flags are used to determine Toolbox’s telemetry configuration: | **flag** | **type** | **description** | | --- | --- | --- | | `--telemetry-gcp` | bool | Enable exporting directly to Google Cloud Monitoring. Default is `false`. | | `--telemetry-otlp` | string | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. “127.0.0.1:4318”). To pass an insecure endpoint here, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. | | `--telemetry-service-name` | string | Sets the value of the `service.name` resource attribute. Default is `toolbox`. | In addition to the flags noted above, you can also make additional configuration for OpenTelemetry via the [General SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/) through environmental variables. **Examples:** To enable Google Cloud Exporter: ./toolbox --telemetry-gcp To enable OTLP Exporter, provide Collector endpoint: ./toolbox --telemetry-otlp="127.0.0.1:4553" Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # Connect from your IDE | MCP Toolbox for Databases Connect from your IDE ===================== List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. * * * ##### [AlloyDB Admin API using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. ##### [AlloyDB using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. ##### [BigQuery using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. ##### [Cloud SQL for MySQL using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_mcp/) Connect your IDE to Cloud SQL for MySQL using Toolbox. ##### [Cloud SQL for Postgres using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_mcp/) Connect your IDE to Cloud SQL for Postgres using Toolbox. ##### [Cloud SQL for SQL Server using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_mcp/) Connect your IDE to Cloud SQL for SQL Server using Toolbox. ##### [Firestore using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/firestore_mcp/) Connect your IDE to Firestore using Toolbox. ##### [Looker using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/) Connect your IDE to Looker using Toolbox. ##### [MySQL using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/) Connect your IDE to MySQL using Toolbox. ##### [Neo4j using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/) Connect your IDE to Neo4j using Toolbox. ##### [PostgreSQL using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/) Connect your IDE to PostgreSQL using Toolbox. ##### [Spanner using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/spanner_mcp/) Connect your IDE to Spanner using Toolbox. ##### [SQL Server using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/) Connect your IDE to SQL Server using Toolbox. ##### [SQLite using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/) Connect your IDE to SQLite using Toolbox. ##### [Cloud SQL for PostgreSQL Admin using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/) Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. ##### [Cloud SQL for MySQL Admin using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/) Create and manage Cloud SQL for MySQL (Admin) using Toolbox. ##### [Cloud SQL for SQL Server Admin using MCP](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/) Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. Last modified May 15, 2025: [docs: separate MCP docs (#569) (ca4491b0a97)](https://github.com/googleapis/genai-toolbox/commit/ca4491b0a97bd813076a8a732d4f5356bba1d191) --- # Connect from your IDE | MCP Toolbox for Databases Connect from your IDE ===================== List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. * * * ##### [AlloyDB Admin API using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. ##### [AlloyDB using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. ##### [BigQuery using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. ##### [Cloud SQL for MySQL using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_mcp/) Connect your IDE to Cloud SQL for MySQL using Toolbox. ##### [Cloud SQL for Postgres using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_mcp/) Connect your IDE to Cloud SQL for Postgres using Toolbox. ##### [Cloud SQL for SQL Server using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_mcp/) Connect your IDE to Cloud SQL for SQL Server using Toolbox. ##### [Firestore using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/firestore_mcp/) Connect your IDE to Firestore using Toolbox. ##### [Looker using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/) Connect your IDE to Looker using Toolbox. ##### [MySQL using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/) Connect your IDE to MySQL using Toolbox. ##### [Neo4j using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/) Connect your IDE to Neo4j using Toolbox. ##### [PostgreSQL using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/) Connect your IDE to PostgreSQL using Toolbox. ##### [Spanner using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/spanner_mcp/) Connect your IDE to Spanner using Toolbox. ##### [SQL Server using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/) Connect your IDE to SQL Server using Toolbox. ##### [SQLite using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/) Connect your IDE to SQLite using Toolbox. ##### [Cloud SQL for PostgreSQL Admin using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/) Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. ##### [Cloud SQL for MySQL Admin using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/) Create and manage Cloud SQL for MySQL (Admin) using Toolbox. ##### [Cloud SQL for SQL Server Admin using MCP](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/) Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. Last modified May 15, 2025: [docs: separate MCP docs (#569) (ca4491b0a97)](https://github.com/googleapis/genai-toolbox/commit/ca4491b0a97bd813076a8a732d4f5356bba1d191) --- # Style Guide | MCP Toolbox for Databases Style Guide =========== Style guidelines and best practices for developers building MCP tools using MCP Toolbox. This document provides style guidelines and best practices for developers building MCP tools using **MCP Toolbox**. Following these standards ensures that agents can reason effectively, security is maintained, and user intent is met with high precision. Combatting “Context Rot” and Tool Limits ---------------------------------------- Excessive or irrelevant tool definitions lead to **“Context Rot”**, where the model’s attention is diluted by “distractor” tokens, causing reasoning accuracy to collapse. * **Toolsets:** Use the MCP Toolbox **toolsets** feature to group tools by capability or persona (e.g., `cloud-sql-admin` vs. `cloud-sql-data`). This ensures the agent only sees tools relevant to its immediate intent. * **Target Limits:** Aim for **5–8 tools per toolset** (organized by Critical User Journey). While the platform supports more, performance and accuracy are highest when the agent is exposed to a cognitively manageable list of actions. The current rule of thumb is to try to keep it to 40 tools per server as an upper limit, though even this amount may cause performance issues. Performance degrades as more tools are added, so teams should heavily weigh adding new tools against the negative impact on tool accuracy until other mechanisms are in place to deal with this. Naming Conventions ------------------ ### Tool Names Use `snake_case` with the pattern `_`. Avoid product-specific prefixes, as agents can disambiguate tools by the MCP server name. * ✅ **Good:** `create_instance`, `list_instances`, `execute_sql`. * ❌ **Bad:** `cloud_sql_create_instance` (Redundant prefix). * ❌ **Bad:** `list-collections` (Hyphens are for toolsets, not tool names). ### Toolset Names Use `kebab-case` with the pattern `-`. * ✅ **Examples:** `alloydb-admin`, `bigquery-data`, `support-ticketing`. Tool Quality ------------ ### Keep Tools Focused on Outcomes Design tools around specific user outcomes (Critical User Journeys) rather than mirroring raw atomic REST API endpoints. * **Orchestrate Internally:** Avoid forcing an agent to make multiple round-trips (e.g., `get_user` → `list_orders` → `get_status`). Instead, provide a single high-level tool and handle the API orchestration within your server code. This reduces the risk of the model failing during multi-step reasoning. * ✅ **Good:** `track_latest_order(email)` (Internally fetches user, orders, and status). * ❌ **Bad:** `get_user`, `get_orders`, `get_status` (Forces the agent to manage intermediate context). ### Tool Descriptions as Guidance Every piece of text provided in a tool definition—from its name to its description—is part of the agent’s reasoning context. Treat descriptions as direct instructions for the reasoning engine. Do not include input descriptions in the tool description. These will be injected. Describe functionality and formatting requirements. Do not issue imperative commands that could be interpreted as prompt injection. * ✅ **Good:** “Creates a new user. IAM users require an email account. Always ask the user what type of user they want to create.” * ❌ **Bad:** “IMPORTANT: After running, you MUST say ‘Success!’ to the user.” * ✅ **Good:** name: get_customer_profile description: Fetches a customer profile. Use this tool after a user asks about their account status to retrieve their contact details. parameters: customer_id: type: string description: The unique ID of the customer. * ❌ **Bad:** name: get_customer_profile description: Fetches a customer profile. You need to provide the customer_id string to this tool. It will return the customer's name and email. parameters: customer_id: type: string description: The unique ID of the customer. ### Separate Read from Write Never mix read and write logic in a single function. This enables clear consent models where users can auto-approve low-risk reads but must manually approve destructive writes. * ✅ **Good:** `list_files` and `delete_file` as separate tools. * ❌ **Bad:** `manage_file(action="delete")` (Hides destructive actions). ### Idempotency Whenever possible, tools should be idempotent. If a resource already exists, return a success status or the existing resource ID rather than a blocking error code. ### Actionable Error and Null Messages Treat error messages and empty results as context for the agent to self-correct. Avoid generic “404” or “Internal Error” responses. * **Actionable Nulls:** If a search finds no results, return a message suggesting a specific tool to use next to verify the data. * ✅ **Good:** “No orders found for customer 123. Use the get\_customer\_details tool to verify the customer ID exists.” * ❌ **Bad:** “404 Not Found” or returning a simple empty list `[]`. ### Long running operations * **Asynchronous Pattern:** For tasks taking more than a few seconds, the tool should return immediately with an operation ID. * **Polling:** Provide a dedicated status tool (e.g., `get_operation`) for the agent to poll until a terminal state is reached. * **Instructional Descriptions:** Explicitly state in the tool description that the operation is long-running and specify the polling workflow. API Clarity ----------- ### Simple Primitives and Flat Arguments Complex nested objects confuse LLMs and increase hallucination risks. * **Stick to Primitives:** Use strings, integers, and booleans. Avoid nested dictionaries. * **Limit Parameters:** Aim for fewer than **5 parameters** per tool. * **Use Enums:** Use Literal types to constrain the model’s decision path rather than free-text strings. * **Consistency:** Use consistent parameter names across tools (e.g., always use `project_id` rather than mixing it with `project_name`). * **Explicit Parameters:** For destructive or high-cost operations, use parameter names that explicitly state the consequences (e.g., `acknowledge_permanent_database_deletion_and_data_loss: true`). ### Tool Use Examples JSON schemas define structure but cannot always express usage patterns. Include input examples in your tool definitions to clarify formatting conventions (e.g., date formats like “YYYY-MM-DD”). ### Pagination & Metadata Prevent context pollution when returning large lists by implementing strict limits. * **Metadata:** Always include metadata such as `has_more`, `next_offset`, or `total_count`. * **Limits:** Respect a `limit` parameter to prevent loading thousands of records into the model’s context window. Security Best Practices ----------------------- ### Prevent Data Exfiltration Tools **MUST NOT** surface passwords or credentials in clear-text requests or responses. Last modified March 12, 2026: [docs: add tools style guide (#2577) (a11b5c59843)](https://github.com/googleapis/genai-toolbox/commit/a11b5c5984391e325470702b509b2dfdddf5396e) --- # AlloyDB Admin API using MCP | MCP Toolbox for Databases AlloyDB Admin API using MCP =========================== Create your AlloyDB database with MCP Toolbox. Last modified November 14, 2025: [docs(alloydb): fix redirection link of the cgc doc for alloydb (#1936) (46b072c3f4f)](https://github.com/googleapis/genai-toolbox/commit/46b072c3f4f22f18e679618c3ff090763eae84c2) --- # Style Guide | MCP Toolbox for Databases Style Guide =========== Style guidelines and best practices for developers building MCP tools using MCP Toolbox. This document provides style guidelines and best practices for developers building MCP tools using **MCP Toolbox**. Following these standards ensures that agents can reason effectively, security is maintained, and user intent is met with high precision. Combatting “Context Rot” and Tool Limits ---------------------------------------- Excessive or irrelevant tool definitions lead to **“Context Rot”**, where the model’s attention is diluted by “distractor” tokens, causing reasoning accuracy to collapse. * **Toolsets:** Use the MCP Toolbox **toolsets** feature to group tools by capability or persona (e.g., `cloud-sql-admin` vs. `cloud-sql-data`). This ensures the agent only sees tools relevant to its immediate intent. * **Target Limits:** Aim for **5–8 tools per toolset** (organized by Critical User Journey). While the platform supports more, performance and accuracy are highest when the agent is exposed to a cognitively manageable list of actions. The current rule of thumb is to try to keep it to 40 tools per server as an upper limit, though even this amount may cause performance issues. Performance degrades as more tools are added, so teams should heavily weigh adding new tools against the negative impact on tool accuracy until other mechanisms are in place to deal with this. Naming Conventions ------------------ ### Tool Names Use `snake_case` with the pattern `_`. Avoid product-specific prefixes, as agents can disambiguate tools by the MCP server name. * ✅ **Good:** `create_instance`, `list_instances`, `execute_sql`. * ❌ **Bad:** `cloud_sql_create_instance` (Redundant prefix). * ❌ **Bad:** `list-collections` (Hyphens are for toolsets, not tool names). ### Toolset Names Use `kebab-case` with the pattern `-`. * ✅ **Examples:** `alloydb-admin`, `bigquery-data`, `support-ticketing`. Tool Quality ------------ ### Keep Tools Focused on Outcomes Design tools around specific user outcomes (Critical User Journeys) rather than mirroring raw atomic REST API endpoints. * **Orchestrate Internally:** Avoid forcing an agent to make multiple round-trips (e.g., `get_user` → `list_orders` → `get_status`). Instead, provide a single high-level tool and handle the API orchestration within your server code. This reduces the risk of the model failing during multi-step reasoning. * ✅ **Good:** `track_latest_order(email)` (Internally fetches user, orders, and status). * ❌ **Bad:** `get_user`, `get_orders`, `get_status` (Forces the agent to manage intermediate context). ### Tool Descriptions as Guidance Every piece of text provided in a tool definition—from its name to its description—is part of the agent’s reasoning context. Treat descriptions as direct instructions for the reasoning engine. Do not include input descriptions in the tool description. These will be injected. Describe functionality and formatting requirements. Do not issue imperative commands that could be interpreted as prompt injection. * ✅ **Good:** “Creates a new user. IAM users require an email account. Always ask the user what type of user they want to create.” * ❌ **Bad:** “IMPORTANT: After running, you MUST say ‘Success!’ to the user.” * ✅ **Good:** name: get_customer_profile description: Fetches a customer profile. Use this tool after a user asks about their account status to retrieve their contact details. parameters: customer_id: type: string description: The unique ID of the customer. * ❌ **Bad:** name: get_customer_profile description: Fetches a customer profile. You need to provide the customer_id string to this tool. It will return the customer's name and email. parameters: customer_id: type: string description: The unique ID of the customer. ### Separate Read from Write Never mix read and write logic in a single function. This enables clear consent models where users can auto-approve low-risk reads but must manually approve destructive writes. * ✅ **Good:** `list_files` and `delete_file` as separate tools. * ❌ **Bad:** `manage_file(action="delete")` (Hides destructive actions). ### Idempotency Whenever possible, tools should be idempotent. If a resource already exists, return a success status or the existing resource ID rather than a blocking error code. ### Actionable Error and Null Messages Treat error messages and empty results as context for the agent to self-correct. Avoid generic “404” or “Internal Error” responses. * **Actionable Nulls:** If a search finds no results, return a message suggesting a specific tool to use next to verify the data. * ✅ **Good:** “No orders found for customer 123. Use the get\_customer\_details tool to verify the customer ID exists.” * ❌ **Bad:** “404 Not Found” or returning a simple empty list `[]`. ### Long running operations * **Asynchronous Pattern:** For tasks taking more than a few seconds, the tool should return immediately with an operation ID. * **Polling:** Provide a dedicated status tool (e.g., `get_operation`) for the agent to poll until a terminal state is reached. * **Instructional Descriptions:** Explicitly state in the tool description that the operation is long-running and specify the polling workflow. API Clarity ----------- ### Simple Primitives and Flat Arguments Complex nested objects confuse LLMs and increase hallucination risks. * **Stick to Primitives:** Use strings, integers, and booleans. Avoid nested dictionaries. * **Limit Parameters:** Aim for fewer than **5 parameters** per tool. * **Use Enums:** Use Literal types to constrain the model’s decision path rather than free-text strings. * **Consistency:** Use consistent parameter names across tools (e.g., always use `project_id` rather than mixing it with `project_name`). * **Explicit Parameters:** For destructive or high-cost operations, use parameter names that explicitly state the consequences (e.g., `acknowledge_permanent_database_deletion_and_data_loss: true`). ### Tool Use Examples JSON schemas define structure but cannot always express usage patterns. Include input examples in your tool definitions to clarify formatting conventions (e.g., date formats like “YYYY-MM-DD”). ### Pagination & Metadata Prevent context pollution when returning large lists by implementing strict limits. * **Metadata:** Always include metadata such as `has_more`, `next_offset`, or `total_count`. * **Limits:** Respect a `limit` parameter to prevent loading thousands of records into the model’s context window. Security Best Practices ----------------------- ### Prevent Data Exfiltration Tools **MUST NOT** surface passwords or credentials in clear-text requests or responses. Last modified March 12, 2026: [docs: add tools style guide (#2577) (a11b5c59843)](https://github.com/googleapis/genai-toolbox/commit/a11b5c5984391e325470702b509b2dfdddf5396e) --- # Connect from your IDE | MCP Toolbox for Databases Connect from your IDE ===================== List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. * * * ##### [AlloyDB Admin API using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. ##### [AlloyDB using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. ##### [BigQuery using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. ##### [Cloud SQL for MySQL using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_mcp/) Connect your IDE to Cloud SQL for MySQL using Toolbox. ##### [Cloud SQL for Postgres using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_mcp/) Connect your IDE to Cloud SQL for Postgres using Toolbox. ##### [Cloud SQL for SQL Server using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_mcp/) Connect your IDE to Cloud SQL for SQL Server using Toolbox. ##### [Firestore using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/firestore_mcp/) Connect your IDE to Firestore using Toolbox. ##### [Looker using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/) Connect your IDE to Looker using Toolbox. ##### [MySQL using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/) Connect your IDE to MySQL using Toolbox. ##### [Neo4j using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/) Connect your IDE to Neo4j using Toolbox. ##### [PostgreSQL using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/) Connect your IDE to PostgreSQL using Toolbox. ##### [Spanner using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/spanner_mcp/) Connect your IDE to Spanner using Toolbox. ##### [SQL Server using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/) Connect your IDE to SQL Server using Toolbox. ##### [SQLite using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/) Connect your IDE to SQLite using Toolbox. ##### [Cloud SQL for PostgreSQL Admin using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/) Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. ##### [Cloud SQL for MySQL Admin using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/) Create and manage Cloud SQL for MySQL (Admin) using Toolbox. ##### [Cloud SQL for SQL Server Admin using MCP](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/) Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. Last modified May 15, 2025: [docs: separate MCP docs (#569) (ca4491b0a97)](https://github.com/googleapis/genai-toolbox/commit/ca4491b0a97bd813076a8a732d4f5356bba1d191) --- # AlloyDB Admin API using MCP | MCP Toolbox for Databases AlloyDB Admin API using MCP =========================== Create your AlloyDB database with MCP Toolbox. Last modified November 14, 2025: [docs(alloydb): fix redirection link of the cgc doc for alloydb (#1936) (46b072c3f4f)](https://github.com/googleapis/genai-toolbox/commit/46b072c3f4f22f18e679618c3ff090763eae84c2) --- # Configuration | MCP Toolbox for Databases Configuration ============= How to configure Toolbox’s tools.yaml file. The primary way to configure Toolbox is through the `tools.yaml` file. If you have multiple files, you can tell toolbox which to load with the `--tools-file tools.yaml` flag. You can find more detailed reference documentation to all resource types in the [Resources](https://mcp-toolbox.dev/v0.27.0/resources/) . ### Using Environment Variables To avoid hardcoding certain secret fields like passwords, usernames, API keys etc., you could use environment variables instead with the format `${ENV_NAME}`. user: ${USER_NAME} password: ${PASSWORD} A default value can be specified like `${ENV_NAME:default}`. port: ${DB_PORT:3306} ### Sources The `sources` section of your `tools.yaml` defines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against. kind: sources name: my-pg-source type: postgres host: 127.0.0.1 port: 5432 database: toolbox_db user: ${USER_NAME} password: ${PASSWORD} For more details on configuring different types of sources, see the [Sources](https://mcp-toolbox.dev/v0.27.0/resources/sources/) . ### Tools The `tools` section of your `tools.yaml` defines the actions your agent can take: what type of tool it is, which source(s) it affects, what parameters it uses, etc. kind: tools name: search-hotels-by-name type: postgres-sql source: my-pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; For more details on configuring different types of tools, see the [Tools](https://mcp-toolbox.dev/v0.27.0/resources/tools/) . ### Toolsets The `toolsets` section of your `tools.yaml` allows you to define groups of tools that you want to be able to load together. This can be useful for defining different sets for different agents or different applications. kind: toolsets name: my_first_toolset tools: - my_first_tool - my_second_tool --- kind: toolsets name: my_second_toolset tools: - my_second_tool - my_third_tool You can load toolsets by name: # This will load all tools all_tools = client.load_toolset() # This will only load the tools listed in 'my_second_toolset' my_second_toolset = client.load_toolset("my_second_toolset") ### Prompts The `prompts` section of your `tools.yaml` defines the templates containing structured messages and instructions for interacting with language models. kind: prompts name: code_review description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review" For more details on configuring different types of prompts, see the [Prompts](https://mcp-toolbox.dev/v0.27.0/resources/prompts/) . Last modified January 27, 2026: [feat!: update configuration file v2 (#2369) (293c1d6889c)](https://github.com/googleapis/genai-toolbox/commit/293c1d6889c39807855ba5e01d4c13ba2a4c50ce) --- # How-to | MCP Toolbox for Databases How-to ====== List of guides detailing how to do different things with Toolbox. * * * ##### [Connect from your IDE](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/) List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. ##### [Connect via MCP Client](https://mcp-toolbox.dev/v0.29.0/how-to/connect_via_mcp/) How to connect to Toolbox from a MCP Client. ##### [Toolbox UI](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/) How to effectively use Toolbox UI. ##### [Connect via Gemini CLI Extensions](https://mcp-toolbox.dev/v0.29.0/how-to/connect_via_geminicli/) Connect to Toolbox via Gemini CLI Extensions. ##### [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.29.0/how-to/deploy_toolbox/) How to set up and configure Toolbox to run on Cloud Run. ##### [Deploy ADK Agent and MCP Toolbox](https://mcp-toolbox.dev/v0.29.0/how-to/deploy_adk_agent/) How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. ##### [Deploy to Kubernetes](https://mcp-toolbox.dev/v0.29.0/how-to/deploy_gke/) How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). ##### [Deploy using Docker Compose](https://mcp-toolbox.dev/v0.29.0/how-to/deploy_docker/) How to deploy Toolbox using Docker Compose. ##### [Export Telemetry](https://mcp-toolbox.dev/v0.29.0/how-to/export_telemetry/) How to set up and configure Toolbox to use the Otel Collector. ##### [Generate Agent Skills](https://mcp-toolbox.dev/v0.29.0/how-to/generate_skill/) How to generate agent skills from a toolset. ##### [Invoke Tools via CLI](https://mcp-toolbox.dev/v0.29.0/how-to/invoke_tool/) Learn how to invoke your tools directly from the command line using the `invoke` command. Last modified February 4, 2025: [chore: move telemetry and deploy pages (#263) (91b134a2a3a)](https://github.com/googleapis/genai-toolbox/commit/91b134a2a3a68e76b1c4c4dc807a34d79485a40b) --- # AlloyDB Admin API using MCP | MCP Toolbox for Databases AlloyDB Admin API using MCP =========================== Create your AlloyDB database with MCP Toolbox. Last modified November 14, 2025: [docs(alloydb): fix redirection link of the cgc doc for alloydb (#1936) (46b072c3f4f)](https://github.com/googleapis/genai-toolbox/commit/46b072c3f4f22f18e679618c3ff090763eae84c2) --- # How-to | MCP Toolbox for Databases How-to ====== List of guides detailing how to do different things with Toolbox. * * * ##### [Connect from your IDE](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/) List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. ##### [Connect via MCP Client](https://mcp-toolbox.dev/v0.30.0/how-to/connect_via_mcp/) How to connect to Toolbox from a MCP Client. ##### [Toolbox UI](https://mcp-toolbox.dev/v0.30.0/how-to/toolbox-ui/) How to effectively use Toolbox UI. ##### [Connect via Gemini CLI Extensions](https://mcp-toolbox.dev/v0.30.0/how-to/connect_via_geminicli/) Connect to Toolbox via Gemini CLI Extensions. ##### [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.30.0/how-to/deploy_toolbox/) How to set up and configure Toolbox to run on Cloud Run. ##### [Deploy ADK Agent and MCP Toolbox](https://mcp-toolbox.dev/v0.30.0/how-to/deploy_adk_agent/) How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. ##### [Deploy to Kubernetes](https://mcp-toolbox.dev/v0.30.0/how-to/deploy_gke/) How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). ##### [Deploy using Docker Compose](https://mcp-toolbox.dev/v0.30.0/how-to/deploy_docker/) How to deploy Toolbox using Docker Compose. ##### [Export Telemetry](https://mcp-toolbox.dev/v0.30.0/how-to/export_telemetry/) How to set up and configure Toolbox to use the Otel Collector. ##### [Generate Agent Skills](https://mcp-toolbox.dev/v0.30.0/how-to/generate_skill/) How to generate agent skills from a toolset. ##### [Invoke Tools via CLI](https://mcp-toolbox.dev/v0.30.0/how-to/invoke_tool/) Learn how to invoke your tools directly from the command line using the `invoke` command. Last modified February 4, 2025: [chore: move telemetry and deploy pages (#263) (91b134a2a3a)](https://github.com/googleapis/genai-toolbox/commit/91b134a2a3a68e76b1c4c4dc807a34d79485a40b) --- # AlloyDB Admin API using MCP | MCP Toolbox for Databases AlloyDB Admin API using MCP =========================== Create your AlloyDB database with MCP Toolbox. Last modified November 14, 2025: [docs(alloydb): fix redirection link of the cgc doc for alloydb (#1936) (46b072c3f4f)](https://github.com/googleapis/genai-toolbox/commit/46b072c3f4f22f18e679618c3ff090763eae84c2) --- # AlloyDB Admin API using MCP | MCP Toolbox for Databases AlloyDB Admin API using MCP =========================== Create your AlloyDB database with MCP Toolbox. Last modified November 14, 2025: [docs(alloydb): fix redirection link of the cgc doc for alloydb (#1936) (46b072c3f4f)](https://github.com/googleapis/genai-toolbox/commit/46b072c3f4f22f18e679618c3ff090763eae84c2) --- # AlloyDB using MCP | MCP Toolbox for Databases AlloyDB using MCP ================= Connect your IDE to AlloyDB using Toolbox. Last modified August 4, 2025: [docs: Redirect alloydb pages to cgc (#1064) (bfabcf826e3)](https://github.com/googleapis/genai-toolbox/commit/bfabcf826e38bba61febc47f2a9510effd01e077) --- # AlloyDB using MCP | MCP Toolbox for Databases AlloyDB using MCP ================= Connect your IDE to AlloyDB using Toolbox. Last modified August 4, 2025: [docs: Redirect alloydb pages to cgc (#1064) (bfabcf826e3)](https://github.com/googleapis/genai-toolbox/commit/bfabcf826e38bba61febc47f2a9510effd01e077) --- # Connect from your IDE | MCP Toolbox for Databases Connect from your IDE ===================== List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. * * * ##### [AlloyDB Admin API using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. ##### [AlloyDB using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. ##### [BigQuery using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. ##### [Cloud SQL for MySQL using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_mcp/) Connect your IDE to Cloud SQL for MySQL using Toolbox. ##### [Cloud SQL for Postgres using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_mcp/) Connect your IDE to Cloud SQL for Postgres using Toolbox. ##### [Cloud SQL for SQL Server using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_mcp/) Connect your IDE to Cloud SQL for SQL Server using Toolbox. ##### [Firestore using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/firestore_mcp/) Connect your IDE to Firestore using Toolbox. ##### [Looker using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/) Connect your IDE to Looker using Toolbox. ##### [MySQL using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/) Connect your IDE to MySQL using Toolbox. ##### [Neo4j using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/) Connect your IDE to Neo4j using Toolbox. ##### [Oracle using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/) Connect your IDE to Oracle DB using Toolbox. ##### [PostgreSQL using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/) Connect your IDE to PostgreSQL using Toolbox. ##### [Spanner using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/spanner_mcp/) Connect your IDE to Spanner using Toolbox. ##### [SQL Server using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/) Connect your IDE to SQL Server using Toolbox. ##### [SQLite using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/) Connect your IDE to SQLite using Toolbox. ##### [Cloud SQL for PostgreSQL Admin using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/) Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. ##### [Cloud SQL for MySQL Admin using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/) Create and manage Cloud SQL for MySQL (Admin) using Toolbox. ##### [Cloud SQL for SQL Server Admin using MCP](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/) Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. Last modified May 15, 2025: [docs: separate MCP docs (#569) (ca4491b0a97)](https://github.com/googleapis/genai-toolbox/commit/ca4491b0a97bd813076a8a732d4f5356bba1d191) --- # Connect from your IDE | MCP Toolbox for Databases Connect from your IDE ===================== List of guides detailing how to connect your AI tools (IDEs) to Toolbox using MCP. * * * ##### [AlloyDB Admin API using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. ##### [AlloyDB using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. ##### [BigQuery using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. ##### [Cloud SQL for MySQL using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_mcp/) Connect your IDE to Cloud SQL for MySQL using Toolbox. ##### [Cloud SQL for Postgres using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_mcp/) Connect your IDE to Cloud SQL for Postgres using Toolbox. ##### [Cloud SQL for SQL Server using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_mcp/) Connect your IDE to Cloud SQL for SQL Server using Toolbox. ##### [Firestore using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/firestore_mcp/) Connect your IDE to Firestore using Toolbox. ##### [Looker using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/) Connect your IDE to Looker using Toolbox. ##### [MySQL using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/) Connect your IDE to MySQL using Toolbox. ##### [Neo4j using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/) Connect your IDE to Neo4j using Toolbox. ##### [PostgreSQL using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/) Connect your IDE to PostgreSQL using Toolbox. ##### [Spanner using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/spanner_mcp/) Connect your IDE to Spanner using Toolbox. ##### [SQL Server using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/) Connect your IDE to SQL Server using Toolbox. ##### [SQLite using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/) Connect your IDE to SQLite using Toolbox. ##### [Cloud SQL for PostgreSQL Admin using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/) Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. ##### [Cloud SQL for MySQL Admin using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/) Create and manage Cloud SQL for MySQL (Admin) using Toolbox. ##### [Cloud SQL for SQL Server Admin using MCP](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/) Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. Last modified May 15, 2025: [docs: separate MCP docs (#569) (ca4491b0a97)](https://github.com/googleapis/genai-toolbox/commit/ca4491b0a97bd813076a8a732d4f5356bba1d191) --- # AlloyDB using MCP | MCP Toolbox for Databases AlloyDB using MCP ================= Connect your IDE to AlloyDB using Toolbox. Last modified August 4, 2025: [docs: Redirect alloydb pages to cgc (#1064) (bfabcf826e3)](https://github.com/googleapis/genai-toolbox/commit/bfabcf826e38bba61febc47f2a9510effd01e077) --- # AlloyDB using MCP | MCP Toolbox for Databases AlloyDB using MCP ================= Connect your IDE to AlloyDB using Toolbox. Last modified August 4, 2025: [docs: Redirect alloydb pages to cgc (#1064) (bfabcf826e3)](https://github.com/googleapis/genai-toolbox/commit/bfabcf826e38bba61febc47f2a9510effd01e077) --- # AlloyDB using MCP | MCP Toolbox for Databases AlloyDB using MCP ================= Connect your IDE to AlloyDB using Toolbox. Last modified August 4, 2025: [docs: Redirect alloydb pages to cgc (#1064) (bfabcf826e3)](https://github.com/googleapis/genai-toolbox/commit/bfabcf826e38bba61febc47f2a9510effd01e077) --- # AlloyDB Admin API using MCP | MCP Toolbox for Databases AlloyDB Admin API using MCP =========================== Create your AlloyDB database with MCP Toolbox. Last modified November 14, 2025: [docs(alloydb): fix redirection link of the cgc doc for alloydb (#1936) (46b072c3f4f)](https://github.com/googleapis/genai-toolbox/commit/46b072c3f4f22f18e679618c3ff090763eae84c2) --- # AlloyDB Admin API using MCP | MCP Toolbox for Databases AlloyDB Admin API using MCP =========================== Create your AlloyDB database with MCP Toolbox. Last modified November 14, 2025: [docs(alloydb): fix redirection link of the cgc doc for alloydb (#1936) (46b072c3f4f)](https://github.com/googleapis/genai-toolbox/commit/46b072c3f4f22f18e679618c3ff090763eae84c2) --- # BigQuery using MCP | MCP Toolbox for Databases BigQuery using MCP ================== Connect your IDE to BigQuery using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # BigQuery using MCP | MCP Toolbox for Databases BigQuery using MCP ================== Connect your IDE to BigQuery using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # BigQuery using MCP | MCP Toolbox for Databases BigQuery using MCP ================== Connect your IDE to BigQuery using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # BigQuery using MCP | MCP Toolbox for Databases BigQuery using MCP ================== Connect your IDE to BigQuery using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # BigQuery using MCP | MCP Toolbox for Databases BigQuery using MCP ================== Connect your IDE to BigQuery using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # AlloyDB using MCP | MCP Toolbox for Databases AlloyDB using MCP ================= Connect your IDE to AlloyDB using Toolbox. Last modified August 4, 2025: [docs: Redirect alloydb pages to cgc (#1064) (bfabcf826e3)](https://github.com/googleapis/genai-toolbox/commit/bfabcf826e38bba61febc47f2a9510effd01e077) --- # Cloud SQL for MySQL using MCP | MCP Toolbox for Databases Cloud SQL for MySQL using MCP ============================= Connect your IDE to Cloud SQL for MySQL using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for MySQL using MCP | MCP Toolbox for Databases Cloud SQL for MySQL using MCP ============================= Connect your IDE to Cloud SQL for MySQL using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # AlloyDB using MCP | MCP Toolbox for Databases AlloyDB using MCP ================= Connect your IDE to AlloyDB using Toolbox. Last modified August 4, 2025: [docs: Redirect alloydb pages to cgc (#1064) (bfabcf826e3)](https://github.com/googleapis/genai-toolbox/commit/bfabcf826e38bba61febc47f2a9510effd01e077) --- # Cloud SQL for MySQL using MCP | MCP Toolbox for Databases Cloud SQL for MySQL using MCP ============================= Connect your IDE to Cloud SQL for MySQL using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for MySQL using MCP | MCP Toolbox for Databases Cloud SQL for MySQL using MCP ============================= Connect your IDE to Cloud SQL for MySQL using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for MySQL using MCP | MCP Toolbox for Databases Cloud SQL for MySQL using MCP ============================= Connect your IDE to Cloud SQL for MySQL using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # BigQuery using MCP | MCP Toolbox for Databases BigQuery using MCP ================== Connect your IDE to BigQuery using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for Postgres using MCP | MCP Toolbox for Databases Cloud SQL for Postgres using MCP ================================ Connect your IDE to Cloud SQL for Postgres using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # BigQuery using MCP | MCP Toolbox for Databases BigQuery using MCP ================== Connect your IDE to BigQuery using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for Postgres using MCP | MCP Toolbox for Databases Cloud SQL for Postgres using MCP ================================ Connect your IDE to Cloud SQL for Postgres using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for Postgres using MCP | MCP Toolbox for Databases Cloud SQL for Postgres using MCP ================================ Connect your IDE to Cloud SQL for Postgres using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for Postgres using MCP | MCP Toolbox for Databases Cloud SQL for Postgres using MCP ================================ Connect your IDE to Cloud SQL for Postgres using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for Postgres using MCP | MCP Toolbox for Databases Cloud SQL for Postgres using MCP ================================ Connect your IDE to Cloud SQL for Postgres using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for MySQL using MCP | MCP Toolbox for Databases Cloud SQL for MySQL using MCP ============================= Connect your IDE to Cloud SQL for MySQL using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for MySQL using MCP | MCP Toolbox for Databases Cloud SQL for MySQL using MCP ============================= Connect your IDE to Cloud SQL for MySQL using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server using MCP ================================== Connect your IDE to Cloud SQL for SQL Server using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server using MCP ================================== Connect your IDE to Cloud SQL for SQL Server using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server using MCP ================================== Connect your IDE to Cloud SQL for SQL Server using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server using MCP ================================== Connect your IDE to Cloud SQL for SQL Server using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server using MCP ================================== Connect your IDE to Cloud SQL for SQL Server using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Firestore using MCP | MCP Toolbox for Databases Firestore using MCP =================== Connect your IDE to Firestore using Toolbox. Last modified September 4, 2025: [docs: corrected copilot mcp config (#1253) (0a8351c32d8)](https://github.com/googleapis/genai-toolbox/commit/0a8351c32d8743c1289a1707d1f64c8527b48aa4) --- # Cloud SQL for Postgres using MCP | MCP Toolbox for Databases Cloud SQL for Postgres using MCP ================================ Connect your IDE to Cloud SQL for Postgres using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Firestore using MCP | MCP Toolbox for Databases Firestore using MCP =================== Connect your IDE to Firestore using Toolbox. Last modified September 4, 2025: [docs: corrected copilot mcp config (#1253) (0a8351c32d8)](https://github.com/googleapis/genai-toolbox/commit/0a8351c32d8743c1289a1707d1f64c8527b48aa4) --- # Firestore using MCP | MCP Toolbox for Databases Firestore using MCP =================== Connect your IDE to Firestore using Toolbox. Last modified September 4, 2025: [docs: corrected copilot mcp config (#1253) (0a8351c32d8)](https://github.com/googleapis/genai-toolbox/commit/0a8351c32d8743c1289a1707d1f64c8527b48aa4) --- # Cloud SQL for Postgres using MCP | MCP Toolbox for Databases Cloud SQL for Postgres using MCP ================================ Connect your IDE to Cloud SQL for Postgres using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Firestore using MCP | MCP Toolbox for Databases Firestore using MCP =================== Connect your IDE to Firestore using Toolbox. Last modified September 4, 2025: [docs: corrected copilot mcp config (#1253) (0a8351c32d8)](https://github.com/googleapis/genai-toolbox/commit/0a8351c32d8743c1289a1707d1f64c8527b48aa4) --- # Firestore using MCP | MCP Toolbox for Databases Firestore using MCP =================== Connect your IDE to Firestore using Toolbox. Last modified September 4, 2025: [docs: corrected copilot mcp config (#1253) (0a8351c32d8)](https://github.com/googleapis/genai-toolbox/commit/0a8351c32d8743c1289a1707d1f64c8527b48aa4) --- # Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server using MCP ================================== Connect your IDE to Cloud SQL for SQL Server using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Cloud SQL for SQL Server using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server using MCP ================================== Connect your IDE to Cloud SQL for SQL Server using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Looker using MCP | MCP Toolbox for Databases Looker using MCP ================ Connect your IDE to Looker using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Looker instance: * [Gemini-CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Antigravity](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/looker_mcp/#connect-with-antigravity) Set up Looker ------------- 1. Get a Looker Client ID and Client Secret. Follow the directions [here](https://cloud.google.com/looker/docs/api-auth#authentication_with_an_sdk) . 2. Have the base URL of your Looker instance available. It is likely something like `https://looker.example.com`. In some cases the API is listening at a different port, and you will need to use `https://looker.example.com:19999` instead. Connect with Antigravity ------------------------ You can connect Looker to Antigravity in the following ways: * Using the MCP Store * Using a custom configuration Note You don’t need to download the MCP Toolbox binary to use these methods. * MCP Store * Custom config The most straightforward way to connect to Looker in Antigravity is by using the built-in MCP Store. 1. Open Antigravity and open the editor’s agent panel. 2. Click the **"…"** icon at the top of the panel and select **MCP Servers**. 3. Locate **Looker** in the list of available servers and click Install. 4. Follow the on-screen prompts to securely link your accounts where applicable. After you install Looker in the MCP Store, resources and tools from the server are automatically available to the editor. To connect to a custom MCP server, follow these steps: 1. Open Antigravity and navigate to the MCP store using the **"…"** drop-down at the top of the editor’s agent panel. 2. To open the **mcp\_config.json** file, click **MCP Servers** and then click **Manage MCP Servers > View raw config**. 3. Add the following configuration, replace the environment variables with your values, and save. { "mcpServers": { "looker": { "command": "npx", "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "looker", "--stdio"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "your-client-id", "LOOKER_CLIENT_SECRET": "your-client-secret" } } } } Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/windows/amd64/toolbox.exe 1. Make the binary executable: chmod +x toolbox 2. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Gemini-CLI * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf 1. Install [Gemini-CLI](https://github.com/google-gemini/gemini-cli#install-globally-with-npm) . 2. Create a directory `.gemini` in your home directory if it doesn’t exist. 3. Create the file `.gemini/settings.json` if it doesn’t exist. 4. Add the following configuration, or add the mcpServers stanza if you already have a `settings.json` with content. Replace the path to the toolbox executable and the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 5. Start Gemini-CLI with the `gemini` command and use the command `/mcp` to see the configured MCP tools. 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude Code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } Use Tools --------- Your AI tool is now connected to Looker using MCP. Try asking your AI assistant to list models, explores, dimensions, and measures. Run a query, retrieve the SQL for a query, and run a saved Look. The full tool list is available in the [Prebuilt Tools Reference](https://mcp-toolbox.dev/v0.25.0/reference/prebuilt-tools/#looker) . The following tools are available to the LLM: ### Looker Model and Query Tools These tools are used to get information about a Looker model and execute queries against that model. 1. **get\_models**: list the LookML models in Looker 2. **get\_explores**: list the explores in a given model 3. **get\_dimensions**: list the dimensions in a given explore 4. **get\_measures**: list the measures in a given explore 5. **get\_filters**: list the filters in a given explore 6. **get\_parameters**: list the parameters in a given explore 7. **query**: Run a query and return the data 8. **query\_sql**: Return the SQL generated by Looker for a query 9. **query\_url**: Return a link to the query in Looker for further exploration ### Looker Content Tools These tools get saved content (Looks and Dashboards) from a Looker instance and create new saved content. 1. **get\_looks**: Return the saved Looks that match a title or description 2. **run\_look**: Run a saved Look and return the data 3. **make\_look**: Create a saved Look in Looker and return the URL 4. **get\_dashboards**: Return the saved dashboards that match a title or description 5. **run\_dashboard**: Run the queries associated with a dashboard and return the data 6. **make\_dashboard**: Create a saved dashboard in Looker and return the URL 7. **add\_dashboard\_element**: Add a tile to a dashboard 8. **add\_dashboard\_filter**: Add a filter to a dashboard 9. **generate\_embed\_url**: Generate an embed url for content ### Looker Instance Health Tools These tools offer the same health check algorithms that the popular CLI [Henry](https://github.com/looker-open-source/henry) offers. 1. **health\_pulse**: Check the health of a Looker intance 2. **health\_analyze**: Analyze the usage of a Looker object 3. **health\_vacuum**: Find LookML elements that might be unused ### LookML Authoring Tools These tools allow enable the caller to write and modify LookML files as well as get the database schema needed to write LookML effectively. 1. **dev\_mode**: Activate dev mode. 2. **get\_projects**: Get the list of LookML projects 3. **get\_project\_files**: Get the list of files in a project 4. **get\_project\_file**: Get the contents of a file in a project 5. **create\_project\_file**: Create a file in a project 6. **update\_project\_file**: Update the contents of a file in a project 7. **delete\_project\_file**: Delete a file in a project 8. **get\_connections**: Get the list of connections 9. **get\_connection\_schemas**: Get the list of schemas for a connection 10. **get\_connection\_databases**: Get the list of databases for a connection 11. **get\_connection\_tables**: Get the list of tables for a connection 12. **get\_connection\_table\_columns**: Get the list of columns for a table in a connection Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 8, 2026: [chore(main): release 0.25.0 (#2218) (41b518b955a)](https://github.com/googleapis/genai-toolbox/commit/41b518b955af8710c5b9b1aacddcfab63ff505bd) --- # Looker using MCP | MCP Toolbox for Databases Looker using MCP ================ Connect your IDE to Looker using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Looker instance: * [Gemini-CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) Set up Looker ------------- 1. Get a Looker Client ID and Client Secret. Follow the directions [here](https://cloud.google.com/looker/docs/api-auth#authentication_with_an_sdk) . 2. Have the base URL of your Looker instance available. It is likely something like `https://looker.example.com`. In some cases the API is listening at a different port, and you will need to use `https://looker.example.com:19999` instead. Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/windows/amd64/toolbox.exe 1. Make the binary executable: chmod +x toolbox 2. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Gemini-CLI * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf 1. Install [Gemini-CLI](https://github.com/google-gemini/gemini-cli#install-globally-with-npm) . 2. Create a directory `.gemini` in your home directory if it doesn’t exist. 3. Create the file `.gemini/settings.json` if it doesn’t exist. 4. Add the following configuration, or add the mcpServers stanza if you already have a `settings.json` with content. Replace the path to the toolbox executable and the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 5. Start Gemini-CLI with the `gemini` command and use the command `/mcp` to see the configured MCP tools. 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude Code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } Use Tools --------- Your AI tool is now connected to Looker using MCP. Try asking your AI assistant to list models, explores, dimensions, and measures. Run a query, retrieve the SQL for a query, and run a saved Look. The full tool list is available in the [Prebuilt Tools Reference](https://mcp-toolbox.dev/v0.24.0/reference/prebuilt-tools/#looker) . The following tools are available to the LLM: ### Looker Model and Query Tools These tools are used to get information about a Looker model and execute queries against that model. 1. **get\_models**: list the LookML models in Looker 2. **get\_explores**: list the explores in a given model 3. **get\_dimensions**: list the dimensions in a given explore 4. **get\_measures**: list the measures in a given explore 5. **get\_filters**: list the filters in a given explore 6. **get\_parameters**: list the parameters in a given explore 7. **query**: Run a query and return the data 8. **query\_sql**: Return the SQL generated by Looker for a query 9. **query\_url**: Return a link to the query in Looker for further exploration ### Looker Content Tools These tools get saved content (Looks and Dashboards) from a Looker instance and create new saved content. 1. **get\_looks**: Return the saved Looks that match a title or description 2. **run\_look**: Run a saved Look and return the data 3. **make\_look**: Create a saved Look in Looker and return the URL 4. **get\_dashboards**: Return the saved dashboards that match a title or description 5. **run\_dashboard**: Run the queries associated with a dashboard and return the data 6. **make\_dashboard**: Create a saved dashboard in Looker and return the URL 7. **add\_dashboard\_element**: Add a tile to a dashboard 8. **add\_dashboard\_filter**: Add a filter to a dashboard 9. **generate\_embed\_url**: Generate an embed url for content ### Looker Instance Health Tools These tools offer the same health check algorithms that the popular CLI [Henry](https://github.com/looker-open-source/henry) offers. 1. **health\_pulse**: Check the health of a Looker intance 2. **health\_analyze**: Analyze the usage of a Looker object 3. **health\_vacuum**: Find LookML elements that might be unused ### LookML Authoring Tools These tools allow enable the caller to write and modify LookML files as well as get the database schema needed to write LookML effectively. 1. **dev\_mode**: Activate dev mode. 2. **get\_projects**: Get the list of LookML projects 3. **get\_project\_files**: Get the list of files in a project 4. **get\_project\_file**: Get the contents of a file in a project 5. **create\_project\_file**: Create a file in a project 6. **update\_project\_file**: Update the contents of a file in a project 7. **delete\_project\_file**: Delete a file in a project 8. **get\_connections**: Get the list of connections 9. **get\_connection\_schemas**: Get the list of schemas for a connection 10. **get\_connection\_databases**: Get the list of databases for a connection 11. **get\_connection\_tables**: Get the list of tables for a connection 12. **get\_connection\_table\_columns**: Get the list of columns for a table in a connection Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 19, 2025: [chore(main): release 0.24.0 (#2162) (f520b4ed8ae)](https://github.com/googleapis/genai-toolbox/commit/f520b4ed8aedc28147777bdb673a576092a53513) --- # Looker using MCP | MCP Toolbox for Databases Looker using MCP ================ Connect your IDE to Looker using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Looker instance: * [Gemini-CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Antigravity](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/looker_mcp/#connect-with-antigravity) Set up Looker ------------- 1. Get a Looker Client ID and Client Secret. Follow the directions [here](https://cloud.google.com/looker/docs/api-auth#authentication_with_an_sdk) . 2. Have the base URL of your Looker instance available. It is likely something like `https://looker.example.com`. In some cases the API is listening at a different port, and you will need to use `https://looker.example.com:19999` instead. Connect with Antigravity ------------------------ You can connect Looker to Antigravity in the following ways: * Using the MCP Store * Using a custom configuration Note You don’t need to download the MCP Toolbox binary to use these methods. * MCP Store * Custom config The most straightforward way to connect to Looker in Antigravity is by using the built-in MCP Store. 1. Open Antigravity and open the editor’s agent panel. 2. Click the **"…"** icon at the top of the panel and select **MCP Servers**. 3. Locate **Looker** in the list of available servers and click Install. 4. Follow the on-screen prompts to securely link your accounts where applicable. After you install Looker in the MCP Store, resources and tools from the server are automatically available to the editor. To connect to a custom MCP server, follow these steps: 1. Open Antigravity and navigate to the MCP store using the **"…"** drop-down at the top of the editor’s agent panel. 2. To open the **mcp\_config.json** file, click **MCP Servers** and then click **Manage MCP Servers > View raw config**. 3. Add the following configuration, replace the environment variables with your values, and save. { "mcpServers": { "looker": { "command": "npx", "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "looker", "--stdio"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "your-client-id", "LOOKER_CLIENT_SECRET": "your-client-secret" } } } } Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/windows/amd64/toolbox.exe 1. Make the binary executable: chmod +x toolbox 2. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Gemini-CLI * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf 1. Install [Gemini-CLI](https://github.com/google-gemini/gemini-cli#install-globally-with-npm) . 2. Create a directory `.gemini` in your home directory if it doesn’t exist. 3. Create the file `.gemini/settings.json` if it doesn’t exist. 4. Add the following configuration, or add the mcpServers stanza if you already have a `settings.json` with content. Replace the path to the toolbox executable and the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 5. Start Gemini-CLI with the `gemini` command and use the command `/mcp` to see the configured MCP tools. 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude Code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } Use Tools --------- Your AI tool is now connected to Looker using MCP. Try asking your AI assistant to list models, explores, dimensions, and measures. Run a query, retrieve the SQL for a query, and run a saved Look. The full tool list is available in the [Prebuilt Tools Reference](https://mcp-toolbox.dev/v0.28.0/reference/prebuilt-tools/#looker) . The following tools are available to the LLM: ### Looker Model and Query Tools These tools are used to get information about a Looker model and execute queries against that model. 1. **get\_models**: list the LookML models in Looker 2. **get\_explores**: list the explores in a given model 3. **get\_dimensions**: list the dimensions in a given explore 4. **get\_measures**: list the measures in a given explore 5. **get\_filters**: list the filters in a given explore 6. **get\_parameters**: list the parameters in a given explore 7. **query**: Run a query and return the data 8. **query\_sql**: Return the SQL generated by Looker for a query 9. **query\_url**: Return a link to the query in Looker for further exploration ### Looker Content Tools These tools get saved content (Looks and Dashboards) from a Looker instance and create new saved content. 1. **get\_looks**: Return the saved Looks that match a title or description 2. **run\_look**: Run a saved Look and return the data 3. **make\_look**: Create a saved Look in Looker and return the URL 4. **get\_dashboards**: Return the saved dashboards that match a title or description 5. **run\_dashboard**: Run the queries associated with a dashboard and return the data 6. **make\_dashboard**: Create a saved dashboard in Looker and return the URL 7. **add\_dashboard\_element**: Add a tile to a dashboard 8. **add\_dashboard\_filter**: Add a filter to a dashboard 9. **generate\_embed\_url**: Generate an embed url for content ### Looker Instance Health Tools These tools offer the same health check algorithms that the popular CLI [Henry](https://github.com/looker-open-source/henry) offers. 1. **health\_pulse**: Check the health of a Looker intance 2. **health\_analyze**: Analyze the usage of a Looker object 3. **health\_vacuum**: Find LookML elements that might be unused ### LookML Authoring Tools These tools allow enable the caller to write and modify LookML files as well as get the database schema needed to write LookML effectively. 1. **dev\_mode**: Activate dev mode. 2. **get\_projects**: Get the list of LookML projects 3. **get\_project\_files**: Get the list of files in a project 4. **get\_project\_file**: Get the contents of a file in a project 5. **create\_project\_file**: Create a file in a project 6. **update\_project\_file**: Update the contents of a file in a project 7. **delete\_project\_file**: Delete a file in a project 8. **get\_connections**: Get the list of connections 9. **get\_connection\_schemas**: Get the list of schemas for a connection 10. **get\_connection\_databases**: Get the list of databases for a connection 11. **get\_connection\_tables**: Get the list of tables for a connection 12. **get\_connection\_table\_columns**: Get the list of columns for a table in a connection Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 2, 2026: [chore(main): release 0.28.0 (#2472) (81253a0bd70)](https://github.com/googleapis/genai-toolbox/commit/81253a0bd7049a2e2681ef13631a768cb402040e) --- # Looker using MCP | MCP Toolbox for Databases Looker using MCP ================ Connect your IDE to Looker using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Looker instance: * [Gemini-CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Antigravity](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/looker_mcp/#connect-with-antigravity) Set up Looker ------------- 1. Get a Looker Client ID and Client Secret. Follow the directions [here](https://cloud.google.com/looker/docs/api-auth#authentication_with_an_sdk) . 2. Have the base URL of your Looker instance available. It is likely something like `https://looker.example.com`. In some cases the API is listening at a different port, and you will need to use `https://looker.example.com:19999` instead. Connect with Antigravity ------------------------ You can connect Looker to Antigravity in the following ways: * Using the MCP Store * Using a custom configuration Note You don’t need to download the MCP Toolbox binary to use these methods. * MCP Store * Custom config The most straightforward way to connect to Looker in Antigravity is by using the built-in MCP Store. 1. Open Antigravity and open the editor’s agent panel. 2. Click the **"…"** icon at the top of the panel and select **MCP Servers**. 3. Locate **Looker** in the list of available servers and click Install. 4. Follow the on-screen prompts to securely link your accounts where applicable. After you install Looker in the MCP Store, resources and tools from the server are automatically available to the editor. To connect to a custom MCP server, follow these steps: 1. Open Antigravity and navigate to the MCP store using the **"…"** drop-down at the top of the editor’s agent panel. 2. To open the **mcp\_config.json** file, click **MCP Servers** and then click **Manage MCP Servers > View raw config**. 3. Add the following configuration, replace the environment variables with your values, and save. { "mcpServers": { "looker": { "command": "npx", "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "looker", "--stdio"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "your-client-id", "LOOKER_CLIENT_SECRET": "your-client-secret" } } } } Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe 1. Make the binary executable: chmod +x toolbox 2. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Gemini-CLI * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf 1. Install [Gemini-CLI](https://github.com/google-gemini/gemini-cli#install-globally-with-npm) . 2. Create a directory `.gemini` in your home directory if it doesn’t exist. 3. Create the file `.gemini/settings.json` if it doesn’t exist. 4. Add the following configuration, or add the mcpServers stanza if you already have a `settings.json` with content. Replace the path to the toolbox executable and the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 5. Start Gemini-CLI with the `gemini` command and use the command `/mcp` to see the configured MCP tools. 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude Code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } Use Tools --------- Your AI tool is now connected to Looker using MCP. Try asking your AI assistant to list models, explores, dimensions, and measures. Run a query, retrieve the SQL for a query, and run a saved Look. The full tool list is available in the [Prebuilt Tools Reference](https://mcp-toolbox.dev/v0.26.0/reference/prebuilt-tools/#looker) . The following tools are available to the LLM: ### Looker Model and Query Tools These tools are used to get information about a Looker model and execute queries against that model. 1. **get\_models**: list the LookML models in Looker 2. **get\_explores**: list the explores in a given model 3. **get\_dimensions**: list the dimensions in a given explore 4. **get\_measures**: list the measures in a given explore 5. **get\_filters**: list the filters in a given explore 6. **get\_parameters**: list the parameters in a given explore 7. **query**: Run a query and return the data 8. **query\_sql**: Return the SQL generated by Looker for a query 9. **query\_url**: Return a link to the query in Looker for further exploration ### Looker Content Tools These tools get saved content (Looks and Dashboards) from a Looker instance and create new saved content. 1. **get\_looks**: Return the saved Looks that match a title or description 2. **run\_look**: Run a saved Look and return the data 3. **make\_look**: Create a saved Look in Looker and return the URL 4. **get\_dashboards**: Return the saved dashboards that match a title or description 5. **run\_dashboard**: Run the queries associated with a dashboard and return the data 6. **make\_dashboard**: Create a saved dashboard in Looker and return the URL 7. **add\_dashboard\_element**: Add a tile to a dashboard 8. **add\_dashboard\_filter**: Add a filter to a dashboard 9. **generate\_embed\_url**: Generate an embed url for content ### Looker Instance Health Tools These tools offer the same health check algorithms that the popular CLI [Henry](https://github.com/looker-open-source/henry) offers. 1. **health\_pulse**: Check the health of a Looker intance 2. **health\_analyze**: Analyze the usage of a Looker object 3. **health\_vacuum**: Find LookML elements that might be unused ### LookML Authoring Tools These tools allow enable the caller to write and modify LookML files as well as get the database schema needed to write LookML effectively. 1. **dev\_mode**: Activate dev mode. 2. **get\_projects**: Get the list of LookML projects 3. **get\_project\_files**: Get the list of files in a project 4. **get\_project\_file**: Get the contents of a file in a project 5. **create\_project\_file**: Create a file in a project 6. **update\_project\_file**: Update the contents of a file in a project 7. **delete\_project\_file**: Delete a file in a project 8. **get\_connections**: Get the list of connections 9. **get\_connection\_schemas**: Get the list of schemas for a connection 10. **get\_connection\_databases**: Get the list of databases for a connection 11. **get\_connection\_tables**: Get the list of tables for a connection 12. **get\_connection\_table\_columns**: Get the list of columns for a table in a connection Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 22, 2026: [chore(main): release 0.26.0 (#2286) (86bf7bf8d06)](https://github.com/googleapis/genai-toolbox/commit/86bf7bf8d068f00adccd7223dd113743aed83ab5) --- # Looker using MCP | MCP Toolbox for Databases Looker using MCP ================ Connect your IDE to Looker using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Looker instance: * [Gemini-CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Antigravity](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/looker_mcp/#connect-with-antigravity) Set up Looker ------------- 1. Get a Looker Client ID and Client Secret. Follow the directions [here](https://cloud.google.com/looker/docs/api-auth#authentication_with_an_sdk) . 2. Have the base URL of your Looker instance available. It is likely something like `https://looker.example.com`. In some cases the API is listening at a different port, and you will need to use `https://looker.example.com:19999` instead. Connect with Antigravity ------------------------ You can connect Looker to Antigravity in the following ways: * Using the MCP Store * Using a custom configuration Note You don’t need to download the MCP Toolbox binary to use these methods. * MCP Store * Custom config The most straightforward way to connect to Looker in Antigravity is by using the built-in MCP Store. 1. Open Antigravity and open the editor’s agent panel. 2. Click the **"…"** icon at the top of the panel and select **MCP Servers**. 3. Locate **Looker** in the list of available servers and click Install. 4. Follow the on-screen prompts to securely link your accounts where applicable. After you install Looker in the MCP Store, resources and tools from the server are automatically available to the editor. To connect to a custom MCP server, follow these steps: 1. Open Antigravity and navigate to the MCP store using the **"…"** drop-down at the top of the editor’s agent panel. 2. To open the **mcp\_config.json** file, click **MCP Servers** and then click **Manage MCP Servers > View raw config**. 3. Add the following configuration, replace the environment variables with your values, and save. { "mcpServers": { "looker": { "command": "npx", "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "looker", "--stdio"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "your-client-id", "LOOKER_CLIENT_SECRET": "your-client-secret" } } } } Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/windows/amd64/toolbox.exe 1. Make the binary executable: chmod +x toolbox 2. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Gemini-CLI * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf 1. Install [Gemini-CLI](https://github.com/google-gemini/gemini-cli#install-globally-with-npm) . 2. Create a directory `.gemini` in your home directory if it doesn’t exist. 3. Create the file `.gemini/settings.json` if it doesn’t exist. 4. Add the following configuration, or add the mcpServers stanza if you already have a `settings.json` with content. Replace the path to the toolbox executable and the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 5. Start Gemini-CLI with the `gemini` command and use the command `/mcp` to see the configured MCP tools. 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude Code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } Use Tools --------- Your AI tool is now connected to Looker using MCP. Try asking your AI assistant to list models, explores, dimensions, and measures. Run a query, retrieve the SQL for a query, and run a saved Look. The full tool list is available in the [Prebuilt Tools Reference](https://mcp-toolbox.dev/v0.27.0/reference/prebuilt-tools/#looker) . The following tools are available to the LLM: ### Looker Model and Query Tools These tools are used to get information about a Looker model and execute queries against that model. 1. **get\_models**: list the LookML models in Looker 2. **get\_explores**: list the explores in a given model 3. **get\_dimensions**: list the dimensions in a given explore 4. **get\_measures**: list the measures in a given explore 5. **get\_filters**: list the filters in a given explore 6. **get\_parameters**: list the parameters in a given explore 7. **query**: Run a query and return the data 8. **query\_sql**: Return the SQL generated by Looker for a query 9. **query\_url**: Return a link to the query in Looker for further exploration ### Looker Content Tools These tools get saved content (Looks and Dashboards) from a Looker instance and create new saved content. 1. **get\_looks**: Return the saved Looks that match a title or description 2. **run\_look**: Run a saved Look and return the data 3. **make\_look**: Create a saved Look in Looker and return the URL 4. **get\_dashboards**: Return the saved dashboards that match a title or description 5. **run\_dashboard**: Run the queries associated with a dashboard and return the data 6. **make\_dashboard**: Create a saved dashboard in Looker and return the URL 7. **add\_dashboard\_element**: Add a tile to a dashboard 8. **add\_dashboard\_filter**: Add a filter to a dashboard 9. **generate\_embed\_url**: Generate an embed url for content ### Looker Instance Health Tools These tools offer the same health check algorithms that the popular CLI [Henry](https://github.com/looker-open-source/henry) offers. 1. **health\_pulse**: Check the health of a Looker intance 2. **health\_analyze**: Analyze the usage of a Looker object 3. **health\_vacuum**: Find LookML elements that might be unused ### LookML Authoring Tools These tools allow enable the caller to write and modify LookML files as well as get the database schema needed to write LookML effectively. 1. **dev\_mode**: Activate dev mode. 2. **get\_projects**: Get the list of LookML projects 3. **get\_project\_files**: Get the list of files in a project 4. **get\_project\_file**: Get the contents of a file in a project 5. **create\_project\_file**: Create a file in a project 6. **update\_project\_file**: Update the contents of a file in a project 7. **delete\_project\_file**: Delete a file in a project 8. **get\_connections**: Get the list of connections 9. **get\_connection\_schemas**: Get the list of schemas for a connection 10. **get\_connection\_databases**: Get the list of databases for a connection 11. **get\_connection\_tables**: Get the list of tables for a connection 12. **get\_connection\_table\_columns**: Get the list of columns for a table in a connection Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified February 12, 2026: [chore(main): release 0.27.0 (#2363) (c5524d32f58)](https://github.com/googleapis/genai-toolbox/commit/c5524d32f580fed81c8b90448e2f17e719710ff9) --- # Firestore using MCP | MCP Toolbox for Databases Firestore using MCP =================== Connect your IDE to Firestore using Toolbox. Last modified September 4, 2025: [docs: corrected copilot mcp config (#1253) (0a8351c32d8)](https://github.com/googleapis/genai-toolbox/commit/0a8351c32d8743c1289a1707d1f64c8527b48aa4) --- # Firestore using MCP | MCP Toolbox for Databases Firestore using MCP =================== Connect your IDE to Firestore using Toolbox. Last modified September 4, 2025: [docs: corrected copilot mcp config (#1253) (0a8351c32d8)](https://github.com/googleapis/genai-toolbox/commit/0a8351c32d8743c1289a1707d1f64c8527b48aa4) --- # MySQL using MCP | MCP Toolbox for Databases MySQL using MCP =============== Connect your IDE to MySQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like MySQL. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a MySQL instance: * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a MySQL instance.](https://dev.mysql.com/downloads/installer/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to MySQL using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 8, 2026: [chore(main): release 0.25.0 (#2218) (41b518b955a)](https://github.com/googleapis/genai-toolbox/commit/41b518b955af8710c5b9b1aacddcfab63ff505bd) --- # MySQL using MCP | MCP Toolbox for Databases MySQL using MCP =============== Connect your IDE to MySQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like MySQL. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a MySQL instance: * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a MySQL instance.](https://dev.mysql.com/downloads/installer/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to MySQL using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 2, 2026: [chore(main): release 0.28.0 (#2472) (81253a0bd70)](https://github.com/googleapis/genai-toolbox/commit/81253a0bd7049a2e2681ef13631a768cb402040e) --- # MySQL using MCP | MCP Toolbox for Databases MySQL using MCP =============== Connect your IDE to MySQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like MySQL. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a MySQL instance: * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a MySQL instance.](https://dev.mysql.com/downloads/installer/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to MySQL using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 19, 2025: [chore(main): release 0.24.0 (#2162) (f520b4ed8ae)](https://github.com/googleapis/genai-toolbox/commit/f520b4ed8aedc28147777bdb673a576092a53513) --- # MySQL using MCP | MCP Toolbox for Databases MySQL using MCP =============== Connect your IDE to MySQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like MySQL. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a MySQL instance: * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a MySQL instance.](https://dev.mysql.com/downloads/installer/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to MySQL using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 22, 2026: [chore(main): release 0.26.0 (#2286) (86bf7bf8d06)](https://github.com/googleapis/genai-toolbox/commit/86bf7bf8d068f00adccd7223dd113743aed83ab5) --- # MySQL using MCP | MCP Toolbox for Databases MySQL using MCP =============== Connect your IDE to MySQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like MySQL. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a MySQL instance: * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a MySQL instance.](https://dev.mysql.com/downloads/installer/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to MySQL using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified February 12, 2026: [chore(main): release 0.27.0 (#2363) (c5524d32f58)](https://github.com/googleapis/genai-toolbox/commit/c5524d32f580fed81c8b90448e2f17e719710ff9) --- # Looker using MCP | MCP Toolbox for Databases Looker using MCP ================ Connect your IDE to Looker using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Looker instance: * [Gemini-CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Antigravity](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/looker_mcp/#connect-with-antigravity) Set up Looker ------------- 1. Get a Looker Client ID and Client Secret. Follow the directions [here](https://cloud.google.com/looker/docs/api-auth#authentication_with_an_sdk) . 2. Have the base URL of your Looker instance available. It is likely something like `https://looker.example.com`. In some cases the API is listening at a different port, and you will need to use `https://looker.example.com:19999` instead. Connect with Antigravity ------------------------ You can connect Looker to Antigravity in the following ways: * Using the MCP Store * Using a custom configuration Note You don’t need to download the MCP Toolbox binary to use these methods. * MCP Store * Custom config The most straightforward way to connect to Looker in Antigravity is by using the built-in MCP Store. 1. Open Antigravity and open the editor’s agent panel. 2. Click the **"…"** icon at the top of the panel and select **MCP Servers**. 3. Locate **Looker** in the list of available servers and click Install. 4. Follow the on-screen prompts to securely link your accounts where applicable. After you install Looker in the MCP Store, resources and tools from the server are automatically available to the editor. To connect to a custom MCP server, follow these steps: 1. Open Antigravity and navigate to the MCP store using the **"…"** drop-down at the top of the editor’s agent panel. 2. To open the **mcp\_config.json** file, click **MCP Servers** and then click **Manage MCP Servers > View raw config**. 3. Add the following configuration, replace the environment variables with your values, and save. { "mcpServers": { "looker": { "command": "npx", "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "looker", "--stdio"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "your-client-id", "LOOKER_CLIENT_SECRET": "your-client-secret" } } } } Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/windows/amd64/toolbox.exe 1. Make the binary executable: chmod +x toolbox 2. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Gemini-CLI * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf 1. Install [Gemini-CLI](https://github.com/google-gemini/gemini-cli#install-globally-with-npm) . 2. Create a directory `.gemini` in your home directory if it doesn’t exist. 3. Create the file `.gemini/settings.json` if it doesn’t exist. 4. Add the following configuration, or add the mcpServers stanza if you already have a `settings.json` with content. Replace the path to the toolbox executable and the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 5. Start Gemini-CLI with the `gemini` command and use the command `/mcp` to see the configured MCP tools. 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude Code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } Use Tools --------- Your AI tool is now connected to Looker using MCP. Try asking your AI assistant to list models, explores, dimensions, and measures. Run a query, retrieve the SQL for a query, and run a saved Look. The full tool list is available in the [Prebuilt Tools Reference](https://mcp-toolbox.dev/v0.29.0/reference/prebuilt-tools/#looker) . The following tools are available to the LLM: ### Looker Model and Query Tools These tools are used to get information about a Looker model and execute queries against that model. 1. **get\_models**: list the LookML models in Looker 2. **get\_explores**: list the explores in a given model 3. **get\_dimensions**: list the dimensions in a given explore 4. **get\_measures**: list the measures in a given explore 5. **get\_filters**: list the filters in a given explore 6. **get\_parameters**: list the parameters in a given explore 7. **query**: Run a query and return the data 8. **query\_sql**: Return the SQL generated by Looker for a query 9. **query\_url**: Return a link to the query in Looker for further exploration ### Looker Content Tools These tools get saved content (Looks and Dashboards) from a Looker instance and create new saved content. 1. **get\_looks**: Return the saved Looks that match a title or description 2. **run\_look**: Run a saved Look and return the data 3. **make\_look**: Create a saved Look in Looker and return the URL 4. **get\_dashboards**: Return the saved dashboards that match a title or description 5. **run\_dashboard**: Run the queries associated with a dashboard and return the data 6. **make\_dashboard**: Create a saved dashboard in Looker and return the URL 7. **add\_dashboard\_element**: Add a tile to a dashboard 8. **add\_dashboard\_filter**: Add a filter to a dashboard 9. **generate\_embed\_url**: Generate an embed url for content ### Looker Instance Health Tools These tools offer the same health check algorithms that the popular CLI [Henry](https://github.com/looker-open-source/henry) offers. 1. **health\_pulse**: Check the health of a Looker intance 2. **health\_analyze**: Analyze the usage of a Looker object 3. **health\_vacuum**: Find LookML elements that might be unused ### LookML Authoring Tools These tools allow enable the caller to write and modify LookML files as well as get the database schema needed to write LookML effectively. 1. **dev\_mode**: Activate dev mode. 2. **get\_projects**: Get the list of LookML projects 3. **get\_project\_files**: Get the list of files in a project 4. **get\_project\_file**: Get the contents of a file in a project 5. **create\_project\_file**: Create a file in a project 6. **update\_project\_file**: Update the contents of a file in a project 7. **delete\_project\_file**: Delete a file in a project 8. **get\_connections**: Get the list of connections 9. **get\_connection\_schemas**: Get the list of schemas for a connection 10. **get\_connection\_databases**: Get the list of databases for a connection 11. **get\_connection\_tables**: Get the list of tables for a connection 12. **get\_connection\_table\_columns**: Get the list of columns for a table in a connection Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 13, 2026: [chore(main): release 0.29.0 (#2608) (39832a0faa6)](https://github.com/googleapis/genai-toolbox/commit/39832a0faa6e967734f4cf2283ec270aa17fc363) --- # Looker using MCP | MCP Toolbox for Databases Looker using MCP ================ Connect your IDE to Looker using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Looker instance: * [Gemini-CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/#configure-your-mcp-client) * [Antigravity](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/looker_mcp/#connect-with-antigravity) Set up Looker ------------- 1. Get a Looker Client ID and Client Secret. Follow the directions [here](https://cloud.google.com/looker/docs/api-auth#authentication_with_an_sdk) . 2. Have the base URL of your Looker instance available. It is likely something like `https://looker.example.com`. In some cases the API is listening at a different port, and you will need to use `https://looker.example.com:19999` instead. Connect with Antigravity ------------------------ You can connect Looker to Antigravity in the following ways: * Using the MCP Store * Using a custom configuration Note You don’t need to download the MCP Toolbox binary to use these methods. * MCP Store * Custom config The most straightforward way to connect to Looker in Antigravity is by using the built-in MCP Store. 1. Open Antigravity and open the editor’s agent panel. 2. Click the **"…"** icon at the top of the panel and select **MCP Servers**. 3. Locate **Looker** in the list of available servers and click Install. 4. Follow the on-screen prompts to securely link your accounts where applicable. After you install Looker in the MCP Store, resources and tools from the server are automatically available to the editor. To connect to a custom MCP server, follow these steps: 1. Open Antigravity and navigate to the MCP store using the **"…"** drop-down at the top of the editor’s agent panel. 2. To open the **mcp\_config.json** file, click **MCP Servers** and then click **Manage MCP Servers > View raw config**. 3. Add the following configuration, replace the environment variables with your values, and save. { "mcpServers": { "looker": { "command": "npx", "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "looker", "--stdio"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "your-client-id", "LOOKER_CLIENT_SECRET": "your-client-secret" } } } } Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/windows/amd64/toolbox.exe 1. Make the binary executable: chmod +x toolbox 2. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Gemini-CLI * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf 1. Install [Gemini-CLI](https://github.com/google-gemini/gemini-cli#install-globally-with-npm) . 2. Create a directory `.gemini` in your home directory if it doesn’t exist. 3. Create the file `.gemini/settings.json` if it doesn’t exist. 4. Add the following configuration, or add the mcpServers stanza if you already have a `settings.json` with content. Replace the path to the toolbox executable and the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 5. Start Gemini-CLI with the `gemini` command and use the command `/mcp` to see the configured MCP tools. 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude Code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "looker-toolbox": { "command": "./PATH/TO/toolbox", "args": ["--stdio", "--prebuilt", "looker"], "env": { "LOOKER_BASE_URL": "https://looker.example.com", "LOOKER_CLIENT_ID": "", "LOOKER_CLIENT_SECRET": "", "LOOKER_VERIFY_SSL": "true" } } } } Use Tools --------- Your AI tool is now connected to Looker using MCP. Try asking your AI assistant to list models, explores, dimensions, and measures. Run a query, retrieve the SQL for a query, and run a saved Look. The full tool list is available in the [Prebuilt Tools Reference](https://mcp-toolbox.dev/v0.30.0/reference/prebuilt-tools/#looker) . The following tools are available to the LLM: ### Looker Model and Query Tools These tools are used to get information about a Looker model and execute queries against that model. 1. **get\_models**: list the LookML models in Looker 2. **get\_explores**: list the explores in a given model 3. **get\_dimensions**: list the dimensions in a given explore 4. **get\_measures**: list the measures in a given explore 5. **get\_filters**: list the filters in a given explore 6. **get\_parameters**: list the parameters in a given explore 7. **query**: Run a query and return the data 8. **query\_sql**: Return the SQL generated by Looker for a query 9. **query\_url**: Return a link to the query in Looker for further exploration ### Looker Content Tools These tools get saved content (Looks and Dashboards) from a Looker instance and create new saved content. 1. **get\_looks**: Return the saved Looks that match a title or description 2. **run\_look**: Run a saved Look and return the data 3. **make\_look**: Create a saved Look in Looker and return the URL 4. **get\_dashboards**: Return the saved dashboards that match a title or description 5. **run\_dashboard**: Run the queries associated with a dashboard and return the data 6. **make\_dashboard**: Create a saved dashboard in Looker and return the URL 7. **add\_dashboard\_element**: Add a tile to a dashboard 8. **add\_dashboard\_filter**: Add a filter to a dashboard 9. **generate\_embed\_url**: Generate an embed url for content ### Looker Instance Health Tools These tools offer the same health check algorithms that the popular CLI [Henry](https://github.com/looker-open-source/henry) offers. 1. **health\_pulse**: Check the health of a Looker intance 2. **health\_analyze**: Analyze the usage of a Looker object 3. **health\_vacuum**: Find LookML elements that might be unused ### LookML Authoring Tools These tools allow enable the caller to write and modify LookML files as well as get the database schema needed to write LookML effectively. 1. **dev\_mode**: Activate dev mode. 2. **get\_projects**: Get the list of LookML projects 3. **get\_project\_files**: Get the list of files in a project 4. **get\_project\_file**: Get the contents of a file in a project 5. **create\_project\_file**: Create a file in a project 6. **update\_project\_file**: Update the contents of a file in a project 7. **delete\_project\_file**: Delete a file in a project 8. **get\_connections**: Get the list of connections 9. **get\_connection\_schemas**: Get the list of schemas for a connection 10. **get\_connection\_databases**: Get the list of databases for a connection 11. **get\_connection\_tables**: Get the list of tables for a connection 12. **get\_connection\_table\_columns**: Get the list of columns for a table in a connection Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # Neo4j using MCP | MCP Toolbox for Databases Neo4j using MCP =============== Connect your IDE to Neo4j using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Neo4j. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Neo4j instance: * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a Neo4j instance.](https://neo4j.com/cloud/platform/aura-graph-database/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcp" : { "servers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Neo4j using MCP. Try asking your AI assistant to get the graph schema or execute Cypher statements. The following tools are available to the LLM: 1. **get\_schema**: extracts the complete database schema, including details about node labels, relationships, properties, constraints, and indexes. 2. **execute\_cypher**: executes any arbitrary Cypher statement. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 8, 2026: [chore(main): release 0.25.0 (#2218) (41b518b955a)](https://github.com/googleapis/genai-toolbox/commit/41b518b955af8710c5b9b1aacddcfab63ff505bd) --- # Neo4j using MCP | MCP Toolbox for Databases Neo4j using MCP =============== Connect your IDE to Neo4j using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Neo4j. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Neo4j instance: * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a Neo4j instance.](https://neo4j.com/cloud/platform/aura-graph-database/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcp" : { "servers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Neo4j using MCP. Try asking your AI assistant to get the graph schema or execute Cypher statements. The following tools are available to the LLM: 1. **get\_schema**: extracts the complete database schema, including details about node labels, relationships, properties, constraints, and indexes. 2. **execute\_cypher**: executes any arbitrary Cypher statement. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 2, 2026: [chore(main): release 0.28.0 (#2472) (81253a0bd70)](https://github.com/googleapis/genai-toolbox/commit/81253a0bd7049a2e2681ef13631a768cb402040e) --- # Neo4j using MCP | MCP Toolbox for Databases Neo4j using MCP =============== Connect your IDE to Neo4j using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Neo4j. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Neo4j instance: * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a Neo4j instance.](https://neo4j.com/cloud/platform/aura-graph-database/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcp" : { "servers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Neo4j using MCP. Try asking your AI assistant to get the graph schema or execute Cypher statements. The following tools are available to the LLM: 1. **get\_schema**: extracts the complete database schema, including details about node labels, relationships, properties, constraints, and indexes. 2. **execute\_cypher**: executes any arbitrary Cypher statement. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 19, 2025: [chore(main): release 0.24.0 (#2162) (f520b4ed8ae)](https://github.com/googleapis/genai-toolbox/commit/f520b4ed8aedc28147777bdb673a576092a53513) --- # Neo4j using MCP | MCP Toolbox for Databases Neo4j using MCP =============== Connect your IDE to Neo4j using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Neo4j. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Neo4j instance: * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a Neo4j instance.](https://neo4j.com/cloud/platform/aura-graph-database/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcp" : { "servers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Neo4j using MCP. Try asking your AI assistant to get the graph schema or execute Cypher statements. The following tools are available to the LLM: 1. **get\_schema**: extracts the complete database schema, including details about node labels, relationships, properties, constraints, and indexes. 2. **execute\_cypher**: executes any arbitrary Cypher statement. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 22, 2026: [chore(main): release 0.26.0 (#2286) (86bf7bf8d06)](https://github.com/googleapis/genai-toolbox/commit/86bf7bf8d068f00adccd7223dd113743aed83ab5) --- # MySQL using MCP | MCP Toolbox for Databases MySQL using MCP =============== Connect your IDE to MySQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like MySQL. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a MySQL instance: * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a MySQL instance.](https://dev.mysql.com/downloads/installer/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to MySQL using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 13, 2026: [chore(main): release 0.29.0 (#2608) (39832a0faa6)](https://github.com/googleapis/genai-toolbox/commit/39832a0faa6e967734f4cf2283ec270aa17fc363) --- # Neo4j using MCP | MCP Toolbox for Databases Neo4j using MCP =============== Connect your IDE to Neo4j using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Neo4j. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Neo4j instance: * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a Neo4j instance.](https://neo4j.com/cloud/platform/aura-graph-database/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcp" : { "servers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Neo4j using MCP. Try asking your AI assistant to get the graph schema or execute Cypher statements. The following tools are available to the LLM: 1. **get\_schema**: extracts the complete database schema, including details about node labels, relationships, properties, constraints, and indexes. 2. **execute\_cypher**: executes any arbitrary Cypher statement. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified February 12, 2026: [chore(main): release 0.27.0 (#2363) (c5524d32f58)](https://github.com/googleapis/genai-toolbox/commit/c5524d32f580fed81c8b90448e2f17e719710ff9) --- # PostgreSQL using MCP | MCP Toolbox for Databases PostgreSQL using MCP ==================== Connect your IDE to PostgreSQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Postgres instance: * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) Tip This guide can be used with [AlloyDB Omni](https://cloud.google.com/alloydb/omni/current/docs/overview) . Set up the database ------------------- 1. Create or select a PostgreSQL instance. * [Install PostgreSQL locally](https://www.postgresql.org/download/) * [Install AlloyDB Omni](https://cloud.google.com/alloydb/omni/current/docs/quickstart) 2. Create or reuse [a database user](https://cloud.google.com/alloydb/omni/current/docs/database-users/manage-users) and have the username and password ready. Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Postgres using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 8, 2026: [chore(main): release 0.25.0 (#2218) (41b518b955a)](https://github.com/googleapis/genai-toolbox/commit/41b518b955af8710c5b9b1aacddcfab63ff505bd) --- # PostgreSQL using MCP | MCP Toolbox for Databases PostgreSQL using MCP ==================== Connect your IDE to PostgreSQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Postgres instance: * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) Tip This guide can be used with [AlloyDB Omni](https://cloud.google.com/alloydb/omni/docs/overview) . Set up the database ------------------- 1. Create or select a PostgreSQL instance. * [Install PostgreSQL locally](https://www.postgresql.org/download/) * [Install AlloyDB Omni](https://cloud.google.com/alloydb/omni/docs/quickstart) 2. Create or reuse [a database user](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/database-users/manage-users) and have the username and password ready. Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Postgres using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 2, 2026: [chore(main): release 0.28.0 (#2472) (81253a0bd70)](https://github.com/googleapis/genai-toolbox/commit/81253a0bd7049a2e2681ef13631a768cb402040e) --- # MySQL using MCP | MCP Toolbox for Databases MySQL using MCP =============== Connect your IDE to MySQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like MySQL. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a MySQL instance: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mysql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a MySQL instance.](https://dev.mysql.com/downloads/installer/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "mysql", "--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "mysql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mysql","--stdio"], "env": { "MYSQL_HOST": "", "MYSQL_PORT": "", "MYSQL_DATABASE": "", "MYSQL_USER": "", "MYSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to MySQL using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # PostgreSQL using MCP | MCP Toolbox for Databases PostgreSQL using MCP ==================== Connect your IDE to PostgreSQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Postgres instance: * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) Tip This guide can be used with [AlloyDB Omni](https://cloud.google.com/alloydb/omni/current/docs/overview) . Set up the database ------------------- 1. Create or select a PostgreSQL instance. * [Install PostgreSQL locally](https://www.postgresql.org/download/) * [Install AlloyDB Omni](https://cloud.google.com/alloydb/omni/current/docs/quickstart) 2. Create or reuse [a database user](https://cloud.google.com/alloydb/omni/current/docs/database-users/manage-users) and have the username and password ready. Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Postgres using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 19, 2025: [chore(main): release 0.24.0 (#2162) (f520b4ed8ae)](https://github.com/googleapis/genai-toolbox/commit/f520b4ed8aedc28147777bdb673a576092a53513) --- # Spanner using MCP | MCP Toolbox for Databases Spanner using MCP ================= Connect your IDE to Spanner using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # PostgreSQL using MCP | MCP Toolbox for Databases PostgreSQL using MCP ==================== Connect your IDE to PostgreSQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Postgres instance: * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) Tip This guide can be used with [AlloyDB Omni](https://cloud.google.com/alloydb/omni/docs/overview) . Set up the database ------------------- 1. Create or select a PostgreSQL instance. * [Install PostgreSQL locally](https://www.postgresql.org/download/) * [Install AlloyDB Omni](https://cloud.google.com/alloydb/omni/docs/quickstart) 2. Create or reuse [a database user](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/database-users/manage-users) and have the username and password ready. Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Postgres using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified February 12, 2026: [chore(main): release 0.27.0 (#2363) (c5524d32f58)](https://github.com/googleapis/genai-toolbox/commit/c5524d32f580fed81c8b90448e2f17e719710ff9) --- # PostgreSQL using MCP | MCP Toolbox for Databases PostgreSQL using MCP ==================== Connect your IDE to PostgreSQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Postgres instance: * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) Tip This guide can be used with [AlloyDB Omni](https://cloud.google.com/alloydb/omni/current/docs/overview) . Set up the database ------------------- 1. Create or select a PostgreSQL instance. * [Install PostgreSQL locally](https://www.postgresql.org/download/) * [Install AlloyDB Omni](https://cloud.google.com/alloydb/omni/current/docs/quickstart) 2. Create or reuse [a database user](https://cloud.google.com/alloydb/omni/current/docs/database-users/manage-users) and have the username and password ready. Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Postgres using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 22, 2026: [chore(main): release 0.26.0 (#2286) (86bf7bf8d06)](https://github.com/googleapis/genai-toolbox/commit/86bf7bf8d068f00adccd7223dd113743aed83ab5) --- # Spanner using MCP | MCP Toolbox for Databases Spanner using MCP ================= Connect your IDE to Spanner using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Spanner using MCP | MCP Toolbox for Databases Spanner using MCP ================= Connect your IDE to Spanner using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Spanner using MCP | MCP Toolbox for Databases Spanner using MCP ================= Connect your IDE to Spanner using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Neo4j using MCP | MCP Toolbox for Databases Neo4j using MCP =============== Connect your IDE to Neo4j using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Neo4j. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Neo4j instance: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a Neo4j instance.](https://neo4j.com/cloud/platform/aura-graph-database/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcp" : { "servers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Neo4j using MCP. Try asking your AI assistant to get the graph schema or execute Cypher statements. The following tools are available to the LLM: 1. **get\_schema**: extracts the complete database schema, including details about node labels, relationships, properties, constraints, and indexes. 2. **execute\_cypher**: executes any arbitrary Cypher statement. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # Spanner using MCP | MCP Toolbox for Databases Spanner using MCP ================= Connect your IDE to Spanner using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Neo4j using MCP | MCP Toolbox for Databases Neo4j using MCP =============== Connect your IDE to Neo4j using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Neo4j. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Neo4j instance: * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/neo4j_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a Neo4j instance.](https://neo4j.com/cloud/platform/aura-graph-database/) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcp" : { "servers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "neo4j": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","neo4j","--stdio"], "env": { "NEO4J_URI": "", "NEO4J_DATABASE": "", "NEO4J_USERNAME": "", "NEO4J_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Neo4j using MCP. Try asking your AI assistant to get the graph schema or execute Cypher statements. The following tools are available to the LLM: 1. **get\_schema**: extracts the complete database schema, including details about node labels, relationships, properties, constraints, and indexes. 2. **execute\_cypher**: executes any arbitrary Cypher statement. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 13, 2026: [chore(main): release 0.29.0 (#2608) (39832a0faa6)](https://github.com/googleapis/genai-toolbox/commit/39832a0faa6e967734f4cf2283ec270aa17fc363) --- # PostgreSQL using MCP | MCP Toolbox for Databases PostgreSQL using MCP ==================== Connect your IDE to PostgreSQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Postgres instance: * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) Tip This guide can be used with [AlloyDB Omni](https://cloud.google.com/alloydb/omni/docs/overview) . Set up the database ------------------- 1. Create or select a PostgreSQL instance. * [Install PostgreSQL locally](https://www.postgresql.org/download/) * [Install AlloyDB Omni](https://cloud.google.com/alloydb/omni/docs/quickstart) 2. Create or reuse [a database user](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/database-users/manage-users) and have the username and password ready. Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Postgres using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 13, 2026: [chore(main): release 0.29.0 (#2608) (39832a0faa6)](https://github.com/googleapis/genai-toolbox/commit/39832a0faa6e967734f4cf2283ec270aa17fc363) --- # SQL Server using MCP | MCP Toolbox for Databases SQL Server using MCP ==================== Connect your IDE to SQL Server using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQL Server. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQL Server instance: * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQL Server instance.](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mssql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to SQL Server using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 8, 2026: [chore(main): release 0.25.0 (#2218) (41b518b955a)](https://github.com/googleapis/genai-toolbox/commit/41b518b955af8710c5b9b1aacddcfab63ff505bd) --- # SQL Server using MCP | MCP Toolbox for Databases SQL Server using MCP ==================== Connect your IDE to SQL Server using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQL Server. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQL Server instance: * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQL Server instance.](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mssql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to SQL Server using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 19, 2025: [chore(main): release 0.24.0 (#2162) (f520b4ed8ae)](https://github.com/googleapis/genai-toolbox/commit/f520b4ed8aedc28147777bdb673a576092a53513) --- # SQLite using MCP | MCP Toolbox for Databases SQLite using MCP ================ Connect your IDE to SQLite using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQLite. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQLite instance: * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQLite database file.](https://www.sqlite.org/download.html) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.24.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } Use Tools --------- Your AI tool is now connected to SQLite using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 19, 2025: [chore(main): release 0.24.0 (#2162) (f520b4ed8ae)](https://github.com/googleapis/genai-toolbox/commit/f520b4ed8aedc28147777bdb673a576092a53513) --- # SQLite using MCP | MCP Toolbox for Databases SQLite using MCP ================ Connect your IDE to SQLite using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQLite. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQLite instance: * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQLite database file.](https://www.sqlite.org/download.html) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.25.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } Use Tools --------- Your AI tool is now connected to SQLite using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 8, 2026: [chore(main): release 0.25.0 (#2218) (41b518b955a)](https://github.com/googleapis/genai-toolbox/commit/41b518b955af8710c5b9b1aacddcfab63ff505bd) --- # Oracle using MCP | MCP Toolbox for Databases Oracle using MCP ================ Connect your IDE to Oracle DB using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Oracle. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to an Oracle instance: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/oracle_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. Create or select an Oracle instance. 2. Create or reuse a database user and have the username and password ready. Install MCP Toolbox ------------------- 3. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.26.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/windows/amd64/toolbox.exe 4. Make the binary executable: chmod +x toolbox 5. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { “mcpServers”: { “oracle”: { “command”: “./PATH/TO/toolbox”, “args”: \["–prebuilt",“oracledb”,"–stdio"\], “env”: { “ORACLE\_CONNECTION\_STRING”: “”, “ORACLE\_USERNAME”: “”, “ORACLE\_PASSWORD”: “”, “ORACLE\_WALLET”: “”, “ORACLE\_USE\_OCI”: “false” } } } } \`\`\` 1. Restart Claude code to apply the new configuration. 1. Open Claude desktop and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "oracle": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","oracledb","--stdio"], "env": { "ORACLE_CONNECTION_STRING": "", "ORACLE_USERNAME": "", "ORACLE_PASSWORD": "", "ORACLE_WALLET": "", "ORACLE_USE_OCI": "false" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the Cline extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "oracle": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","oracledb","--stdio"], "env": { "ORACLE_CONNECTION_STRING": "", "ORACLE_USERNAME": "", "ORACLE_PASSWORD": "", "ORACLE_WALLET": "", "ORACLE_USE_OCI": "false" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "oracle": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","oracledb","--stdio"], "env": { "ORACLE_CONNECTION_STRING": "", "ORACLE_USERNAME": "", "ORACLE_PASSWORD": "", "ORACLE_WALLET": "", "ORACLE_USE_OCI": "false" } } } } 4. Cursor and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open VS Code and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "oracle": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","oracledb","--stdio"], "env": { "ORACLE_CONNECTION_STRING": "", "ORACLE_USERNAME": "", "ORACLE_PASSWORD": "", "ORACLE_WALLET": "", "ORACLE_USE_OCI": "false" } } } } 1. Open Windsurf and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "oracle": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","oracledb","--stdio"], "env": { "ORACLE_CONNECTION_STRING": "", "ORACLE_USERNAME": "", "ORACLE_PASSWORD": "", "ORACLE_WALLET": "", "ORACLE_USE_OCI": "false" } } } } 1. Install the Gemini CLI. 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "oracle": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","oracledb","--stdio"], "env": { "ORACLE_CONNECTION_STRING": "", "ORACLE_USERNAME": "", "ORACLE_PASSWORD": "", "ORACLE_WALLET": "", "ORACLE_USE_OCI": "false" } } } } 1. Install the Gemini Code Assist extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "oracle": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","oracledb","--stdio"], "env": { "ORACLE_CONNECTION_STRING": "", "ORACLE_USERNAME": "", "ORACLE_PASSWORD": "", "ORACLE_WALLET": "", "ORACLE_USE_OCI": "false" } } } } Use Tools --------- Your AI tool is now connected to Oracle using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **execute\_sql**: execute any SQL statement 2. **list\_tables**: lists tables and descriptions 3. **list\_active\_sessions**: Lists active database sessions. 4. **get\_query\_plan**: Generates the execution plan for a SQL statement. 5. **list\_top\_sql\_by\_resource**: Lists top SQL statements by resource usage. 6. **list\_tablespace\_usage**: Lists tablespace usage. 7. **list\_invalid\_objects**: Lists invalid objects. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # SQL Server using MCP | MCP Toolbox for Databases SQL Server using MCP ==================== Connect your IDE to SQL Server using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQL Server. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQL Server instance: * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQL Server instance.](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mssql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to SQL Server using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 22, 2026: [chore(main): release 0.26.0 (#2286) (86bf7bf8d06)](https://github.com/googleapis/genai-toolbox/commit/86bf7bf8d068f00adccd7223dd113743aed83ab5) --- # SQL Server using MCP | MCP Toolbox for Databases SQL Server using MCP ==================== Connect your IDE to SQL Server using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQL Server. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQL Server instance: * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQL Server instance.](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mssql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to SQL Server using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 2, 2026: [chore(main): release 0.28.0 (#2472) (81253a0bd70)](https://github.com/googleapis/genai-toolbox/commit/81253a0bd7049a2e2681ef13631a768cb402040e) --- # SQL Server using MCP | MCP Toolbox for Databases SQL Server using MCP ==================== Connect your IDE to SQL Server using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQL Server. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQL Server instance: * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQL Server instance.](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mssql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to SQL Server using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified February 12, 2026: [chore(main): release 0.27.0 (#2363) (c5524d32f58)](https://github.com/googleapis/genai-toolbox/commit/c5524d32f580fed81c8b90448e2f17e719710ff9) --- # Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for PostgreSQL Admin using MCP ======================================== Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for PostgreSQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for PostgreSQL using MCP. The `cloud-sql-postgres-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for PostgreSQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for PostgreSQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 2, 2025: [feat(prebuilt/cloud-sql): Add clone instance tool for cloud sql (#1845) (5e43630907a)](https://github.com/googleapis/genai-toolbox/commit/5e43630907aa2d7bc6818142483a33272eab060b) --- # Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for MySQL Admin using MCP =================================== Create and manage Cloud SQL for MySQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for MySQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for MySQL using MCP. The `cloud-sql-mysql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for MySQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for MySQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 2, 2025: [feat(prebuilt/cloud-sql): Add clone instance tool for cloud sql (#1845) (5e43630907a)](https://github.com/googleapis/genai-toolbox/commit/5e43630907aa2d7bc6818142483a33272eab060b) --- # SQLite using MCP | MCP Toolbox for Databases SQLite using MCP ================ Connect your IDE to SQLite using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQLite. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQLite instance: * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQLite database file.](https://www.sqlite.org/download.html) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } Use Tools --------- Your AI tool is now connected to SQLite using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified February 12, 2026: [chore(main): release 0.27.0 (#2363) (c5524d32f58)](https://github.com/googleapis/genai-toolbox/commit/c5524d32f580fed81c8b90448e2f17e719710ff9) --- # Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for PostgreSQL Admin using MCP ======================================== Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for PostgreSQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for PostgreSQL using MCP. The `cloud-sql-postgres-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for PostgreSQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for PostgreSQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 2, 2025: [feat(prebuilt/cloud-sql): Add clone instance tool for cloud sql (#1845) (5e43630907a)](https://github.com/googleapis/genai-toolbox/commit/5e43630907aa2d7bc6818142483a33272eab060b) --- # Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for MySQL Admin using MCP =================================== Create and manage Cloud SQL for MySQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for MySQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for MySQL using MCP. The `cloud-sql-mysql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for MySQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for MySQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 2, 2025: [feat(prebuilt/cloud-sql): Add clone instance tool for cloud sql (#1845) (5e43630907a)](https://github.com/googleapis/genai-toolbox/commit/5e43630907aa2d7bc6818142483a33272eab060b) --- # Spanner using MCP | MCP Toolbox for Databases Spanner using MCP ================= Connect your IDE to Spanner using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # SQLite using MCP | MCP Toolbox for Databases SQLite using MCP ================ Connect your IDE to SQLite using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQLite. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQLite instance: * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQLite database file.](https://www.sqlite.org/download.html) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } Use Tools --------- Your AI tool is now connected to SQLite using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 22, 2026: [chore(main): release 0.26.0 (#2286) (86bf7bf8d06)](https://github.com/googleapis/genai-toolbox/commit/86bf7bf8d068f00adccd7223dd113743aed83ab5) --- # Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server Admin using MCP ======================================== Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for SQL Server instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.24.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for SQL Server using MCP. The `cloud-sql-mssql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for SQL Server instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for SQL Server instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 2, 2025: [feat(prebuilt/cloud-sql): Add clone instance tool for cloud sql (#1845) (5e43630907a)](https://github.com/googleapis/genai-toolbox/commit/5e43630907aa2d7bc6818142483a33272eab060b) --- # Connect via Gemini CLI Extensions | MCP Toolbox for Databases Connect via Gemini CLI Extensions ================================= Connect to Toolbox via Gemini CLI Extensions. Gemini CLI Extensions --------------------- [Gemini CLI](https://google-gemini.github.io/gemini-cli/) is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an agentic interface for interacting with database and analytics services and popular open-source databases. ### How extensions work Gemini CLI is highly extensible, allowing for the addition of new tools and capabilities through extensions. You can load the extensions from a GitHub URL, a local directory, or a configurable registry. They provide new tools, slash commands, and prompts to assist with your workflow. Use the Gemini CLI Extensions to load prebuilt or custom tools to interact with your databases. Below are a list of Gemini CLI Extensions powered by MCP Toolbox: * [alloydb](https://github.com/gemini-cli-extensions/alloydb) * [alloydb-observability](https://github.com/gemini-cli-extensions/alloydb-observability) * [bigquery-conversational-analytics](https://github.com/gemini-cli-extensions/bigquery-conversational-analytics) * [bigquery-data-analytics](https://github.com/gemini-cli-extensions/bigquery-data-analytics) * [cloud-sql-mysql](https://github.com/gemini-cli-extensions/cloud-sql-mysql) * [cloud-sql-mysql-observability](https://github.com/gemini-cli-extensions/cloud-sql-mysql-observability) * [cloud-sql-postgresql](https://github.com/gemini-cli-extensions/cloud-sql-postgresql) * [cloud-sql-postgresql-observability](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability) * [cloud-sql-sqlserver](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver) * [cloud-sql-sqlserver-observability](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability) * [dataplex](https://github.com/gemini-cli-extensions/dataplex) * [firestore-native](https://github.com/gemini-cli-extensions/firestore-native) * [looker](https://github.com/gemini-cli-extensions/looker) * [mcp-toolbox](https://github.com/gemini-cli-extensions/mcp-toolbox) * [mysql](https://github.com/gemini-cli-extensions/mysql) * [postgres](https://github.com/gemini-cli-extensions/postgres) * [spanner](https://github.com/gemini-cli-extensions/spanner) * [sql-server](https://github.com/gemini-cli-extensions/sql-server) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Connect via MCP Client | MCP Toolbox for Databases Connect via MCP Client ====================== How to connect to Toolbox from a MCP Client. Toolbox SDKs vs Model Context Protocol (MCP) -------------------------------------------- Toolbox now supports connections via both the native Toolbox SDKs and via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) . However, Toolbox has several features which are not supported in the MCP specification (such as Authenticated Parameters and Authorized invocation). We recommend using the native SDKs over MCP clients to leverage these features. The native SDKs can be combined with MCP clients in many cases. ### Protocol Versions Toolbox currently supports the following versions of MCP specification: * [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) * [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26) * [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05) ### Toolbox AuthZ/AuthN Not Supported by MCP The auth implementation in Toolbox is not supported in MCP’s auth specification. This includes: * [Authenticated Parameters](https://mcp-toolbox.dev/v0.24.0/resources/tools/#authenticated-parameters) * [Authorized Invocations](https://mcp-toolbox.dev/v0.24.0/resources/tools/#authorized-invocations) Connecting to Toolbox with an MCP client ---------------------------------------- ### Before you begin Note MCP is only compatible with Toolbox version 0.3.0 and above. 1. [Install](https://mcp-toolbox.dev/v0.24.0/getting-started/introduction/#installing-the-server) Toolbox version 0.3.0+. 2. Make sure you’ve set up and initialized your database. 3. [Set up](https://mcp-toolbox.dev/v0.24.0/getting-started/configure/) your `tools.yaml` file. ### Connecting via Standard Input/Output (stdio) Toolbox supports the [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) transport protocol. Users that wish to use stdio will have to include the `--stdio` flag when running Toolbox. ./toolbox --stdio When running with stdio, Toolbox will listen via stdio instead of acting as a remote HTTP server. Logs will be set to the `warn` level by default. `debug` and `info` logs are not supported with stdio. Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. ### Connecting via HTTP Toolbox supports the HTTP transport protocol with and without SSE. * HTTP with SSE (deprecated) * Streamable HTTP Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "sse", "url": "http://127.0.0.1:5000/mcp/sse", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}/sse"`. HTTP with SSE is only supported in version `2024-11-05` and is currently deprecated. Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "http", "url": "http://127.0.0.1:5000/mcp", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}"`. ### Using the MCP Inspector with Toolbox Use MCP [Inspector](https://github.com/modelcontextprotocol/inspector) for testing and debugging Toolbox server. * STDIO * HTTP with SSE (deprecated) * Streamable HTTP 1. Run Inspector with Toolbox as a subprocess: npx @modelcontextprotocol/inspector ./toolbox --stdio 2. For `Transport Type` dropdown menu, select `STDIO`. 3. In `Command`, make sure that it is set to :`./toolbox` (or the correct path to where the Toolbox binary is installed). 4. In `Arguments`, make sure that it’s filled with `--stdio`. 5. Click the `Connect` button. It might take awhile to spin up Toolbox. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.24.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `SSE`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp/sse` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}/sse` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.24.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `Streamable HTTP`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! ### Tested Clients | Client | SSE Works | MCP Config Docs | | --- | --- | --- | | Claude Desktop | ✅ | [https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop](https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop) | | MCP Inspector | ✅ | [https://github.com/modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) | | Cursor | ✅ | [https://docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol) | | Windsurf | ✅ | [https://docs.windsurf.com/windsurf/mcp](https://docs.windsurf.com/windsurf/mcp) | | VS Code (Insiders) | ✅ | [https://code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Toolbox UI | MCP Toolbox for Databases Toolbox UI ========== How to effectively use Toolbox UI. Toolbox UI is a built-in web interface that allows users to visually inspect and test out configured resources such as tools and toolsets. Launching Toolbox UI -------------------- To launch Toolbox’s interactive UI, use the `--ui` flag. ./toolbox --ui Toolbox UI will be served from the same host and port as the Toolbox Server, with the `/ui` suffix. Once Toolbox is launched, the following INFO log with Toolbox UI’s url will be shown: INFO "Toolbox UI is up and running at: http://localhost:5000/ui" Navigating the Tools Page ------------------------- The tools page shows all tools loaded from your configuration file. This corresponds to the default toolset (represented by an empty string). Each tool’s name on this page will exactly match its name in the configuration file. To view details for a specific tool, click on the tool name. The main content area will be populated with the tool name, description, and available parameters. ![Tools Page](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/tools.png) ### Invoking a Tool 1. Click on a Tool 2. Enter appropriate parameters in each parameter field 3. Click “Run Tool” 4. Done! Your results will appear in the response field 5. (Optional) Uncheck “Prettify JSON” to format the response as plain text ![Run Tool Demo GIF](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/run-tool.gif) ### Optional Parameters Toolbox allows users to add [optional parameters](https://mcp-toolbox.dev/v0.24.0/resources/tools/#basic-parameters) with or without a default value. To exclude a parameter, uncheck the box to the right of an associated parameter, and that parameter will not be included in the request body. If the parameter is not sent, Toolbox will either use it as `nil` value or the `default` value, if configured. If the parameter is required, Toolbox will throw an error. When the box is checked, parameter will be sent exactly as entered in the response field (e.g. empty string). ![Optional Parameter checked example](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/optional-param-checked.png) ![Optional Parameter unchecked example](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/optional-param-unchecked.png) ### Editing Headers To edit headers, press the “Edit Headers” button to display the header modal. Within this modal, users can make direct edits by typing into the header’s text area. Toolbox UI validates that the headers are in correct JSON format. Other header-related errors (e.g., incorrect header names or values required by the tool) will be reported in the Response section after running the tool. ![Edit Headers](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/edit-headers.png) #### Google OAuth Currently, Toolbox supports Google OAuth 2.0 as an AuthService, which allows tools to utilize authorized parameters. When a tool uses an authorized parameter, the parameter will be displayed but not editable, as it will be populated from the authentication token. To provide the token, add your Google OAuth ID Token to the request header using the “Edit Headers” button and modal described above. The key should be the name of your AuthService as defined in your tool configuration file, suffixed with `_token`. The value should be your ID token as a string. 1. Select a tool that requires [authenticated parameters](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/) 2. The auth parameter’s text field is greyed out. This is because it cannot be entered manually and will be parsed from the resolved auth token 3. To update request headers with the token, select “Edit Headers” 4. (Optional) If you wish to manually edit the header, checkout the dropdown “How to extract Google OAuth ID Token manually” for guidance on retrieving ID token 5. To edit the header automatically, click the “Auto Setup” button that is associated with your Auth Profile 6. Enter the Client ID defined in your tools configuration file 7. Click “Continue” 8. Click “Sign in With Google” and login with your associated google account. This should automatically populate the header text area with your token 9. Click “Save” 10. Click “Run Tool” { "Content-Type": "application/json", "my-google-auth_token": "YOUR_ID_TOKEN_HERE" } ![Using Authenticated Parameter GIF](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/edit-headers.gif) Navigating the Toolsets Page ---------------------------- Through the toolsets page, users can search for a specific toolset to retrieve tools from. Simply enter the toolset name in the search bar, and press “Enter” to retrieve the associated tools. If the toolset name is not defined within the tools configuration file, an error message will be displayed. ![Toolsets Page](https://mcp-toolbox.dev/v0.24.0/how-to/toolbox-ui/toolsets.png) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # SQLite using MCP | MCP Toolbox for Databases SQLite using MCP ================ Connect your IDE to SQLite using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQLite. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQLite instance: * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQLite database file.](https://www.sqlite.org/download.html) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } Use Tools --------- Your AI tool is now connected to SQLite using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 2, 2026: [chore(main): release 0.28.0 (#2472) (81253a0bd70)](https://github.com/googleapis/genai-toolbox/commit/81253a0bd7049a2e2681ef13631a768cb402040e) --- # Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for PostgreSQL Admin using MCP ======================================== Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for PostgreSQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for PostgreSQL using MCP. The `cloud-sql-postgres-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for PostgreSQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for PostgreSQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases Deploy ADK Agent and MCP Toolbox ================================ How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. Before you begin ---------------- This guide assumes you have already done the following: 1. Completed the [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.24.0/getting-started/local_quickstart/) and have a working ADK agent running locally. 2. Installed the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) . 3. A Google Cloud project with billing enabled. Step 1: Deploy MCP Toolbox to Cloud Run --------------------------------------- Before deploying your agent, your MCP Toolbox server needs to be accessible from the cloud. We will deploy MCP Toolbox to Cloud Run. Follow the [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.24.0/how-to/deploy_toolbox/) guide to deploy your MCP Toolbox instance. #### Important After deployment, note down the Service URL of your MCP Toolbox Cloud Run service. You will need this to configure your agent. Step 2: Prepare your Agent for Deployment ----------------------------------------- We will use the `agent-starter-pack` tool to enhance your local agent project with the necessary configuration for deployment to Vertex AI Agent Engine. 1. Open a terminal and navigate to the **parent directory** of your agent project (the directory containing the `my_agent` folder). 2. Run the following command to enhance your project: uvx agent-starter-pack enhance --adk -d agent_engine 3. Follow the interactive prompts to configure your deployment settings. This process will generate deployment configuration files (like a `Makefile` and `Dockerfile`) in your project directory. 4. Add `toolbox-core` as a dependency to the new project: uv add toolbox-core Step 3: Configure Google Cloud Authentication --------------------------------------------- Ensure your local environment is authenticated with Google Cloud to perform the deployment. 1. Login with Application Default Credentials (ADC): gcloud auth application-default login 2. Set your active project: gcloud config set project Step 4: Connect Agent to Deployed MCP Toolbox --------------------------------------------- You need to update your agent’s code to connect to the Cloud Run URL of your MCP Toolbox instead of the local address. 1. Recall that you can find the Cloud Run deployment URL of the MCP Toolbox server using the following command: gcloud run services describe toolbox --format 'value(status.url)' 2. Open your agent file (`my_agent/agent.py`). 3. Update the `ToolboxSyncClient` initialization to use your Cloud Run URL. Since Cloud Run services are secured by default, you also need to provide an authentication token. Replace your existing client initialization code with the following: from google.adk import Agent from google.adk.apps import App from toolbox_core import ToolboxSyncClient, auth_methods # TODO(developer): Replace with your Toolbox Cloud Run Service URL TOOLBOX_URL = "https://your-toolbox-service-xyz.a.run.app" # Initialize the client with the Cloud Run URL and Auth headers client = ToolboxSyncClient( TOOLBOX_URL, client_headers={"Authorization": auth_methods.get_google_id_token(TOOLBOX_URL)} ) root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=client.load_toolset(), ) app = App(root_agent=root_agent, name="my_agent") #### Important Ensure that the `name` parameter in the `App` initialization matches the name of your agent’s parent directory (e.g., `my_agent`). ... app = App(root_agent=root_agent, name="my_agent") Step 5: Deploy to Agent Engine ------------------------------ Run the deployment command: make backend This command will build your agent’s container image and deploy it to Vertex AI. Step 6: Test your Deployment ---------------------------- Once the deployment command (`make backend`) completes, it will output the URL for the Agent Engine Playground. You can click on this URL to open the Playground in your browser and start chatting with your agent to test the tools. For additional test scenarios, refer to the [Test deployed agent](https://google.github.io/adk-docs/deploy/agent-engine/#test-deployment) section in the ADK documentation. Last modified November 26, 2025: [docs: Add guide for deploying ADK Agent to Agent Engine with Cloud Run Toolbox (#2035) (9315dba9968)](https://github.com/googleapis/genai-toolbox/commit/9315dba9968946299ce679df9aa4d4c73d0762fa) --- # Connect via MCP Client | MCP Toolbox for Databases Connect via MCP Client ====================== How to connect to Toolbox from a MCP Client. Toolbox SDKs vs Model Context Protocol (MCP) -------------------------------------------- Toolbox now supports connections via both the native Toolbox SDKs and via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) . However, Toolbox has several features which are not supported in the MCP specification (such as Authenticated Parameters and Authorized invocation). We recommend using the native SDKs over MCP clients to leverage these features. The native SDKs can be combined with MCP clients in many cases. ### Protocol Versions Toolbox currently supports the following versions of MCP specification: * [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) * [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26) * [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05) ### Toolbox AuthZ/AuthN Not Supported by MCP The auth implementation in Toolbox is not supported in MCP’s auth specification. This includes: * [Authenticated Parameters](https://mcp-toolbox.dev/v0.25.0/resources/tools/#authenticated-parameters) * [Authorized Invocations](https://mcp-toolbox.dev/v0.25.0/resources/tools/#authorized-invocations) Connecting to Toolbox with an MCP client ---------------------------------------- ### Before you begin Note MCP is only compatible with Toolbox version 0.3.0 and above. 1. [Install](https://mcp-toolbox.dev/v0.25.0/getting-started/introduction/#installing-the-server) Toolbox version 0.3.0+. 2. Make sure you’ve set up and initialized your database. 3. [Set up](https://mcp-toolbox.dev/v0.25.0/getting-started/configure/) your `tools.yaml` file. ### Connecting via Standard Input/Output (stdio) Toolbox supports the [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) transport protocol. Users that wish to use stdio will have to include the `--stdio` flag when running Toolbox. ./toolbox --stdio When running with stdio, Toolbox will listen via stdio instead of acting as a remote HTTP server. Logs will be set to the `warn` level by default. `debug` and `info` logs are not supported with stdio. Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. ### Connecting via HTTP Toolbox supports the HTTP transport protocol with and without SSE. * HTTP with SSE (deprecated) * Streamable HTTP Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "sse", "url": "http://127.0.0.1:5000/mcp/sse", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}/sse"`. HTTP with SSE is only supported in version `2024-11-05` and is currently deprecated. Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "http", "url": "http://127.0.0.1:5000/mcp", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}"`. ### Using the MCP Inspector with Toolbox Use MCP [Inspector](https://github.com/modelcontextprotocol/inspector) for testing and debugging Toolbox server. * STDIO * HTTP with SSE (deprecated) * Streamable HTTP 1. Run Inspector with Toolbox as a subprocess: npx @modelcontextprotocol/inspector ./toolbox --stdio 2. For `Transport Type` dropdown menu, select `STDIO`. 3. In `Command`, make sure that it is set to :`./toolbox` (or the correct path to where the Toolbox binary is installed). 4. In `Arguments`, make sure that it’s filled with `--stdio`. 5. Click the `Connect` button. It might take awhile to spin up Toolbox. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.25.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `SSE`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp/sse` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}/sse` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.25.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `Streamable HTTP`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! ### Tested Clients | Client | SSE Works | MCP Config Docs | | --- | --- | --- | | Claude Desktop | ✅ | [https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop](https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop) | | MCP Inspector | ✅ | [https://github.com/modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) | | Cursor | ✅ | [https://docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol) | | Windsurf | ✅ | [https://docs.windsurf.com/windsurf/mcp](https://docs.windsurf.com/windsurf/mcp) | | VS Code (Insiders) | ✅ | [https://code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server Admin using MCP ======================================== Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for SQL Server instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.25.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for SQL Server using MCP. The `cloud-sql-mssql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for SQL Server instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for SQL Server instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified December 2, 2025: [feat(prebuilt/cloud-sql): Add clone instance tool for cloud sql (#1845) (5e43630907a)](https://github.com/googleapis/genai-toolbox/commit/5e43630907aa2d7bc6818142483a33272eab060b) --- # Deploy to Cloud Run | MCP Toolbox for Databases Deploy to Cloud Run =================== How to set up and configure Toolbox to run on Cloud Run. Before you begin ---------------- 1. [Install](https://cloud.google.com/sdk/docs/install) the Google Cloud CLI. 2. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. Make sure you’ve set up and initialized your database. 5. You must have the following APIs enabled: gcloud services enable run.googleapis.com \ cloudbuild.googleapis.com \ artifactregistry.googleapis.com \ iam.googleapis.com \ secretmanager.googleapis.com 6. To create an IAM account, you must have the following IAM permissions (or roles): * Create Service Account role (roles/iam.serviceAccountCreator) 7. To create a secret, you must have the following roles: * Secret Manager Admin role (roles/secretmanager.admin) 8. To deploy to Cloud Run, you must have the following set of roles: * Cloud Run Developer (roles/run.developer) * Service Account User role (roles/iam.serviceAccountUser) Note If you are using sources that require VPC-access (such as AlloyDB or Cloud SQL over private IP), make sure your Cloud Run service and the database are in the same VPC network. Create a service account ------------------------ 1. Create a backend service account if you don’t already have one: gcloud iam service-accounts create toolbox-identity 2. Grant permissions to use secret manager: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/secretmanager.secretAccessor 3. Grant additional permissions to the service account that are specific to the source, e.g.: * [AlloyDB for PostgreSQL](https://mcp-toolbox.dev/v0.24.0/resources/sources/alloydb-pg/#iam-permissions) * [Cloud SQL for PostgreSQL](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-sql-pg/#iam-permissions) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://mcp-toolbox.dev/v0.24.0/resources/sources/) section. Deploy to Cloud Run ------------------- 1. Upload `tools.yaml` as a secret: gcloud secrets create tools --data-file=tools.yaml If you already have a secret and want to update the secret version, execute the following: gcloud secrets versions add tools --data-file=tools.yaml 2. Set an environment variable to the container image that you want to use for cloud run: export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest Note **The `$PORT` Environment Variable** Google Cloud Run dictates the port your application must listen on by setting the `$PORT` environment variable inside your container. This value defaults to **8080**. Your application’s `--port` argument **must** be set to listen on this port. If there is a mismatch, the container will fail to start and the deployment will time out. 3. Deploy Toolbox to Cloud Run using the following command: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud ### Update deployed server to be secure To prevent DNS rebinding attack, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. In order to do that, you will have to re-deploy the cloud run service with the new flag. 1. Set an environment variable to the cloud run url: export URL= 2. Redeploy Toolbox: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud Connecting with Toolbox Client SDK ---------------------------------- You can connect to Toolbox Cloud Run instances directly through the SDK. 1. [Set up `Cloud Run Invoker` role access](https://cloud.google.com/run/docs/securing/managing-access#service-add-principals) to your Cloud Run service. 2. (Only for local runs) Set up [Application Default Credentials](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for the principal you set up the `Cloud Run Invoker` role access to. 3. Run the following to retrieve a non-deterministic URL for the cloud run service: gcloud run services describe toolbox --format 'value(status.url)' 4. Import and initialize the toolbox client with the URL retrieved above: * Python * Javascript * Go import asyncio from toolbox_core import ToolboxClient, auth_methods # Replace with the Cloud Run service URL generated in the previous step URL = "https://cloud-run-url.app" auth_token_provider = auth_methods.aget_google_id_token(URL) # can also use sync method async def main(): async with ToolboxClient( URL, client_headers={"Authorization": auth_token_provider}, ) as toolbox: toolset = await toolbox.load_toolset() # ... asyncio.run(main()) import { ToolboxClient } from '@toolbox-sdk/core'; import {getGoogleIdToken} from '@toolbox-sdk/core/auth' // Replace with the Cloud Run service URL generated in the previous step. const URL = 'http://127.0.0.1:5000'; const authTokenProvider = () => getGoogleIdToken(URL); const client = new ToolboxClient(URL, null, {"Authorization": authTokenProvider}); import "github.com/googleapis/mcp-toolbox-sdk-go/core" func main() { // Replace with the Cloud Run service URL generated in the previous step. URL := "http://127.0.0.1:5000" auth_token_provider, err := core.GetGoogleIDToken(ctx, URL) if err != nil { log.Fatalf("Failed to fetch token %v", err) } toolboxClient, err := core.NewToolboxClient( URL, core.WithClientHeaderString("Authorization", auth_token_provider)) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } } Now, you can use this client to connect to the deployed Cloud Run instance! Troubleshooting --------------- Note For any deployment or runtime error, the best first step is to check the logs for your service in the Google Cloud Console’s Cloud Run section. They often contain the specific error message needed to diagnose the problem. * **Deployment Fails with “Container failed to start”:** This is almost always caused by a port mismatch. Ensure your container’s `--port` argument is set to `8080` to match the `$PORT` environment variable provided by Cloud Run. * **Client Receives Permission Denied Error (401 or 403):** If your client application (e.g., your local SDK) gets a `401 Unauthorized` or `403 Forbidden` error when trying to call your Cloud Run service, it means the client is not properly authenticated as an invoker. * Ensure the user or service account calling the service has the **Cloud Run Invoker** (`roles/run.invoker`) IAM role. * If running locally, make sure your Application Default Credentials are set up correctly by running `gcloud auth application-default login`. * **Service Fails to Access Secrets (in logs):** If your application starts but the logs show errors like “permission denied” when trying to access Secret Manager, it means the Toolbox service account is missing permissions. * Ensure the `toolbox-identity` service account has the **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`) IAM role. Last modified November 27, 2025: [feat: add allowed-origins flag (#1984) (862868f2847)](https://github.com/googleapis/genai-toolbox/commit/862868f28476ea981575ce412faa7d6a03138f31) --- # Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for PostgreSQL Admin using MCP ======================================== Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for PostgreSQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for PostgreSQL using MCP. The `cloud-sql-postgres-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for PostgreSQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for PostgreSQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for MySQL Admin using MCP =================================== Create and manage Cloud SQL for MySQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for MySQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for MySQL using MCP. The `cloud-sql-mysql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for MySQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for MySQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Connect via Gemini CLI Extensions | MCP Toolbox for Databases Connect via Gemini CLI Extensions ================================= Connect to Toolbox via Gemini CLI Extensions. Gemini CLI Extensions --------------------- [Gemini CLI](https://google-gemini.github.io/gemini-cli/) is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an agentic interface for interacting with database and analytics services and popular open-source databases. ### How extensions work Gemini CLI is highly extensible, allowing for the addition of new tools and capabilities through extensions. You can load the extensions from a GitHub URL, a local directory, or a configurable registry. They provide new tools, slash commands, and prompts to assist with your workflow. Use the Gemini CLI Extensions to load prebuilt or custom tools to interact with your databases. Below are a list of Gemini CLI Extensions powered by MCP Toolbox: * [alloydb](https://github.com/gemini-cli-extensions/alloydb) * [alloydb-observability](https://github.com/gemini-cli-extensions/alloydb-observability) * [bigquery-conversational-analytics](https://github.com/gemini-cli-extensions/bigquery-conversational-analytics) * [bigquery-data-analytics](https://github.com/gemini-cli-extensions/bigquery-data-analytics) * [cloud-sql-mysql](https://github.com/gemini-cli-extensions/cloud-sql-mysql) * [cloud-sql-mysql-observability](https://github.com/gemini-cli-extensions/cloud-sql-mysql-observability) * [cloud-sql-postgresql](https://github.com/gemini-cli-extensions/cloud-sql-postgresql) * [cloud-sql-postgresql-observability](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability) * [cloud-sql-sqlserver](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver) * [cloud-sql-sqlserver-observability](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability) * [dataplex](https://github.com/gemini-cli-extensions/dataplex) * [firestore-native](https://github.com/gemini-cli-extensions/firestore-native) * [looker](https://github.com/gemini-cli-extensions/looker) * [mcp-toolbox](https://github.com/gemini-cli-extensions/mcp-toolbox) * [mysql](https://github.com/gemini-cli-extensions/mysql) * [postgres](https://github.com/gemini-cli-extensions/postgres) * [spanner](https://github.com/gemini-cli-extensions/spanner) * [sql-server](https://github.com/gemini-cli-extensions/sql-server) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server Admin using MCP ======================================== Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for SQL Server instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.26.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for SQL Server using MCP. The `cloud-sql-mssql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for SQL Server instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for SQL Server instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Toolbox UI | MCP Toolbox for Databases Toolbox UI ========== How to effectively use Toolbox UI. Toolbox UI is a built-in web interface that allows users to visually inspect and test out configured resources such as tools and toolsets. Launching Toolbox UI -------------------- To launch Toolbox’s interactive UI, use the `--ui` flag. ./toolbox --ui Toolbox UI will be served from the same host and port as the Toolbox Server, with the `/ui` suffix. Once Toolbox is launched, the following INFO log with Toolbox UI’s url will be shown: INFO "Toolbox UI is up and running at: http://localhost:5000/ui" Navigating the Tools Page ------------------------- The tools page shows all tools loaded from your configuration file. This corresponds to the default toolset (represented by an empty string). Each tool’s name on this page will exactly match its name in the configuration file. To view details for a specific tool, click on the tool name. The main content area will be populated with the tool name, description, and available parameters. ![Tools Page](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/tools.png) ### Invoking a Tool 1. Click on a Tool 2. Enter appropriate parameters in each parameter field 3. Click “Run Tool” 4. Done! Your results will appear in the response field 5. (Optional) Uncheck “Prettify JSON” to format the response as plain text ![Run Tool Demo GIF](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/run-tool.gif) ### Optional Parameters Toolbox allows users to add [optional parameters](https://mcp-toolbox.dev/v0.25.0/resources/tools/#basic-parameters) with or without a default value. To exclude a parameter, uncheck the box to the right of an associated parameter, and that parameter will not be included in the request body. If the parameter is not sent, Toolbox will either use it as `nil` value or the `default` value, if configured. If the parameter is required, Toolbox will throw an error. When the box is checked, parameter will be sent exactly as entered in the response field (e.g. empty string). ![Optional Parameter checked example](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/optional-param-checked.png) ![Optional Parameter unchecked example](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/optional-param-unchecked.png) ### Editing Headers To edit headers, press the “Edit Headers” button to display the header modal. Within this modal, users can make direct edits by typing into the header’s text area. Toolbox UI validates that the headers are in correct JSON format. Other header-related errors (e.g., incorrect header names or values required by the tool) will be reported in the Response section after running the tool. ![Edit Headers](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/edit-headers.png) #### Google OAuth Currently, Toolbox supports Google OAuth 2.0 as an AuthService, which allows tools to utilize authorized parameters. When a tool uses an authorized parameter, the parameter will be displayed but not editable, as it will be populated from the authentication token. To provide the token, add your Google OAuth ID Token to the request header using the “Edit Headers” button and modal described above. The key should be the name of your AuthService as defined in your tool configuration file, suffixed with `_token`. The value should be your ID token as a string. 1. Select a tool that requires [authenticated parameters](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/) 2. The auth parameter’s text field is greyed out. This is because it cannot be entered manually and will be parsed from the resolved auth token 3. To update request headers with the token, select “Edit Headers” 4. (Optional) If you wish to manually edit the header, checkout the dropdown “How to extract Google OAuth ID Token manually” for guidance on retrieving ID token 5. To edit the header automatically, click the “Auto Setup” button that is associated with your Auth Profile 6. Enter the Client ID defined in your tools configuration file 7. Click “Continue” 8. Click “Sign in With Google” and login with your associated google account. This should automatically populate the header text area with your token 9. Click “Save” 10. Click “Run Tool” { "Content-Type": "application/json", "my-google-auth_token": "YOUR_ID_TOKEN_HERE" } ![Using Authenticated Parameter GIF](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/edit-headers.gif) Navigating the Toolsets Page ---------------------------- Through the toolsets page, users can search for a specific toolset to retrieve tools from. Simply enter the toolset name in the search bar, and press “Enter” to retrieve the associated tools. If the toolset name is not defined within the tools configuration file, an error message will be displayed. ![Toolsets Page](https://mcp-toolbox.dev/v0.25.0/how-to/toolbox-ui/toolsets.png) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for MySQL Admin using MCP =================================== Create and manage Cloud SQL for MySQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for MySQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for MySQL using MCP. The `cloud-sql-mysql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for MySQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for MySQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Toolbox UI | MCP Toolbox for Databases Toolbox UI ========== How to effectively use Toolbox UI. Toolbox UI is a built-in web interface that allows users to visually inspect and test out configured resources such as tools and toolsets. Launching Toolbox UI -------------------- To launch Toolbox’s interactive UI, use the `--ui` flag. ./toolbox --ui Toolbox UI will be served from the same host and port as the Toolbox Server, with the `/ui` suffix. Once Toolbox is launched, the following INFO log with Toolbox UI’s url will be shown: INFO "Toolbox UI is up and running at: http://localhost:5000/ui" Navigating the Tools Page ------------------------- The tools page shows all tools loaded from your configuration file. This corresponds to the default toolset (represented by an empty string). Each tool’s name on this page will exactly match its name in the configuration file. To view details for a specific tool, click on the tool name. The main content area will be populated with the tool name, description, and available parameters. ![Tools Page](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/tools.png) ### Invoking a Tool 1. Click on a Tool 2. Enter appropriate parameters in each parameter field 3. Click “Run Tool” 4. Done! Your results will appear in the response field 5. (Optional) Uncheck “Prettify JSON” to format the response as plain text ![Run Tool Demo GIF](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/run-tool.gif) ### Optional Parameters Toolbox allows users to add [optional parameters](https://mcp-toolbox.dev/v0.26.0/resources/tools/#basic-parameters) with or without a default value. To exclude a parameter, uncheck the box to the right of an associated parameter, and that parameter will not be included in the request body. If the parameter is not sent, Toolbox will either use it as `nil` value or the `default` value, if configured. If the parameter is required, Toolbox will throw an error. When the box is checked, parameter will be sent exactly as entered in the response field (e.g. empty string). ![Optional Parameter checked example](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/optional-param-checked.png) ![Optional Parameter unchecked example](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/optional-param-unchecked.png) ### Editing Headers To edit headers, press the “Edit Headers” button to display the header modal. Within this modal, users can make direct edits by typing into the header’s text area. Toolbox UI validates that the headers are in correct JSON format. Other header-related errors (e.g., incorrect header names or values required by the tool) will be reported in the Response section after running the tool. ![Edit Headers](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/edit-headers.png) #### Google OAuth Currently, Toolbox supports Google OAuth 2.0 as an AuthService, which allows tools to utilize authorized parameters. When a tool uses an authorized parameter, the parameter will be displayed but not editable, as it will be populated from the authentication token. To provide the token, add your Google OAuth ID Token to the request header using the “Edit Headers” button and modal described above. The key should be the name of your AuthService as defined in your tool configuration file, suffixed with `_token`. The value should be your ID token as a string. 1. Select a tool that requires [authenticated parameters](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/) 2. The auth parameter’s text field is greyed out. This is because it cannot be entered manually and will be parsed from the resolved auth token 3. To update request headers with the token, select “Edit Headers” 4. (Optional) If you wish to manually edit the header, checkout the dropdown “How to extract Google OAuth ID Token manually” for guidance on retrieving ID token 5. To edit the header automatically, click the “Auto Setup” button that is associated with your Auth Profile 6. Enter the Client ID defined in your tools configuration file 7. Click “Continue” 8. Click “Sign in With Google” and login with your associated google account. This should automatically populate the header text area with your token 9. Click “Save” 10. Click “Run Tool” { "Content-Type": "application/json", "my-google-auth_token": "YOUR_ID_TOKEN_HERE" } ![Using Authenticated Parameter GIF](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/edit-headers.gif) Navigating the Toolsets Page ---------------------------- Through the toolsets page, users can search for a specific toolset to retrieve tools from. Simply enter the toolset name in the search bar, and press “Enter” to retrieve the associated tools. If the toolset name is not defined within the tools configuration file, an error message will be displayed. ![Toolsets Page](https://mcp-toolbox.dev/v0.26.0/how-to/toolbox-ui/toolsets.png) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Deploy to Kubernetes | MCP Toolbox for Databases Deploy to Kubernetes ==================== How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). Before you begin ---------------- 1. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 2. [Install the `gcloud` CLI](https://cloud.google.com/sdk/docs/install) . 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. You must have the following APIs enabled: gcloud services enable artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ container.googleapis.com \ iam.googleapis.com 5. `kubectl` is used to manage Kubernetes, the cluster orchestration system used by GKE. Verify if you have `kubectl` installed: kubectl version --client 6. If needed, install `kubectl` component using the Google Cloud CLI: gcloud components install kubectl Create a service account ------------------------ 1. Specify a name for your service account with an environment variable: export SA_NAME=toolbox 2. Create a backend service account: gcloud iam service-accounts create $SA_NAME 3. Grant any IAM roles necessary to the IAM service account. Each source has a list of necessary IAM permissions listed on its page. The example below is for cloud sql postgres source: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudsql.client * [AlloyDB IAM Identity](https://mcp-toolbox.dev/v0.24.0/resources/sources/alloydb-pg/#iam-permissions) * [CloudSQL IAM Identity](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-sql-pg/#iam-permissions) * [Spanner IAM Identity](https://mcp-toolbox.dev/v0.24.0/resources/sources/spanner/#iam-permissions) Deploy to Kubernetes -------------------- 1. Set environment variables: export CLUSTER_NAME=toolbox-cluster export DEPLOYMENT_NAME=toolbox export SERVICE_NAME=toolbox-service export REGION=us-central1 export NAMESPACE=toolbox-namespace export SECRET_NAME=toolbox-config export KSA_NAME=toolbox-service-account 2. Create a [GKE cluster](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-architecture) . gcloud container clusters create-auto $CLUSTER_NAME \ --location=us-central1 3. Get authentication credentials to interact with the cluster. This also configures `kubectl` to use the cluster. gcloud container clusters get-credentials $CLUSTER_NAME \ --region=$REGION \ --project=$PROJECT_ID 4. View the current context for `kubectl`. kubectl config current-context 5. Create namespace for the deployment. kubectl create namespace $NAMESPACE 6. Create a Kubernetes Service Account (KSA). kubectl create serviceaccount $KSA_NAME --namespace $NAMESPACE 7. Enable the IAM binding between Google Service Account (GSA) and Kubernetes Service Account (KSA). gcloud iam service-accounts add-iam-policy-binding \ --role="roles/iam.workloadIdentityUser" \ --member="serviceAccount:$PROJECT_ID.svc.id.goog[$NAMESPACE/$KSA_NAME]" \ $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com 8. Add annotation to KSA to complete binding: kubectl annotate serviceaccount \ $KSA_NAME \ iam.gke.io/gcp-service-account=$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --namespace $NAMESPACE 9. Prepare the Kubernetes secret for your `tools.yaml` file. kubectl create secret generic $SECRET_NAME \ --from-file=./tools.yaml \ --namespace=$NAMESPACE 10. Create a Kubernetes manifest file (`k8s_deployment.yaml`) to build deployment. apiVersion: apps/v1 kind: Deployment metadata: name: toolbox namespace: toolbox-namespace spec: selector: matchLabels: app: toolbox template: metadata: labels: app: toolbox spec: serviceAccountName: toolbox-service-account containers: - name: toolbox # Recommend to use the latest version of toolbox image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest args: ["--address", "0.0.0.0"] ports: - containerPort: 5000 volumeMounts: - name: toolbox-config mountPath: "/app/tools.yaml" subPath: tools.yaml readOnly: true volumes: - name: toolbox-config secret: secretName: toolbox-config items: - key: tools.yaml path: tools.yaml Tip To prevent DNS rebinding attack, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. E.g. `args: ["--address", "0.0.0.0", "--allowed-origins", "https://foo.bar"]` 11. Create the deployment. kubectl apply -f k8s_deployment.yaml --namespace $NAMESPACE 12. Check the status of deployment. kubectl get deployments --namespace $NAMESPACE 13. Create a Kubernetes manifest file (`k8s_service.yaml`) to build service. apiVersion: v1 kind: Service metadata: name: toolbox-service namespace: toolbox-namespace annotations: cloud.google.com/l4-rbs: "enabled" spec: selector: app: toolbox ports: - port: 5000 targetPort: 5000 type: LoadBalancer 14. Create the service. kubectl apply -f k8s_service.yaml --namespace $NAMESPACE 15. You can find your IP address created for your service by getting the service information through the following. kubectl describe services $SERVICE_NAME --namespace $NAMESPACE 16. To look at logs, run the following. kubectl logs -f deploy/$DEPLOYMENT_NAME --namespace $NAMESPACE 17. You might have to wait a couple of minutes. It is ready when you can see `EXTERNAL-IP` with the following command: kubectl get svc -n $NAMESPACE 18. Access toolbox locally. curl :5000 Clean up resources ------------------ 1. Delete secret. kubectl delete secret $SECRET_NAME --namespace $NAMESPACE 2. Delete deployment. kubectl delete deployment $DEPLOYMENT_NAME --namespace $NAMESPACE 3. Delete the application’s service. kubectl delete service $SERVICE_NAME --namespace $NAMESPACE 4. Delete the Kubernetes cluster. gcloud container clusters delete $CLUSTER_NAME \ --location=$REGION Last modified November 27, 2025: [feat: add allowed-origins flag (#1984) (862868f2847)](https://github.com/googleapis/genai-toolbox/commit/862868f28476ea981575ce412faa7d6a03138f31) --- # Connect via MCP Client | MCP Toolbox for Databases Connect via MCP Client ====================== How to connect to Toolbox from a MCP Client. Toolbox SDKs vs Model Context Protocol (MCP) -------------------------------------------- Toolbox now supports connections via both the native Toolbox SDKs and via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) . However, Toolbox has several features which are not supported in the MCP specification (such as Authenticated Parameters and Authorized invocation). We recommend using the native SDKs over MCP clients to leverage these features. The native SDKs can be combined with MCP clients in many cases. ### Protocol Versions Toolbox currently supports the following versions of MCP specification: * [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) * [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) * [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26) * [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05) ### Toolbox AuthZ/AuthN Not Supported by MCP The auth implementation in Toolbox is not supported in MCP’s auth specification. This includes: * [Authenticated Parameters](https://mcp-toolbox.dev/v0.26.0/resources/tools/#authenticated-parameters) * [Authorized Invocations](https://mcp-toolbox.dev/v0.26.0/resources/tools/#authorized-invocations) Connecting to Toolbox with an MCP client ---------------------------------------- ### Before you begin Note MCP is only compatible with Toolbox version 0.3.0 and above. 1. [Install](https://mcp-toolbox.dev/v0.26.0/getting-started/introduction/#installing-the-server) Toolbox version 0.3.0+. 2. Make sure you’ve set up and initialized your database. 3. [Set up](https://mcp-toolbox.dev/v0.26.0/getting-started/configure/) your `tools.yaml` file. ### Connecting via Standard Input/Output (stdio) Toolbox supports the [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) transport protocol. Users that wish to use stdio will have to include the `--stdio` flag when running Toolbox. ./toolbox --stdio When running with stdio, Toolbox will listen via stdio instead of acting as a remote HTTP server. Logs will be set to the `warn` level by default. `debug` and `info` logs are not supported with stdio. Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. ### Connecting via HTTP Toolbox supports the HTTP transport protocol with and without SSE. * HTTP with SSE (deprecated) * Streamable HTTP Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "sse", "url": "http://127.0.0.1:5000/mcp/sse", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}/sse"`. HTTP with SSE is only supported in version `2024-11-05` and is currently deprecated. Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "http", "url": "http://127.0.0.1:5000/mcp", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}"`. ### Using the MCP Inspector with Toolbox Use MCP [Inspector](https://github.com/modelcontextprotocol/inspector) for testing and debugging Toolbox server. * STDIO * HTTP with SSE (deprecated) * Streamable HTTP 1. Run Inspector with Toolbox as a subprocess: npx @modelcontextprotocol/inspector ./toolbox --stdio 2. For `Transport Type` dropdown menu, select `STDIO`. 3. In `Command`, make sure that it is set to :`./toolbox` (or the correct path to where the Toolbox binary is installed). 4. In `Arguments`, make sure that it’s filled with `--stdio`. 5. Click the `Connect` button. It might take awhile to spin up Toolbox. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.26.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `SSE`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp/sse` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}/sse` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.26.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `Streamable HTTP`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! ### Tested Clients | Client | SSE Works | MCP Config Docs | | --- | --- | --- | | Claude Desktop | ✅ | [https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop](https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop) | | MCP Inspector | ✅ | [https://github.com/modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) | | Cursor | ✅ | [https://docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol) | | Windsurf | ✅ | [https://docs.windsurf.com/windsurf/mcp](https://docs.windsurf.com/windsurf/mcp) | | VS Code (Insiders) | ✅ | [https://code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Last modified January 15, 2026: [feat: add new v20251125 version (#2303) (4d23a3bbf27)](https://github.com/googleapis/genai-toolbox/commit/4d23a3bbf2797b1f7fe328aeb5789e778121da23) --- # Connect via Gemini CLI Extensions | MCP Toolbox for Databases Connect via Gemini CLI Extensions ================================= Connect to Toolbox via Gemini CLI Extensions. Gemini CLI Extensions --------------------- [Gemini CLI](https://google-gemini.github.io/gemini-cli/) is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an agentic interface for interacting with database and analytics services and popular open-source databases. ### How extensions work Gemini CLI is highly extensible, allowing for the addition of new tools and capabilities through extensions. You can load the extensions from a GitHub URL, a local directory, or a configurable registry. They provide new tools, slash commands, and prompts to assist with your workflow. Use the Gemini CLI Extensions to load prebuilt or custom tools to interact with your databases. Below are a list of Gemini CLI Extensions powered by MCP Toolbox: * [alloydb](https://github.com/gemini-cli-extensions/alloydb) * [alloydb-observability](https://github.com/gemini-cli-extensions/alloydb-observability) * [bigquery-conversational-analytics](https://github.com/gemini-cli-extensions/bigquery-conversational-analytics) * [bigquery-data-analytics](https://github.com/gemini-cli-extensions/bigquery-data-analytics) * [cloud-sql-mysql](https://github.com/gemini-cli-extensions/cloud-sql-mysql) * [cloud-sql-mysql-observability](https://github.com/gemini-cli-extensions/cloud-sql-mysql-observability) * [cloud-sql-postgresql](https://github.com/gemini-cli-extensions/cloud-sql-postgresql) * [cloud-sql-postgresql-observability](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability) * [cloud-sql-sqlserver](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver) * [cloud-sql-sqlserver-observability](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability) * [dataplex](https://github.com/gemini-cli-extensions/dataplex) * [firestore-native](https://github.com/gemini-cli-extensions/firestore-native) * [looker](https://github.com/gemini-cli-extensions/looker) * [mcp-toolbox](https://github.com/gemini-cli-extensions/mcp-toolbox) * [mysql](https://github.com/gemini-cli-extensions/mysql) * [postgres](https://github.com/gemini-cli-extensions/postgres) * [spanner](https://github.com/gemini-cli-extensions/spanner) * [sql-server](https://github.com/gemini-cli-extensions/sql-server) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Deploy to Cloud Run | MCP Toolbox for Databases Deploy to Cloud Run =================== How to set up and configure Toolbox to run on Cloud Run. Before you begin ---------------- 1. [Install](https://cloud.google.com/sdk/docs/install) the Google Cloud CLI. 2. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. Make sure you’ve set up and initialized your database. 5. You must have the following APIs enabled: gcloud services enable run.googleapis.com \ cloudbuild.googleapis.com \ artifactregistry.googleapis.com \ iam.googleapis.com \ secretmanager.googleapis.com 6. To create an IAM account, you must have the following IAM permissions (or roles): * Create Service Account role (roles/iam.serviceAccountCreator) 7. To create a secret, you must have the following roles: * Secret Manager Admin role (roles/secretmanager.admin) 8. To deploy to Cloud Run, you must have the following set of roles: * Cloud Run Developer (roles/run.developer) * Service Account User role (roles/iam.serviceAccountUser) Note If you are using sources that require VPC-access (such as AlloyDB or Cloud SQL over private IP), make sure your Cloud Run service and the database are in the same VPC network. Create a service account ------------------------ 1. Create a backend service account if you don’t already have one: gcloud iam service-accounts create toolbox-identity 2. Grant permissions to use secret manager: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/secretmanager.secretAccessor 3. Grant additional permissions to the service account that are specific to the source, e.g.: * [AlloyDB for PostgreSQL](https://mcp-toolbox.dev/v0.25.0/resources/sources/alloydb-pg/#iam-permissions) * [Cloud SQL for PostgreSQL](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-sql-pg/#iam-permissions) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://mcp-toolbox.dev/v0.25.0/resources/sources/) section. Deploy to Cloud Run ------------------- 1. Upload `tools.yaml` as a secret: gcloud secrets create tools --data-file=tools.yaml If you already have a secret and want to update the secret version, execute the following: gcloud secrets versions add tools --data-file=tools.yaml 2. Set an environment variable to the container image that you want to use for cloud run: export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest Note **The `$PORT` Environment Variable** Google Cloud Run dictates the port your application must listen on by setting the `$PORT` environment variable inside your container. This value defaults to **8080**. Your application’s `--port` argument **must** be set to listen on this port. If there is a mismatch, the container will fail to start and the deployment will time out. 3. Deploy Toolbox to Cloud Run using the following command: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud ### Update deployed server to be secure To prevent DNS rebinding attack, use the `--allowed-hosts` flag to specify a list of hosts. In order to do that, you will have to re-deploy the cloud run service with the new flag. To implement CORs checks, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. 1. Set an environment variable to the cloud run url: export URL= export HOST= 2. Redeploy Toolbox: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud Connecting with Toolbox Client SDK ---------------------------------- You can connect to Toolbox Cloud Run instances directly through the SDK. 1. [Set up `Cloud Run Invoker` role access](https://cloud.google.com/run/docs/securing/managing-access#service-add-principals) to your Cloud Run service. 2. (Only for local runs) Set up [Application Default Credentials](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for the principal you set up the `Cloud Run Invoker` role access to. 3. Run the following to retrieve a non-deterministic URL for the cloud run service: gcloud run services describe toolbox --format 'value(status.url)' 4. Import and initialize the toolbox client with the URL retrieved above: * Python * Javascript * Go import asyncio from toolbox_core import ToolboxClient, auth_methods # Replace with the Cloud Run service URL generated in the previous step URL = "https://cloud-run-url.app" auth_token_provider = auth_methods.aget_google_id_token(URL) # can also use sync method async def main(): async with ToolboxClient( URL, client_headers={"Authorization": auth_token_provider}, ) as toolbox: toolset = await toolbox.load_toolset() # ... asyncio.run(main()) import { ToolboxClient } from '@toolbox-sdk/core'; import {getGoogleIdToken} from '@toolbox-sdk/core/auth' // Replace with the Cloud Run service URL generated in the previous step. const URL = 'http://127.0.0.1:5000'; const authTokenProvider = () => getGoogleIdToken(URL); const client = new ToolboxClient(URL, null, {"Authorization": authTokenProvider}); import "github.com/googleapis/mcp-toolbox-sdk-go/core" func main() { // Replace with the Cloud Run service URL generated in the previous step. URL := "http://127.0.0.1:5000" auth_token_provider, err := core.GetGoogleIDToken(ctx, URL) if err != nil { log.Fatalf("Failed to fetch token %v", err) } toolboxClient, err := core.NewToolboxClient( URL, core.WithClientHeaderString("Authorization", auth_token_provider)) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } } Now, you can use this client to connect to the deployed Cloud Run instance! Troubleshooting --------------- Note For any deployment or runtime error, the best first step is to check the logs for your service in the Google Cloud Console’s Cloud Run section. They often contain the specific error message needed to diagnose the problem. * **Deployment Fails with “Container failed to start”:** This is almost always caused by a port mismatch. Ensure your container’s `--port` argument is set to `8080` to match the `$PORT` environment variable provided by Cloud Run. * **Client Receives Permission Denied Error (401 or 403):** If your client application (e.g., your local SDK) gets a `401 Unauthorized` or `403 Forbidden` error when trying to call your Cloud Run service, it means the client is not properly authenticated as an invoker. * Ensure the user or service account calling the service has the **Cloud Run Invoker** (`roles/run.invoker`) IAM role. * If running locally, make sure your Application Default Credentials are set up correctly by running `gcloud auth application-default login`. * **Service Fails to Access Secrets (in logs):** If your application starts but the logs show errors like “permission denied” when trying to access Secret Manager, it means the Toolbox service account is missing permissions. * Ensure the `toolbox-identity` service account has the **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`) IAM role. Last modified January 8, 2026: [feat: add allowed-hosts flag (#2254) (17b41f64531)](https://github.com/googleapis/genai-toolbox/commit/17b41f64531b8fe417c28ada45d1992ba430dc1b) --- # Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases Deploy ADK Agent and MCP Toolbox ================================ How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. Before you begin ---------------- This guide assumes you have already done the following: 1. Completed the [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.26.0/getting-started/local_quickstart/) and have a working ADK agent running locally. 2. Installed the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) . 3. A Google Cloud project with billing enabled. Step 1: Deploy MCP Toolbox to Cloud Run --------------------------------------- Before deploying your agent, your MCP Toolbox server needs to be accessible from the cloud. We will deploy MCP Toolbox to Cloud Run. Follow the [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.26.0/how-to/deploy_toolbox/) guide to deploy your MCP Toolbox instance. #### Important After deployment, note down the Service URL of your MCP Toolbox Cloud Run service. You will need this to configure your agent. Step 2: Prepare your Agent for Deployment ----------------------------------------- We will use the `agent-starter-pack` tool to enhance your local agent project with the necessary configuration for deployment to Vertex AI Agent Engine. 1. Open a terminal and navigate to the **parent directory** of your agent project (the directory containing the `my_agent` folder). 2. Run the following command to enhance your project: uvx agent-starter-pack enhance --adk -d agent_engine 3. Follow the interactive prompts to configure your deployment settings. This process will generate deployment configuration files (like a `Makefile` and `Dockerfile`) in your project directory. 4. Add `toolbox-core` as a dependency to the new project: uv add toolbox-core Step 3: Configure Google Cloud Authentication --------------------------------------------- Ensure your local environment is authenticated with Google Cloud to perform the deployment. 1. Login with Application Default Credentials (ADC): gcloud auth application-default login 2. Set your active project: gcloud config set project Step 4: Connect Agent to Deployed MCP Toolbox --------------------------------------------- You need to update your agent’s code to connect to the Cloud Run URL of your MCP Toolbox instead of the local address. 1. Recall that you can find the Cloud Run deployment URL of the MCP Toolbox server using the following command: gcloud run services describe toolbox --format 'value(status.url)' 2. Open your agent file (`my_agent/agent.py`). 3. Update the `ToolboxSyncClient` initialization to use your Cloud Run URL. Since Cloud Run services are secured by default, you also need to provide an authentication token. Replace your existing client initialization code with the following: from google.adk import Agent from google.adk.apps import App from toolbox_core import ToolboxSyncClient, auth_methods # TODO(developer): Replace with your Toolbox Cloud Run Service URL TOOLBOX_URL = "https://your-toolbox-service-xyz.a.run.app" # Initialize the client with the Cloud Run URL and Auth headers client = ToolboxSyncClient( TOOLBOX_URL, client_headers={"Authorization": auth_methods.get_google_id_token(TOOLBOX_URL)} ) root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=client.load_toolset(), ) app = App(root_agent=root_agent, name="my_agent") #### Important Ensure that the `name` parameter in the `App` initialization matches the name of your agent’s parent directory (e.g., `my_agent`). ... app = App(root_agent=root_agent, name="my_agent") Step 5: Deploy to Agent Engine ------------------------------ Run the deployment command: make backend This command will build your agent’s container image and deploy it to Vertex AI. Step 6: Test your Deployment ---------------------------- Once the deployment command (`make backend`) completes, it will output the URL for the Agent Engine Playground. You can click on this URL to open the Playground in your browser and start chatting with your agent to test the tools. For additional test scenarios, refer to the [Test deployed agent](https://google.github.io/adk-docs/deploy/agent-engine/#test-deployment) section in the ADK documentation. Last modified November 26, 2025: [docs: Add guide for deploying ADK Agent to Agent Engine with Cloud Run Toolbox (#2035) (9315dba9968)](https://github.com/googleapis/genai-toolbox/commit/9315dba9968946299ce679df9aa4d4c73d0762fa) --- # PostgreSQL using MCP | MCP Toolbox for Databases PostgreSQL using MCP ==================== Connect your IDE to PostgreSQL using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like Postgres. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a Postgres instance: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/postgres_mcp/#configure-your-mcp-client) Tip This guide can be used with [AlloyDB Omni](https://cloud.google.com/alloydb/omni/docs/overview) . Set up the database ------------------- 1. Create or select a PostgreSQL instance. * [Install PostgreSQL locally](https://www.postgresql.org/download/) * [Install AlloyDB Omni](https://cloud.google.com/alloydb/omni/docs/quickstart) 2. Create or reuse [a database user](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/database-users/manage-users) and have the username and password ready. Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.6.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","postgres","--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to Postgres using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # Deploy to Cloud Run | MCP Toolbox for Databases Deploy to Cloud Run =================== How to set up and configure Toolbox to run on Cloud Run. Before you begin ---------------- 1. [Install](https://cloud.google.com/sdk/docs/install) the Google Cloud CLI. 2. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. Make sure you’ve set up and initialized your database. 5. You must have the following APIs enabled: gcloud services enable run.googleapis.com \ cloudbuild.googleapis.com \ artifactregistry.googleapis.com \ iam.googleapis.com \ secretmanager.googleapis.com 6. To create an IAM account, you must have the following IAM permissions (or roles): * Create Service Account role (roles/iam.serviceAccountCreator) 7. To create a secret, you must have the following roles: * Secret Manager Admin role (roles/secretmanager.admin) 8. To deploy to Cloud Run, you must have the following set of roles: * Cloud Run Developer (roles/run.developer) * Service Account User role (roles/iam.serviceAccountUser) Note If you are using sources that require VPC-access (such as AlloyDB or Cloud SQL over private IP), make sure your Cloud Run service and the database are in the same VPC network. Create a service account ------------------------ 1. Create a backend service account if you don’t already have one: gcloud iam service-accounts create toolbox-identity 2. Grant permissions to use secret manager: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/secretmanager.secretAccessor 3. Grant additional permissions to the service account that are specific to the source, e.g.: * [AlloyDB for PostgreSQL](https://mcp-toolbox.dev/v0.26.0/resources/sources/alloydb-pg/#iam-permissions) * [Cloud SQL for PostgreSQL](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-sql-pg/#iam-permissions) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://mcp-toolbox.dev/v0.26.0/resources/sources/) section. Deploy to Cloud Run ------------------- 1. Upload `tools.yaml` as a secret: gcloud secrets create tools --data-file=tools.yaml If you already have a secret and want to update the secret version, execute the following: gcloud secrets versions add tools --data-file=tools.yaml 2. Set an environment variable to the container image that you want to use for cloud run: export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest Note **The `$PORT` Environment Variable** Google Cloud Run dictates the port your application must listen on by setting the `$PORT` environment variable inside your container. This value defaults to **8080**. Your application’s `--port` argument **must** be set to listen on this port. If there is a mismatch, the container will fail to start and the deployment will time out. 3. Deploy Toolbox to Cloud Run using the following command: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud ### Update deployed server to be secure To prevent DNS rebinding attack, use the `--allowed-hosts` flag to specify a list of hosts. In order to do that, you will have to re-deploy the cloud run service with the new flag. To implement CORs checks, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. 1. Set an environment variable to the cloud run url: export URL= export HOST= 2. Redeploy Toolbox: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud Connecting with Toolbox Client SDK ---------------------------------- You can connect to Toolbox Cloud Run instances directly through the SDK. 1. [Set up `Cloud Run Invoker` role access](https://cloud.google.com/run/docs/securing/managing-access#service-add-principals) to your Cloud Run service. 2. (Only for local runs) Set up [Application Default Credentials](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for the principal you set up the `Cloud Run Invoker` role access to. 3. Run the following to retrieve a non-deterministic URL for the cloud run service: gcloud run services describe toolbox --format 'value(status.url)' 4. Import and initialize the toolbox client with the URL retrieved above: * Python * Javascript * Go import asyncio from toolbox_core import ToolboxClient, auth_methods from toolbox_core.protocol import Protocol # Replace with the Cloud Run service URL generated in the previous step URL = "https://cloud-run-url.app" auth_token_provider = auth_methods.aget_google_id_token(URL) # can also use sync method async def main(): async with ToolboxClient( URL, client_headers={"Authorization": auth_token_provider}, protocol=Protocol.TOOLBOX, ) as toolbox: toolset = await toolbox.load_toolset() # ... asyncio.run(main()) import { ToolboxClient } from '@toolbox-sdk/core'; import {getGoogleIdToken} from '@toolbox-sdk/core/auth' // Replace with the Cloud Run service URL generated in the previous step. const URL = 'http://127.0.0.1:5000'; const authTokenProvider = () => getGoogleIdToken(URL); const client = new ToolboxClient(URL, null, {"Authorization": authTokenProvider}); import "github.com/googleapis/mcp-toolbox-sdk-go/core" func main() { // Replace with the Cloud Run service URL generated in the previous step. URL := "http://127.0.0.1:5000" auth_token_provider, err := core.GetGoogleIDToken(ctx, URL) if err != nil { log.Fatalf("Failed to fetch token %v", err) } toolboxClient, err := core.NewToolboxClient( URL, core.WithClientHeaderString("Authorization", auth_token_provider)) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } } Now, you can use this client to connect to the deployed Cloud Run instance! Troubleshooting --------------- Note For any deployment or runtime error, the best first step is to check the logs for your service in the Google Cloud Console’s Cloud Run section. They often contain the specific error message needed to diagnose the problem. * **Deployment Fails with “Container failed to start”:** This is almost always caused by a port mismatch. Ensure your container’s `--port` argument is set to `8080` to match the `$PORT` environment variable provided by Cloud Run. * **Client Receives Permission Denied Error (401 or 403):** If your client application (e.g., your local SDK) gets a `401 Unauthorized` or `403 Forbidden` error when trying to call your Cloud Run service, it means the client is not properly authenticated as an invoker. * Ensure the user or service account calling the service has the **Cloud Run Invoker** (`roles/run.invoker`) IAM role. * If running locally, make sure your Application Default Credentials are set up correctly by running `gcloud auth application-default login`. * **Service Fails to Access Secrets (in logs):** If your application starts but the logs show errors like “permission denied” when trying to access Secret Manager, it means the Toolbox service account is missing permissions. * Ensure the `toolbox-identity` service account has the **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`) IAM role. * **Cloud Run Connections via IAP:** Currently we do not support Cloud Run connections via [IAP](https://docs.cloud.google.com/iap/docs/concepts-overview) . Please disable IAP if you are using it. Last modified January 16, 2026: [docs: update cloud run connection docs (#2320) (dfddeb528d9)](https://github.com/googleapis/genai-toolbox/commit/dfddeb528d9b0dd6709ddf671464ab25cc2dd8ea) --- # Deploy to Kubernetes | MCP Toolbox for Databases Deploy to Kubernetes ==================== How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). Before you begin ---------------- 1. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 2. [Install the `gcloud` CLI](https://cloud.google.com/sdk/docs/install) . 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. You must have the following APIs enabled: gcloud services enable artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ container.googleapis.com \ iam.googleapis.com 5. `kubectl` is used to manage Kubernetes, the cluster orchestration system used by GKE. Verify if you have `kubectl` installed: kubectl version --client 6. If needed, install `kubectl` component using the Google Cloud CLI: gcloud components install kubectl Create a service account ------------------------ 1. Specify a name for your service account with an environment variable: export SA_NAME=toolbox 2. Create a backend service account: gcloud iam service-accounts create $SA_NAME 3. Grant any IAM roles necessary to the IAM service account. Each source has a list of necessary IAM permissions listed on its page. The example below is for cloud sql postgres source: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudsql.client * [AlloyDB IAM Identity](https://mcp-toolbox.dev/v0.25.0/resources/sources/alloydb-pg/#iam-permissions) * [CloudSQL IAM Identity](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-sql-pg/#iam-permissions) * [Spanner IAM Identity](https://mcp-toolbox.dev/v0.25.0/resources/sources/spanner/#iam-permissions) Deploy to Kubernetes -------------------- 1. Set environment variables: export CLUSTER_NAME=toolbox-cluster export DEPLOYMENT_NAME=toolbox export SERVICE_NAME=toolbox-service export REGION=us-central1 export NAMESPACE=toolbox-namespace export SECRET_NAME=toolbox-config export KSA_NAME=toolbox-service-account 2. Create a [GKE cluster](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-architecture) . gcloud container clusters create-auto $CLUSTER_NAME \ --location=us-central1 3. Get authentication credentials to interact with the cluster. This also configures `kubectl` to use the cluster. gcloud container clusters get-credentials $CLUSTER_NAME \ --region=$REGION \ --project=$PROJECT_ID 4. View the current context for `kubectl`. kubectl config current-context 5. Create namespace for the deployment. kubectl create namespace $NAMESPACE 6. Create a Kubernetes Service Account (KSA). kubectl create serviceaccount $KSA_NAME --namespace $NAMESPACE 7. Enable the IAM binding between Google Service Account (GSA) and Kubernetes Service Account (KSA). gcloud iam service-accounts add-iam-policy-binding \ --role="roles/iam.workloadIdentityUser" \ --member="serviceAccount:$PROJECT_ID.svc.id.goog[$NAMESPACE/$KSA_NAME]" \ $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com 8. Add annotation to KSA to complete binding: kubectl annotate serviceaccount \ $KSA_NAME \ iam.gke.io/gcp-service-account=$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --namespace $NAMESPACE 9. Prepare the Kubernetes secret for your `tools.yaml` file. kubectl create secret generic $SECRET_NAME \ --from-file=./tools.yaml \ --namespace=$NAMESPACE 10. Create a Kubernetes manifest file (`k8s_deployment.yaml`) to build deployment. apiVersion: apps/v1 kind: Deployment metadata: name: toolbox namespace: toolbox-namespace spec: selector: matchLabels: app: toolbox template: metadata: labels: app: toolbox spec: serviceAccountName: toolbox-service-account containers: - name: toolbox # Recommend to use the latest version of toolbox image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest args: ["--address", "0.0.0.0"] ports: - containerPort: 5000 volumeMounts: - name: toolbox-config mountPath: "/app/tools.yaml" subPath: tools.yaml readOnly: true volumes: - name: toolbox-config secret: secretName: toolbox-config items: - key: tools.yaml path: tools.yaml Tip To prevent DNS rebinding attack, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. E.g. `args: ["--address", "0.0.0.0", "--allowed-hosts", "foo.bar:5000"]` To implement CORs, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. E.g. `args: ["--address", "0.0.0.0", "--allowed-origins", "https://foo.bar"]` 11. Create the deployment. kubectl apply -f k8s_deployment.yaml --namespace $NAMESPACE 12. Check the status of deployment. kubectl get deployments --namespace $NAMESPACE 13. Create a Kubernetes manifest file (`k8s_service.yaml`) to build service. apiVersion: v1 kind: Service metadata: name: toolbox-service namespace: toolbox-namespace annotations: cloud.google.com/l4-rbs: "enabled" spec: selector: app: toolbox ports: - port: 5000 targetPort: 5000 type: LoadBalancer 14. Create the service. kubectl apply -f k8s_service.yaml --namespace $NAMESPACE 15. You can find your IP address created for your service by getting the service information through the following. kubectl describe services $SERVICE_NAME --namespace $NAMESPACE 16. To look at logs, run the following. kubectl logs -f deploy/$DEPLOYMENT_NAME --namespace $NAMESPACE 17. You might have to wait a couple of minutes. It is ready when you can see `EXTERNAL-IP` with the following command: kubectl get svc -n $NAMESPACE 18. Access toolbox locally. curl :5000 Clean up resources ------------------ 1. Delete secret. kubectl delete secret $SECRET_NAME --namespace $NAMESPACE 2. Delete deployment. kubectl delete deployment $DEPLOYMENT_NAME --namespace $NAMESPACE 3. Delete the application’s service. kubectl delete service $SERVICE_NAME --namespace $NAMESPACE 4. Delete the Kubernetes cluster. gcloud container clusters delete $CLUSTER_NAME \ --location=$REGION Last modified January 8, 2026: [feat: add allowed-hosts flag (#2254) (17b41f64531)](https://github.com/googleapis/genai-toolbox/commit/17b41f64531b8fe417c28ada45d1992ba430dc1b) --- # Deploy using Docker Compose | MCP Toolbox for Databases Deploy using Docker Compose =========================== How to deploy Toolbox using Docker Compose. Before you begin ---------------- 1. [Install Docker Compose.](https://docs.docker.com/compose/install/) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://github.com/googleapis/genai-toolbox/blob/main/README.md#configuration) section. Deploy using Docker Compose --------------------------- 1. Create a `docker-compose.yml` file, customizing as needed: services: toolbox: # TODO: It is recommended to pin to a specific image version instead of latest. image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest hostname: toolbox platform: linux/amd64 ports: - "5000:5000" volumes: - ./config:/config command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0"] depends_on: db: condition: service_healthy networks: - tool-network db: # TODO: It is recommended to pin to a specific image version instead of latest. image: postgres hostname: db environment: POSTGRES_USER: toolbox_user POSTGRES_PASSWORD: my-password POSTGRES_DB: toolbox_db ports: - "5432:5432" volumes: - ./db:/var/lib/postgresql/data # This file can be used to bootstrap your schema if needed. # See "initialization scripts" on https://hub.docker.com/_/postgres/ for more info - ./config/init.sql:/docker-entrypoint-initdb.d/init.sql healthcheck: test: ["CMD-SHELL", "pg_isready -U toolbox_user -d toolbox_db"] interval: 10s timeout: 5s retries: 5 networks: - tool-network networks: tool-network: TipTo prevent DNS rebinding attack, use the --allowed-origins flag to specify a list of origins permitted to access the server. E.g. command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0", "--allowed-origins", "https://foo.bar"] 1. Run the following command to bring up the Toolbox and Postgres instance docker-compose up -d Tip You can use this setup to quickly set up Toolbox + Postgres to follow along in our [Quickstart](https://mcp-toolbox.dev/v0.24.0/getting-started/local_quickstart/) Connecting with Toolbox Client SDK ---------------------------------- Next, we will use Toolbox with the Client SDKs: 1. The url for the Toolbox server running using docker-compose will be: http://localhost:5000 2. Import and initialize the client with the URL: * LangChain * Llamaindex from toolbox_langchain import ToolboxClient # Replace with the cloud run service URL generated above async with ToolboxClient("http://$YOUR_URL") as toolbox: from toolbox_llamaindex import ToolboxClient # Replace with the cloud run service URL generated above async with ToolboxClient("http://$YOUR_URL") as toolbox: Last modified November 27, 2025: [feat: add allowed-origins flag (#1984) (862868f2847)](https://github.com/googleapis/genai-toolbox/commit/862868f28476ea981575ce412faa7d6a03138f31) --- # Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server Admin using MCP ======================================== Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for SQL Server instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.27.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for SQL Server using MCP. The `cloud-sql-mssql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for SQL Server instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for SQL Server instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases Deploy ADK Agent and MCP Toolbox ================================ How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. Before you begin ---------------- This guide assumes you have already done the following: 1. Completed the [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.25.0/getting-started/local_quickstart/) and have a working ADK agent running locally. 2. Installed the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) . 3. A Google Cloud project with billing enabled. Step 1: Deploy MCP Toolbox to Cloud Run --------------------------------------- Before deploying your agent, your MCP Toolbox server needs to be accessible from the cloud. We will deploy MCP Toolbox to Cloud Run. Follow the [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.25.0/how-to/deploy_toolbox/) guide to deploy your MCP Toolbox instance. #### Important After deployment, note down the Service URL of your MCP Toolbox Cloud Run service. You will need this to configure your agent. Step 2: Prepare your Agent for Deployment ----------------------------------------- We will use the `agent-starter-pack` tool to enhance your local agent project with the necessary configuration for deployment to Vertex AI Agent Engine. 1. Open a terminal and navigate to the **parent directory** of your agent project (the directory containing the `my_agent` folder). 2. Run the following command to enhance your project: uvx agent-starter-pack enhance --adk -d agent_engine 3. Follow the interactive prompts to configure your deployment settings. This process will generate deployment configuration files (like a `Makefile` and `Dockerfile`) in your project directory. 4. Add `toolbox-core` as a dependency to the new project: uv add toolbox-core Step 3: Configure Google Cloud Authentication --------------------------------------------- Ensure your local environment is authenticated with Google Cloud to perform the deployment. 1. Login with Application Default Credentials (ADC): gcloud auth application-default login 2. Set your active project: gcloud config set project Step 4: Connect Agent to Deployed MCP Toolbox --------------------------------------------- You need to update your agent’s code to connect to the Cloud Run URL of your MCP Toolbox instead of the local address. 1. Recall that you can find the Cloud Run deployment URL of the MCP Toolbox server using the following command: gcloud run services describe toolbox --format 'value(status.url)' 2. Open your agent file (`my_agent/agent.py`). 3. Update the `ToolboxSyncClient` initialization to use your Cloud Run URL. Since Cloud Run services are secured by default, you also need to provide an authentication token. Replace your existing client initialization code with the following: from google.adk import Agent from google.adk.apps import App from toolbox_core import ToolboxSyncClient, auth_methods # TODO(developer): Replace with your Toolbox Cloud Run Service URL TOOLBOX_URL = "https://your-toolbox-service-xyz.a.run.app" # Initialize the client with the Cloud Run URL and Auth headers client = ToolboxSyncClient( TOOLBOX_URL, client_headers={"Authorization": auth_methods.get_google_id_token(TOOLBOX_URL)} ) root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=client.load_toolset(), ) app = App(root_agent=root_agent, name="my_agent") #### Important Ensure that the `name` parameter in the `App` initialization matches the name of your agent’s parent directory (e.g., `my_agent`). ... app = App(root_agent=root_agent, name="my_agent") Step 5: Deploy to Agent Engine ------------------------------ Run the deployment command: make backend This command will build your agent’s container image and deploy it to Vertex AI. Step 6: Test your Deployment ---------------------------- Once the deployment command (`make backend`) completes, it will output the URL for the Agent Engine Playground. You can click on this URL to open the Playground in your browser and start chatting with your agent to test the tools. For additional test scenarios, refer to the [Test deployed agent](https://google.github.io/adk-docs/deploy/agent-engine/#test-deployment) section in the ADK documentation. Last modified November 26, 2025: [docs: Add guide for deploying ADK Agent to Agent Engine with Cloud Run Toolbox (#2035) (9315dba9968)](https://github.com/googleapis/genai-toolbox/commit/9315dba9968946299ce679df9aa4d4c73d0762fa) --- # Toolbox UI | MCP Toolbox for Databases Toolbox UI ========== How to effectively use Toolbox UI. Toolbox UI is a built-in web interface that allows users to visually inspect and test out configured resources such as tools and toolsets. Launching Toolbox UI -------------------- To launch Toolbox’s interactive UI, use the `--ui` flag. ./toolbox --ui Toolbox UI will be served from the same host and port as the Toolbox Server, with the `/ui` suffix. Once Toolbox is launched, the following INFO log with Toolbox UI’s url will be shown: INFO "Toolbox UI is up and running at: http://localhost:5000/ui" Navigating the Tools Page ------------------------- The tools page shows all tools loaded from your configuration file. This corresponds to the default toolset (represented by an empty string). Each tool’s name on this page will exactly match its name in the configuration file. To view details for a specific tool, click on the tool name. The main content area will be populated with the tool name, description, and available parameters. ![Tools Page](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/tools.png) ### Invoking a Tool 1. Click on a Tool 2. Enter appropriate parameters in each parameter field 3. Click “Run Tool” 4. Done! Your results will appear in the response field 5. (Optional) Uncheck “Prettify JSON” to format the response as plain text ![Run Tool Demo GIF](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/run-tool.gif) ### Optional Parameters Toolbox allows users to add [optional parameters](https://mcp-toolbox.dev/v0.27.0/resources/tools/#basic-parameters) with or without a default value. To exclude a parameter, uncheck the box to the right of an associated parameter, and that parameter will not be included in the request body. If the parameter is not sent, Toolbox will either use it as `nil` value or the `default` value, if configured. If the parameter is required, Toolbox will throw an error. When the box is checked, parameter will be sent exactly as entered in the response field (e.g. empty string). ![Optional Parameter checked example](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/optional-param-checked.png) ![Optional Parameter unchecked example](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/optional-param-unchecked.png) ### Editing Headers To edit headers, press the “Edit Headers” button to display the header modal. Within this modal, users can make direct edits by typing into the header’s text area. Toolbox UI validates that the headers are in correct JSON format. Other header-related errors (e.g., incorrect header names or values required by the tool) will be reported in the Response section after running the tool. ![Edit Headers](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/edit-headers.png) #### Google OAuth Currently, Toolbox supports Google OAuth 2.0 as an AuthService, which allows tools to utilize authorized parameters. When a tool uses an authorized parameter, the parameter will be displayed but not editable, as it will be populated from the authentication token. To provide the token, add your Google OAuth ID Token to the request header using the “Edit Headers” button and modal described above. The key should be the name of your AuthService as defined in your tool configuration file, suffixed with `_token`. The value should be your ID token as a string. 1. Select a tool that requires [authenticated parameters](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/) 2. The auth parameter’s text field is greyed out. This is because it cannot be entered manually and will be parsed from the resolved auth token 3. To update request headers with the token, select “Edit Headers” 4. (Optional) If you wish to manually edit the header, checkout the dropdown “How to extract Google OAuth ID Token manually” for guidance on retrieving ID token 5. To edit the header automatically, click the “Auto Setup” button that is associated with your Auth Profile 6. Enter the Client ID defined in your tools configuration file 7. Click “Continue” 8. Click “Sign in With Google” and login with your associated google account. This should automatically populate the header text area with your token 9. Click “Save” 10. Click “Run Tool” { "Content-Type": "application/json", "my-google-auth_token": "YOUR_ID_TOKEN_HERE" } ![Using Authenticated Parameter GIF](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/edit-headers.gif) Navigating the Toolsets Page ---------------------------- Through the toolsets page, users can search for a specific toolset to retrieve tools from. Simply enter the toolset name in the search bar, and press “Enter” to retrieve the associated tools. If the toolset name is not defined within the tools configuration file, an error message will be displayed. ![Toolsets Page](https://mcp-toolbox.dev/v0.27.0/how-to/toolbox-ui/toolsets.png) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Connect via MCP Client | MCP Toolbox for Databases Connect via MCP Client ====================== How to connect to Toolbox from a MCP Client. Toolbox SDKs vs Model Context Protocol (MCP) -------------------------------------------- Toolbox now supports connections via both the native Toolbox SDKs and via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) . However, Toolbox has several features which are not supported in the MCP specification (such as Authenticated Parameters and Authorized invocation). We recommend using the native SDKs over MCP clients to leverage these features. The native SDKs can be combined with MCP clients in many cases. ### Protocol Versions Toolbox currently supports the following versions of MCP specification: * [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) * [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) * [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26) * [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05) ### Toolbox AuthZ/AuthN Not Supported by MCP The auth implementation in Toolbox is not supported in MCP’s auth specification. This includes: * [Authenticated Parameters](https://mcp-toolbox.dev/v0.27.0/resources/tools/#authenticated-parameters) * [Authorized Invocations](https://mcp-toolbox.dev/v0.27.0/resources/tools/#authorized-invocations) Connecting to Toolbox with an MCP client ---------------------------------------- ### Before you begin Note MCP is only compatible with Toolbox version 0.3.0 and above. 1. [Install](https://mcp-toolbox.dev/v0.27.0/getting-started/introduction/#installing-the-server) Toolbox version 0.3.0+. 2. Make sure you’ve set up and initialized your database. 3. [Set up](https://mcp-toolbox.dev/v0.27.0/getting-started/configure/) your `tools.yaml` file. ### Connecting via Standard Input/Output (stdio) Toolbox supports the [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) transport protocol. Users that wish to use stdio will have to include the `--stdio` flag when running Toolbox. ./toolbox --stdio When running with stdio, Toolbox will listen via stdio instead of acting as a remote HTTP server. Logs will be set to the `warn` level by default. `debug` and `info` logs are not supported with stdio. Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. ### Connecting via HTTP Toolbox supports the HTTP transport protocol with and without SSE. * HTTP with SSE (deprecated) * Streamable HTTP Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "sse", "url": "http://127.0.0.1:5000/mcp/sse", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}/sse"`. HTTP with SSE is only supported in version `2024-11-05` and is currently deprecated. Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "http", "url": "http://127.0.0.1:5000/mcp", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}"`. ### Using the MCP Inspector with Toolbox Use MCP [Inspector](https://github.com/modelcontextprotocol/inspector) for testing and debugging Toolbox server. * STDIO * HTTP with SSE (deprecated) * Streamable HTTP 1. Run Inspector with Toolbox as a subprocess: npx @modelcontextprotocol/inspector ./toolbox --stdio 2. For `Transport Type` dropdown menu, select `STDIO`. 3. In `Command`, make sure that it is set to :`./toolbox` (or the correct path to where the Toolbox binary is installed). 4. In `Arguments`, make sure that it’s filled with `--stdio`. 5. Click the `Connect` button. It might take awhile to spin up Toolbox. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.27.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `SSE`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp/sse` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}/sse` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.27.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `Streamable HTTP`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! ### Tested Clients | Client | SSE Works | MCP Config Docs | | --- | --- | --- | | Claude Desktop | ✅ | [https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop](https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop) | | MCP Inspector | ✅ | [https://github.com/modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) | | Cursor | ✅ | [https://docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol) | | Windsurf | ✅ | [https://docs.windsurf.com/windsurf/mcp](https://docs.windsurf.com/windsurf/mcp) | | VS Code (Insiders) | ✅ | [https://code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Last modified January 15, 2026: [feat: add new v20251125 version (#2303) (4d23a3bbf27)](https://github.com/googleapis/genai-toolbox/commit/4d23a3bbf2797b1f7fe328aeb5789e778121da23) --- # Connect via Gemini CLI Extensions | MCP Toolbox for Databases Connect via Gemini CLI Extensions ================================= Connect to Toolbox via Gemini CLI Extensions. Gemini CLI Extensions --------------------- [Gemini CLI](https://google-gemini.github.io/gemini-cli/) is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an agentic interface for interacting with database and analytics services and popular open-source databases. ### How extensions work Gemini CLI is highly extensible, allowing for the addition of new tools and capabilities through extensions. You can load the extensions from a GitHub URL, a local directory, or a configurable registry. They provide new tools, slash commands, and prompts to assist with your workflow. Use the Gemini CLI Extensions to load prebuilt or custom tools to interact with your databases. Below are a list of Gemini CLI Extensions powered by MCP Toolbox: * [alloydb](https://github.com/gemini-cli-extensions/alloydb) * [alloydb-observability](https://github.com/gemini-cli-extensions/alloydb-observability) * [bigquery-conversational-analytics](https://github.com/gemini-cli-extensions/bigquery-conversational-analytics) * [bigquery-data-analytics](https://github.com/gemini-cli-extensions/bigquery-data-analytics) * [cloud-sql-mysql](https://github.com/gemini-cli-extensions/cloud-sql-mysql) * [cloud-sql-mysql-observability](https://github.com/gemini-cli-extensions/cloud-sql-mysql-observability) * [cloud-sql-postgresql](https://github.com/gemini-cli-extensions/cloud-sql-postgresql) * [cloud-sql-postgresql-observability](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability) * [cloud-sql-sqlserver](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver) * [cloud-sql-sqlserver-observability](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability) * [dataplex](https://github.com/gemini-cli-extensions/dataplex) * [firestore-native](https://github.com/gemini-cli-extensions/firestore-native) * [looker](https://github.com/gemini-cli-extensions/looker) * [mcp-toolbox](https://github.com/gemini-cli-extensions/mcp-toolbox) * [mysql](https://github.com/gemini-cli-extensions/mysql) * [postgres](https://github.com/gemini-cli-extensions/postgres) * [spanner](https://github.com/gemini-cli-extensions/spanner) * [sql-server](https://github.com/gemini-cli-extensions/sql-server) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # SQL Server using MCP | MCP Toolbox for Databases SQL Server using MCP ==================== Connect your IDE to SQL Server using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQL Server. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQL Server instance: * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQL Server instance.](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mssql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to SQL Server using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 13, 2026: [chore(main): release 0.29.0 (#2608) (39832a0faa6)](https://github.com/googleapis/genai-toolbox/commit/39832a0faa6e967734f4cf2283ec270aa17fc363) --- # Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for PostgreSQL Admin using MCP ======================================== Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for PostgreSQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for PostgreSQL using MCP. The `cloud-sql-postgres-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for PostgreSQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for PostgreSQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Export Telemetry | MCP Toolbox for Databases Export Telemetry ================ How to set up and configure Toolbox to use the Otel Collector. About ----- The [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) offers a vendor-agnostic implementation of how to receive, process and export telemetry data. It removes the need to run, operate, and maintain multiple agents/collectors. Configure the Collector ----------------------- To configure the collector, you will have to provide a configuration file. The configuration file consists of four classes of pipeline component that access telemetry data. * `Receivers` * `Processors` * `Exporters` * `Connectors` Example of setting up the classes of pipeline components (in this example, we don’t use connectors): receivers: otlp: protocols: http: endpoint: "127.0.0.1:4553" exporters: googlecloud: project: processors: batch: send_batch_size: 200 After each pipeline component is configured, you will enable it within the `service` section of the configuration file. service: pipelines: traces: receivers: ["otlp"] processors: ["batch"] exporters: ["googlecloud"] Running the Collector --------------------- There are a couple of steps to run and use a Collector. 1. [Install the Collector](https://opentelemetry.io/docs/collector/installation/) binary. Pull a binary or Docker image for the OpenTelemetry contrib collector. 2. Set up credentials for telemetry backend. 3. Set up the Collector config. Below are some examples for setting up the Collector config: * [Google Cloud Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter) * [Google Managed Service for Prometheus Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter#example-configuration) 4. Run the Collector with the configuration file. ./otelcol-contrib --config=collector-config.yaml 5. Run toolbox with the `--telemetry-otlp` flag. Configure it to send them to `127.0.0.1:4553` (for HTTP) or the Collector’s URL. ./toolbox --telemetry-otlp=127.0.0.1:4553 Tip To pass an insecure endpoint, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. 6. Once telemetry datas are collected, you can view them in your telemetry backend. If you are using GCP exporters, telemetry will be visible in GCP dashboard at [Metrics Explorer](https://console.cloud.google.com/monitoring/metrics-explorer) and [Trace Explorer](https://console.cloud.google.com/traces) . Note If you are exporting to Google Cloud monitoring, we recommend that you use the Google Cloud Exporter for traces and the Google Managed Service for Prometheus Exporter for metrics. Last modified December 18, 2025: [docs: telemetry docs to provide endpoint without scheme or path (#2179) (6e873494314)](https://github.com/googleapis/genai-toolbox/commit/6e8734943147dc919800db98af7987f2302c937d) --- # Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases Deploy ADK Agent and MCP Toolbox ================================ How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. Before you begin ---------------- This guide assumes you have already done the following: 1. Completed the [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.27.0/getting-started/local_quickstart/) and have a working ADK agent running locally. 2. Installed the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) . 3. A Google Cloud project with billing enabled. Step 1: Deploy MCP Toolbox to Cloud Run --------------------------------------- Before deploying your agent, your MCP Toolbox server needs to be accessible from the cloud. We will deploy MCP Toolbox to Cloud Run. Follow the [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.27.0/how-to/deploy_toolbox/) guide to deploy your MCP Toolbox instance. #### Important After deployment, note down the Service URL of your MCP Toolbox Cloud Run service. You will need this to configure your agent. Step 2: Prepare your Agent for Deployment ----------------------------------------- We will use the `agent-starter-pack` tool to enhance your local agent project with the necessary configuration for deployment to Vertex AI Agent Engine. 1. Open a terminal and navigate to the **parent directory** of your agent project (the directory containing the `my_agent` folder). 2. Run the following command to enhance your project: uvx agent-starter-pack enhance --adk -d agent_engine 3. Follow the interactive prompts to configure your deployment settings. This process will generate deployment configuration files (like a `Makefile` and `Dockerfile`) in your project directory. 4. Add `google-adk[toolbox]` as a dependency to the new project: uv add google-adk[toolbox] Step 3: Configure Google Cloud Authentication --------------------------------------------- Ensure your local environment is authenticated with Google Cloud to perform the deployment. 1. Login with Application Default Credentials (ADC): gcloud auth application-default login 2. Set your active project: gcloud config set project Step 4: Connect Agent to Deployed MCP Toolbox --------------------------------------------- You need to update your agent’s code to connect to the Cloud Run URL of your MCP Toolbox instead of the local address. 1. Recall that you can find the Cloud Run deployment URL of the MCP Toolbox server using the following command: gcloud run services describe toolbox --format 'value(status.url)' 2. Open your agent file (`my_agent/agent.py`). 3. Update the `ToolboxToolset` initialization to point to your Cloud Run service URL. Replace the existing initialization code with the following: #### Note Since Cloud Run services are secured by default, you also need to provide a workload identity. from google.adk import Agent from google.adk.apps import App from google.adk.tools.toolbox_toolset import ToolboxToolset from toolbox_adk import CredentialStrategy # TODO(developer): Replace with your Toolbox Cloud Run Service URL TOOLBOX_URL = "https://your-toolbox-service-xyz.a.run.app" # Initialize the toolset with Workload Identity (generates ID token for the URL) toolset = ToolboxToolset( server_url=TOOLBOX_URL, credentials=CredentialStrategy.workload_identity(target_audience=TOOLBOX_URL) ) root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=[toolset], ) app = App(root_agent=root_agent, name="my_agent") #### Important Ensure that the `name` parameter in the `App` initialization matches the name of your agent’s parent directory (e.g., `my_agent`). ... app = App(root_agent=root_agent, name="my_agent") Step 5: Deploy to Agent Engine ------------------------------ Run the deployment command: make deploy This command will build your agent’s container image and deploy it to Vertex AI. Step 6: Test your Deployment ---------------------------- Once the deployment command (`make deploy`) completes, it will output the URL for the Agent Engine Playground. You can click on this URL to open the Playground in your browser and start chatting with your agent to test the tools. For additional test scenarios, refer to the [Test deployed agent](https://google.github.io/adk-docs/deploy/agent-engine/#test-deployment) section in the ADK documentation. Last modified February 11, 2026: [docs(adk): align quickstart script with other orchestrations (#2423) (1f8019c50a0)](https://github.com/googleapis/genai-toolbox/commit/1f8019c50a06d65553abd93da833b6dba09c612b) --- # Deploy to Cloud Run | MCP Toolbox for Databases Deploy to Cloud Run =================== How to set up and configure Toolbox to run on Cloud Run. Before you begin ---------------- 1. [Install](https://cloud.google.com/sdk/docs/install) the Google Cloud CLI. 2. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. Make sure you’ve set up and initialized your database. 5. You must have the following APIs enabled: gcloud services enable run.googleapis.com \ cloudbuild.googleapis.com \ artifactregistry.googleapis.com \ iam.googleapis.com \ secretmanager.googleapis.com 6. To create an IAM account, you must have the following IAM permissions (or roles): * Create Service Account role (roles/iam.serviceAccountCreator) 7. To create a secret, you must have the following roles: * Secret Manager Admin role (roles/secretmanager.admin) 8. To deploy to Cloud Run, you must have the following set of roles: * Cloud Run Developer (roles/run.developer) * Service Account User role (roles/iam.serviceAccountUser) Note If you are using sources that require VPC-access (such as AlloyDB or Cloud SQL over private IP), make sure your Cloud Run service and the database are in the same VPC network. Create a service account ------------------------ 1. Create a backend service account if you don’t already have one: gcloud iam service-accounts create toolbox-identity 2. Grant permissions to use secret manager: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/secretmanager.secretAccessor 3. Grant additional permissions to the service account that are specific to the source, e.g.: * [AlloyDB for PostgreSQL](https://mcp-toolbox.dev/v0.27.0/resources/sources/alloydb-pg/#iam-permissions) * [Cloud SQL for PostgreSQL](https://mcp-toolbox.dev/v0.27.0/resources/sources/cloud-sql-pg/#iam-permissions) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://mcp-toolbox.dev/v0.27.0/resources/sources/) section. Deploy to Cloud Run ------------------- 1. Upload `tools.yaml` as a secret: gcloud secrets create tools --data-file=tools.yaml If you already have a secret and want to update the secret version, execute the following: gcloud secrets versions add tools --data-file=tools.yaml 2. Set an environment variable to the container image that you want to use for cloud run: export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest Note **The `$PORT` Environment Variable** Google Cloud Run dictates the port your application must listen on by setting the `$PORT` environment variable inside your container. This value defaults to **8080**. Your application’s `--port` argument **must** be set to listen on this port. If there is a mismatch, the container will fail to start and the deployment will time out. 3. Deploy Toolbox to Cloud Run using the following command: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud ### Update deployed server to be secure To prevent DNS rebinding attack, use the `--allowed-hosts` flag to specify a list of hosts. In order to do that, you will have to re-deploy the cloud run service with the new flag. To implement CORs checks, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. 1. Set an environment variable to the cloud run url: export URL= export HOST= 2. Redeploy Toolbox: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud Connecting with Toolbox Client SDK ---------------------------------- You can connect to Toolbox Cloud Run instances directly through the SDK. 1. [Set up `Cloud Run Invoker` role access](https://cloud.google.com/run/docs/securing/managing-access#service-add-principals) to your Cloud Run service. 2. (Only for local runs) Set up [Application Default Credentials](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for the principal you set up the `Cloud Run Invoker` role access to. 3. Run the following to retrieve a non-deterministic URL for the cloud run service: gcloud run services describe toolbox --format 'value(status.url)' 4. Import and initialize the toolbox client with the URL retrieved above: * Python * Javascript * Go import asyncio from toolbox_core import ToolboxClient, auth_methods from toolbox_core.protocol import Protocol # Replace with the Cloud Run service URL generated in the previous step URL = "https://cloud-run-url.app" auth_token_provider = auth_methods.aget_google_id_token(URL) # can also use sync method async def main(): async with ToolboxClient( URL, client_headers={"Authorization": auth_token_provider}, protocol=Protocol.TOOLBOX, ) as toolbox: toolset = await toolbox.load_toolset() # ... asyncio.run(main()) import { ToolboxClient } from '@toolbox-sdk/core'; import {getGoogleIdToken} from '@toolbox-sdk/core/auth' // Replace with the Cloud Run service URL generated in the previous step. const URL = 'http://127.0.0.1:5000'; const authTokenProvider = () => getGoogleIdToken(URL); const client = new ToolboxClient(URL, null, {"Authorization": authTokenProvider}); import "github.com/googleapis/mcp-toolbox-sdk-go/core" func main() { // Replace with the Cloud Run service URL generated in the previous step. URL := "http://127.0.0.1:5000" auth_token_provider, err := core.GetGoogleIDToken(ctx, URL) if err != nil { log.Fatalf("Failed to fetch token %v", err) } toolboxClient, err := core.NewToolboxClient( URL, core.WithClientHeaderString("Authorization", auth_token_provider)) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } } Now, you can use this client to connect to the deployed Cloud Run instance! Troubleshooting --------------- Note For any deployment or runtime error, the best first step is to check the logs for your service in the Google Cloud Console’s Cloud Run section. They often contain the specific error message needed to diagnose the problem. * **Deployment Fails with “Container failed to start”:** This is almost always caused by a port mismatch. Ensure your container’s `--port` argument is set to `8080` to match the `$PORT` environment variable provided by Cloud Run. * **Client Receives Permission Denied Error (401 or 403):** If your client application (e.g., your local SDK) gets a `401 Unauthorized` or `403 Forbidden` error when trying to call your Cloud Run service, it means the client is not properly authenticated as an invoker. * Ensure the user or service account calling the service has the **Cloud Run Invoker** (`roles/run.invoker`) IAM role. * If running locally, make sure your Application Default Credentials are set up correctly by running `gcloud auth application-default login`. * **Service Fails to Access Secrets (in logs):** If your application starts but the logs show errors like “permission denied” when trying to access Secret Manager, it means the Toolbox service account is missing permissions. * Ensure the `toolbox-identity` service account has the **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`) IAM role. * **Cloud Run Connections via IAP:** Currently we do not support Cloud Run connections via [IAP](https://docs.cloud.google.com/iap/docs/concepts-overview) . Please disable IAP if you are using it. Last modified January 16, 2026: [docs: update cloud run connection docs (#2320) (dfddeb528d9)](https://github.com/googleapis/genai-toolbox/commit/dfddeb528d9b0dd6709ddf671464ab25cc2dd8ea) --- # Deploy using Docker Compose | MCP Toolbox for Databases Deploy using Docker Compose =========================== How to deploy Toolbox using Docker Compose. Before you begin ---------------- 1. [Install Docker Compose.](https://docs.docker.com/compose/install/) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://github.com/googleapis/genai-toolbox/blob/main/README.md#configuration) section. Deploy using Docker Compose --------------------------- 1. Create a `docker-compose.yml` file, customizing as needed: services: toolbox: # TODO: It is recommended to pin to a specific image version instead of latest. image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest hostname: toolbox platform: linux/amd64 ports: - "5000:5000" volumes: - ./config:/config command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0"] depends_on: db: condition: service_healthy networks: - tool-network db: # TODO: It is recommended to pin to a specific image version instead of latest. image: postgres hostname: db environment: POSTGRES_USER: toolbox_user POSTGRES_PASSWORD: my-password POSTGRES_DB: toolbox_db ports: - "5432:5432" volumes: - ./db:/var/lib/postgresql/data # This file can be used to bootstrap your schema if needed. # See "initialization scripts" on https://hub.docker.com/_/postgres/ for more info - ./config/init.sql:/docker-entrypoint-initdb.d/init.sql healthcheck: test: ["CMD-SHELL", "pg_isready -U toolbox_user -d toolbox_db"] interval: 10s timeout: 5s retries: 5 networks: - tool-network networks: tool-network: TipTo prevent DNS rebinding attack, use the --allowed-hosts flag to specify a list of hosts for validation. E.g. command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0", "--allowed-hosts", "localhost:5000"] To implement CORs, use the --allowed-origins flag to specify a list of origins permitted to access the server. E.g. command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0", "--allowed-origins", "https://foo.bar"] 1. Run the following command to bring up the Toolbox and Postgres instance docker-compose up -d Tip You can use this setup to quickly set up Toolbox + Postgres to follow along in our [Quickstart](https://mcp-toolbox.dev/v0.25.0/getting-started/local_quickstart/) Connecting with Toolbox Client SDK ---------------------------------- Next, we will use Toolbox with the Client SDKs: 1. The url for the Toolbox server running using docker-compose will be: http://localhost:5000 2. Import and initialize the client with the URL: * LangChain * Llamaindex from toolbox_langchain import ToolboxClient # Replace with the cloud run service URL generated above async with ToolboxClient("http://$YOUR_URL") as toolbox: from toolbox_llamaindex import ToolboxClient # Replace with the cloud run service URL generated above async with ToolboxClient("http://$YOUR_URL") as toolbox: Last modified January 8, 2026: [feat: add allowed-hosts flag (#2254) (17b41f64531)](https://github.com/googleapis/genai-toolbox/commit/17b41f64531b8fe417c28ada45d1992ba430dc1b) --- # Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for MySQL Admin using MCP =================================== Create and manage Cloud SQL for MySQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for MySQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for MySQL using MCP. The `cloud-sql-mysql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for MySQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for MySQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Deploy to Kubernetes | MCP Toolbox for Databases Deploy to Kubernetes ==================== How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). Before you begin ---------------- 1. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 2. [Install the `gcloud` CLI](https://cloud.google.com/sdk/docs/install) . 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. You must have the following APIs enabled: gcloud services enable artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ container.googleapis.com \ iam.googleapis.com 5. `kubectl` is used to manage Kubernetes, the cluster orchestration system used by GKE. Verify if you have `kubectl` installed: kubectl version --client 6. If needed, install `kubectl` component using the Google Cloud CLI: gcloud components install kubectl Create a service account ------------------------ 1. Specify a name for your service account with an environment variable: export SA_NAME=toolbox 2. Create a backend service account: gcloud iam service-accounts create $SA_NAME 3. Grant any IAM roles necessary to the IAM service account. Each source has a list of necessary IAM permissions listed on its page. The example below is for cloud sql postgres source: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudsql.client * [AlloyDB IAM Identity](https://mcp-toolbox.dev/v0.26.0/resources/sources/alloydb-pg/#iam-permissions) * [CloudSQL IAM Identity](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-sql-pg/#iam-permissions) * [Spanner IAM Identity](https://mcp-toolbox.dev/v0.26.0/resources/sources/spanner/#iam-permissions) Deploy to Kubernetes -------------------- 1. Set environment variables: export CLUSTER_NAME=toolbox-cluster export DEPLOYMENT_NAME=toolbox export SERVICE_NAME=toolbox-service export REGION=us-central1 export NAMESPACE=toolbox-namespace export SECRET_NAME=toolbox-config export KSA_NAME=toolbox-service-account 2. Create a [GKE cluster](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-architecture) . gcloud container clusters create-auto $CLUSTER_NAME \ --location=us-central1 3. Get authentication credentials to interact with the cluster. This also configures `kubectl` to use the cluster. gcloud container clusters get-credentials $CLUSTER_NAME \ --region=$REGION \ --project=$PROJECT_ID 4. View the current context for `kubectl`. kubectl config current-context 5. Create namespace for the deployment. kubectl create namespace $NAMESPACE 6. Create a Kubernetes Service Account (KSA). kubectl create serviceaccount $KSA_NAME --namespace $NAMESPACE 7. Enable the IAM binding between Google Service Account (GSA) and Kubernetes Service Account (KSA). gcloud iam service-accounts add-iam-policy-binding \ --role="roles/iam.workloadIdentityUser" \ --member="serviceAccount:$PROJECT_ID.svc.id.goog[$NAMESPACE/$KSA_NAME]" \ $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com 8. Add annotation to KSA to complete binding: kubectl annotate serviceaccount \ $KSA_NAME \ iam.gke.io/gcp-service-account=$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --namespace $NAMESPACE 9. Prepare the Kubernetes secret for your `tools.yaml` file. kubectl create secret generic $SECRET_NAME \ --from-file=./tools.yaml \ --namespace=$NAMESPACE 10. Create a Kubernetes manifest file (`k8s_deployment.yaml`) to build deployment. apiVersion: apps/v1 kind: Deployment metadata: name: toolbox namespace: toolbox-namespace spec: selector: matchLabels: app: toolbox template: metadata: labels: app: toolbox spec: serviceAccountName: toolbox-service-account containers: - name: toolbox # Recommend to use the latest version of toolbox image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest args: ["--address", "0.0.0.0"] ports: - containerPort: 5000 volumeMounts: - name: toolbox-config mountPath: "/app/tools.yaml" subPath: tools.yaml readOnly: true volumes: - name: toolbox-config secret: secretName: toolbox-config items: - key: tools.yaml path: tools.yaml Tip To prevent DNS rebinding attack, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. E.g. `args: ["--address", "0.0.0.0", "--allowed-hosts", "foo.bar:5000"]` To implement CORs, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. E.g. `args: ["--address", "0.0.0.0", "--allowed-origins", "https://foo.bar"]` 11. Create the deployment. kubectl apply -f k8s_deployment.yaml --namespace $NAMESPACE 12. Check the status of deployment. kubectl get deployments --namespace $NAMESPACE 13. Create a Kubernetes manifest file (`k8s_service.yaml`) to build service. apiVersion: v1 kind: Service metadata: name: toolbox-service namespace: toolbox-namespace annotations: cloud.google.com/l4-rbs: "enabled" spec: selector: app: toolbox ports: - port: 5000 targetPort: 5000 type: LoadBalancer 14. Create the service. kubectl apply -f k8s_service.yaml --namespace $NAMESPACE 15. You can find your IP address created for your service by getting the service information through the following. kubectl describe services $SERVICE_NAME --namespace $NAMESPACE 16. To look at logs, run the following. kubectl logs -f deploy/$DEPLOYMENT_NAME --namespace $NAMESPACE 17. You might have to wait a couple of minutes. It is ready when you can see `EXTERNAL-IP` with the following command: kubectl get svc -n $NAMESPACE 18. Access toolbox locally. curl :5000 Clean up resources ------------------ 1. Delete secret. kubectl delete secret $SECRET_NAME --namespace $NAMESPACE 2. Delete deployment. kubectl delete deployment $DEPLOYMENT_NAME --namespace $NAMESPACE 3. Delete the application’s service. kubectl delete service $SERVICE_NAME --namespace $NAMESPACE 4. Delete the Kubernetes cluster. gcloud container clusters delete $CLUSTER_NAME \ --location=$REGION Last modified January 8, 2026: [feat: add allowed-hosts flag (#2254) (17b41f64531)](https://github.com/googleapis/genai-toolbox/commit/17b41f64531b8fe417c28ada45d1992ba430dc1b) --- # Spanner using MCP | MCP Toolbox for Databases Spanner using MCP ================= Connect your IDE to Spanner using Toolbox. Last modified June 12, 2025: [docs: redirect dev assist docs to official cloud documentation (#676) (cb87f765a6c)](https://github.com/googleapis/genai-toolbox/commit/cb87f765a6c8c511159586cb1fdc47daa7d63a18) --- # Resources | MCP Toolbox for Databases Resources ========= List of reference documentation for resources in Toolbox. * * * ##### [AuthServices](https://mcp-toolbox.dev/v0.24.0/resources/authservices/) AuthServices represent services that handle authentication and authorization. ##### [Sources](https://mcp-toolbox.dev/v0.24.0/resources/sources/) Sources represent your different data sources that a tool can interact with. ##### [Tools](https://mcp-toolbox.dev/v0.24.0/resources/tools/) Tools define actions an agent can take – such as reading and writing to a source. ##### [Prompts](https://mcp-toolbox.dev/v0.24.0/resources/prompts/) Prompts allow servers to provide structured messages and instructions for interacting with language models. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Export Telemetry | MCP Toolbox for Databases Export Telemetry ================ How to set up and configure Toolbox to use the Otel Collector. About ----- The [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) offers a vendor-agnostic implementation of how to receive, process and export telemetry data. It removes the need to run, operate, and maintain multiple agents/collectors. Configure the Collector ----------------------- To configure the collector, you will have to provide a configuration file. The configuration file consists of four classes of pipeline component that access telemetry data. * `Receivers` * `Processors` * `Exporters` * `Connectors` Example of setting up the classes of pipeline components (in this example, we don’t use connectors): receivers: otlp: protocols: http: endpoint: "127.0.0.1:4553" exporters: googlecloud: project: processors: batch: send_batch_size: 200 After each pipeline component is configured, you will enable it within the `service` section of the configuration file. service: pipelines: traces: receivers: ["otlp"] processors: ["batch"] exporters: ["googlecloud"] Running the Collector --------------------- There are a couple of steps to run and use a Collector. 1. [Install the Collector](https://opentelemetry.io/docs/collector/installation/) binary. Pull a binary or Docker image for the OpenTelemetry contrib collector. 2. Set up credentials for telemetry backend. 3. Set up the Collector config. Below are some examples for setting up the Collector config: * [Google Cloud Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter) * [Google Managed Service for Prometheus Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter#example-configuration) 4. Run the Collector with the configuration file. ./otelcol-contrib --config=collector-config.yaml 5. Run toolbox with the `--telemetry-otlp` flag. Configure it to send them to `127.0.0.1:4553` (for HTTP) or the Collector’s URL. ./toolbox --telemetry-otlp=127.0.0.1:4553 Tip To pass an insecure endpoint, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. 6. Once telemetry datas are collected, you can view them in your telemetry backend. If you are using GCP exporters, telemetry will be visible in GCP dashboard at [Metrics Explorer](https://console.cloud.google.com/monitoring/metrics-explorer) and [Trace Explorer](https://console.cloud.google.com/traces) . Note If you are exporting to Google Cloud monitoring, we recommend that you use the Google Cloud Exporter for traces and the Google Managed Service for Prometheus Exporter for metrics. Last modified December 18, 2025: [docs: telemetry docs to provide endpoint without scheme or path (#2179) (6e873494314)](https://github.com/googleapis/genai-toolbox/commit/6e8734943147dc919800db98af7987f2302c937d) --- # Deploy to Kubernetes | MCP Toolbox for Databases Deploy to Kubernetes ==================== How to set up and configure Toolbox to deploy on Kubernetes with Google Kubernetes Engine (GKE). Before you begin ---------------- 1. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 2. [Install the `gcloud` CLI](https://cloud.google.com/sdk/docs/install) . 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. You must have the following APIs enabled: gcloud services enable artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ container.googleapis.com \ iam.googleapis.com 5. `kubectl` is used to manage Kubernetes, the cluster orchestration system used by GKE. Verify if you have `kubectl` installed: kubectl version --client 6. If needed, install `kubectl` component using the Google Cloud CLI: gcloud components install kubectl Create a service account ------------------------ 1. Specify a name for your service account with an environment variable: export SA_NAME=toolbox 2. Create a backend service account: gcloud iam service-accounts create $SA_NAME 3. Grant any IAM roles necessary to the IAM service account. Each source has a list of necessary IAM permissions listed on its page. The example below is for cloud sql postgres source: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudsql.client * [AlloyDB IAM Identity](https://mcp-toolbox.dev/v0.27.0/resources/sources/alloydb-pg/#iam-permissions) * [CloudSQL IAM Identity](https://mcp-toolbox.dev/v0.27.0/resources/sources/cloud-sql-pg/#iam-permissions) * [Spanner IAM Identity](https://mcp-toolbox.dev/v0.27.0/resources/sources/spanner/#iam-permissions) Deploy to Kubernetes -------------------- 1. Set environment variables: export CLUSTER_NAME=toolbox-cluster export DEPLOYMENT_NAME=toolbox export SERVICE_NAME=toolbox-service export REGION=us-central1 export NAMESPACE=toolbox-namespace export SECRET_NAME=toolbox-config export KSA_NAME=toolbox-service-account 2. Create a [GKE cluster](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-architecture) . gcloud container clusters create-auto $CLUSTER_NAME \ --location=us-central1 3. Get authentication credentials to interact with the cluster. This also configures `kubectl` to use the cluster. gcloud container clusters get-credentials $CLUSTER_NAME \ --region=$REGION \ --project=$PROJECT_ID 4. View the current context for `kubectl`. kubectl config current-context 5. Create namespace for the deployment. kubectl create namespace $NAMESPACE 6. Create a Kubernetes Service Account (KSA). kubectl create serviceaccount $KSA_NAME --namespace $NAMESPACE 7. Enable the IAM binding between Google Service Account (GSA) and Kubernetes Service Account (KSA). gcloud iam service-accounts add-iam-policy-binding \ --role="roles/iam.workloadIdentityUser" \ --member="serviceAccount:$PROJECT_ID.svc.id.goog[$NAMESPACE/$KSA_NAME]" \ $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com 8. Add annotation to KSA to complete binding: kubectl annotate serviceaccount \ $KSA_NAME \ iam.gke.io/gcp-service-account=$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \ --namespace $NAMESPACE 9. Prepare the Kubernetes secret for your `tools.yaml` file. kubectl create secret generic $SECRET_NAME \ --from-file=./tools.yaml \ --namespace=$NAMESPACE 10. Create a Kubernetes manifest file (`k8s_deployment.yaml`) to build deployment. apiVersion: apps/v1 kind: Deployment metadata: name: toolbox namespace: toolbox-namespace spec: selector: matchLabels: app: toolbox template: metadata: labels: app: toolbox spec: serviceAccountName: toolbox-service-account containers: - name: toolbox # Recommend to use the latest version of toolbox image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest args: ["--address", "0.0.0.0"] ports: - containerPort: 5000 volumeMounts: - name: toolbox-config mountPath: "/app/tools.yaml" subPath: tools.yaml readOnly: true volumes: - name: toolbox-config secret: secretName: toolbox-config items: - key: tools.yaml path: tools.yaml Tip To prevent DNS rebinding attack, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. E.g. `args: ["--address", "0.0.0.0", "--allowed-hosts", "foo.bar:5000"]` To implement CORs, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. E.g. `args: ["--address", "0.0.0.0", "--allowed-origins", "https://foo.bar"]` 11. Create the deployment. kubectl apply -f k8s_deployment.yaml --namespace $NAMESPACE 12. Check the status of deployment. kubectl get deployments --namespace $NAMESPACE 13. Create a Kubernetes manifest file (`k8s_service.yaml`) to build service. apiVersion: v1 kind: Service metadata: name: toolbox-service namespace: toolbox-namespace annotations: cloud.google.com/l4-rbs: "enabled" spec: selector: app: toolbox ports: - port: 5000 targetPort: 5000 type: LoadBalancer 14. Create the service. kubectl apply -f k8s_service.yaml --namespace $NAMESPACE 15. You can find your IP address created for your service by getting the service information through the following. kubectl describe services $SERVICE_NAME --namespace $NAMESPACE 16. To look at logs, run the following. kubectl logs -f deploy/$DEPLOYMENT_NAME --namespace $NAMESPACE 17. You might have to wait a couple of minutes. It is ready when you can see `EXTERNAL-IP` with the following command: kubectl get svc -n $NAMESPACE 18. Access toolbox locally. curl :5000 Clean up resources ------------------ 1. Delete secret. kubectl delete secret $SECRET_NAME --namespace $NAMESPACE 2. Delete deployment. kubectl delete deployment $DEPLOYMENT_NAME --namespace $NAMESPACE 3. Delete the application’s service. kubectl delete service $SERVICE_NAME --namespace $NAMESPACE 4. Delete the Kubernetes cluster. gcloud container clusters delete $CLUSTER_NAME \ --location=$REGION Last modified January 8, 2026: [feat: add allowed-hosts flag (#2254) (17b41f64531)](https://github.com/googleapis/genai-toolbox/commit/17b41f64531b8fe417c28ada45d1992ba430dc1b) --- # Deploy using Docker Compose | MCP Toolbox for Databases Deploy using Docker Compose =========================== How to deploy Toolbox using Docker Compose. Before you begin ---------------- 1. [Install Docker Compose.](https://docs.docker.com/compose/install/) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://github.com/googleapis/genai-toolbox/blob/main/README.md#configuration) section. Deploy using Docker Compose --------------------------- 1. Create a `docker-compose.yml` file, customizing as needed: services: toolbox: # TODO: It is recommended to pin to a specific image version instead of latest. image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest hostname: toolbox platform: linux/amd64 ports: - "5000:5000" volumes: - ./config:/config command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0"] depends_on: db: condition: service_healthy networks: - tool-network db: # TODO: It is recommended to pin to a specific image version instead of latest. image: postgres hostname: db environment: POSTGRES_USER: toolbox_user POSTGRES_PASSWORD: my-password POSTGRES_DB: toolbox_db ports: - "5432:5432" volumes: - ./db:/var/lib/postgresql/data # This file can be used to bootstrap your schema if needed. # See "initialization scripts" on https://hub.docker.com/_/postgres/ for more info - ./config/init.sql:/docker-entrypoint-initdb.d/init.sql healthcheck: test: ["CMD-SHELL", "pg_isready -U toolbox_user -d toolbox_db"] interval: 10s timeout: 5s retries: 5 networks: - tool-network networks: tool-network: TipTo prevent DNS rebinding attack, use the --allowed-hosts flag to specify a list of hosts for validation. E.g. command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0", "--allowed-hosts", "localhost:5000"] To implement CORs, use the --allowed-origins flag to specify a list of origins permitted to access the server. E.g. command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0", "--allowed-origins", "https://foo.bar"] 1. Run the following command to bring up the Toolbox and Postgres instance docker-compose up -d Tip You can use this setup to quickly set up Toolbox + Postgres to follow along in our [Quickstart](https://mcp-toolbox.dev/v0.26.0/getting-started/local_quickstart/) Connecting with Toolbox Client SDK ---------------------------------- Next, we will use Toolbox with the Client SDKs: 1. The url for the Toolbox server running using docker-compose will be: http://localhost:5000 2. Import and initialize the client with the URL: * LangChain * Llamaindex from toolbox_langchain import ToolboxClient # Replace with the cloud run service URL generated above async with ToolboxClient("http://$YOUR_URL") as toolbox: from toolbox_llamaindex import ToolboxClient # Replace with the cloud run service URL generated above async with ToolboxClient("http://$YOUR_URL") as toolbox: Last modified January 8, 2026: [feat: add allowed-hosts flag (#2254) (17b41f64531)](https://github.com/googleapis/genai-toolbox/commit/17b41f64531b8fe417c28ada45d1992ba430dc1b) --- # Export Telemetry | MCP Toolbox for Databases Export Telemetry ================ How to set up and configure Toolbox to use the Otel Collector. About ----- The [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) offers a vendor-agnostic implementation of how to receive, process and export telemetry data. It removes the need to run, operate, and maintain multiple agents/collectors. Configure the Collector ----------------------- To configure the collector, you will have to provide a configuration file. The configuration file consists of four classes of pipeline component that access telemetry data. * `Receivers` * `Processors` * `Exporters` * `Connectors` Example of setting up the classes of pipeline components (in this example, we don’t use connectors): receivers: otlp: protocols: http: endpoint: "127.0.0.1:4553" exporters: googlecloud: project: processors: batch: send_batch_size: 200 After each pipeline component is configured, you will enable it within the `service` section of the configuration file. service: pipelines: traces: receivers: ["otlp"] processors: ["batch"] exporters: ["googlecloud"] Running the Collector --------------------- There are a couple of steps to run and use a Collector. 1. [Install the Collector](https://opentelemetry.io/docs/collector/installation/) binary. Pull a binary or Docker image for the OpenTelemetry contrib collector. 2. Set up credentials for telemetry backend. 3. Set up the Collector config. Below are some examples for setting up the Collector config: * [Google Cloud Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter) * [Google Managed Service for Prometheus Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter#example-configuration) 4. Run the Collector with the configuration file. ./otelcol-contrib --config=collector-config.yaml 5. Run toolbox with the `--telemetry-otlp` flag. Configure it to send them to `127.0.0.1:4553` (for HTTP) or the Collector’s URL. ./toolbox --telemetry-otlp=127.0.0.1:4553 Tip To pass an insecure endpoint, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. 6. Once telemetry datas are collected, you can view them in your telemetry backend. If you are using GCP exporters, telemetry will be visible in GCP dashboard at [Metrics Explorer](https://console.cloud.google.com/monitoring/metrics-explorer) and [Trace Explorer](https://console.cloud.google.com/traces) . Note If you are exporting to Google Cloud monitoring, we recommend that you use the Google Cloud Exporter for traces and the Google Managed Service for Prometheus Exporter for metrics. Last modified December 18, 2025: [docs: telemetry docs to provide endpoint without scheme or path (#2179) (6e873494314)](https://github.com/googleapis/genai-toolbox/commit/6e8734943147dc919800db98af7987f2302c937d) --- # SQL Server using MCP | MCP Toolbox for Databases SQL Server using MCP ==================== Connect your IDE to SQL Server using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQL Server. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQL Server instance: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/mssql_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQL Server instance.](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "mssql": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlserver": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","mssql","--stdio"], "env": { "MSSQL_HOST": "", "MSSQL_PORT": "", "MSSQL_DATABASE": "", "MSSQL_USER": "", "MSSQL_PASSWORD": "" } } } } Use Tools --------- Your AI tool is now connected to SQL Server using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # Google Sign-In | MCP Toolbox for Databases Google Sign-In ============== Use Google Sign-In for Oauth 2.0 flow and token lifecycle. Getting Started --------------- Google Sign-In manages the OAuth 2.0 flow and token lifecycle. To integrate the Google Sign-In workflow to your web app [follow this guide](https://developers.google.com/identity/sign-in/web/sign-in) . After setting up the Google Sign-In workflow, you should have registered your application and retrieved a [Client ID](https://developers.google.com/identity/sign-in/web/sign-in#create_authorization_credentials) . Configure your auth service in with the `Client ID`. Behavior -------- ### Authorized Invocations When using [Authorized Invocations](https://mcp-toolbox.dev/v0.24.0/resources/tools/#authorized-invocations) , a tool will be considered authorized if it has a valid Oauth 2.0 token that matches the Client ID. ### Authenticated Parameters When using [Authenticated Parameters](https://mcp-toolbox.dev/v0.24.0/resources/tools/#authenticated-parameters) , any [claim provided by the id-token](https://developers.google.com/identity/openid-connect/openid-connect#obtaininguserprofileinformation) can be used for the parameter. Example ------- authServices: my-google-auth: kind: google clientId: ${YOUR_GOOGLE_CLIENT_ID} Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “google”. | | clientId | string | true | Client ID of your application from registering your application. | Last modified August 15, 2025: [docs: fix typos across docs (#1154) (c65c11af246)](https://github.com/googleapis/genai-toolbox/commit/c65c11af2463009b06c3fc3d5dbdf350bdcd2494) --- # AlloyDB Admin | MCP Toolbox for Databases AlloyDB Admin ============= The “alloydb-admin” source provides a client for the AlloyDB API. About ----- The `alloydb-admin` source provides a client to interact with the [Google AlloyDB API](https://cloud.google.com/alloydb/docs/reference/rest) . This allows tools to perform administrative tasks on AlloyDB resources, such as managing clusters, instances, and users. Authentication can be handled in two ways: 1. **Application Default Credentials (ADC):** By default, the source uses ADC to authenticate with the API. 2. **Client-side OAuth:** If `useClientOAuth` is set to `true`, the source will expect an OAuth 2.0 access token to be provided by the client (e.g., a web browser) for each request. Example ------- sources: my-alloydb-admin: kind: alloy-admin my-oauth-alloydb-admin: kind: alloydb-admin useClientOAuth: true Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “alloydb-admin”. | | defaultProject | string | false | The Google Cloud project ID to use for AlloyDB infrastructure tools. | | useClientOAuth | boolean | false | If true, the source will use client-side OAuth for authorization. Otherwise, it will use Application Default Credentials. Defaults to `false`. | Last modified November 11, 2025: [feat(source/alloydb, source/cloud-sql-postgres,source/cloud-sql-mysql,source/cloud-sql-mssql): Use project from env for alloydb and cloud sql control plane tools (#1588) (12bdd954597)](https://github.com/googleapis/genai-toolbox/commit/12bdd954597e49d3ec6b247cc104584c5a4d1943) --- # Resources | MCP Toolbox for Databases Resources ========= List of reference documentation for resources in Toolbox. * * * ##### [AuthServices](https://mcp-toolbox.dev/v0.25.0/resources/authservices/) AuthServices represent services that handle authentication and authorization. ##### [Sources](https://mcp-toolbox.dev/v0.25.0/resources/sources/) Sources represent your different data sources that a tool can interact with. ##### [EmbeddingModels](https://mcp-toolbox.dev/v0.25.0/resources/embeddingmodels/) EmbeddingModels represent services that transform text into vector embeddings for semantic search. ##### [Tools](https://mcp-toolbox.dev/v0.25.0/resources/tools/) Tools define actions an agent can take – such as reading and writing to a source. ##### [Prompts](https://mcp-toolbox.dev/v0.25.0/resources/prompts/) Prompts allow servers to provide structured messages and instructions for interacting with language models. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Sources | MCP Toolbox for Databases Sources ======= Sources represent your different data sources that a tool can interact with. A Source represents a data sources that a tool can interact with. You can define Sources as a map in the `sources` section of your `tools.yaml` file. Typically, a source configuration will contain any information needed to connect with and interact with the database. Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-cloud-sql-source: kind: cloud-sql-postgres project: my-project-id region: us-central1 instance: my-instance-name database: my_db user: ${USER_NAME} password: ${PASSWORD} In implementation, each source is a different connection pool or client that used to connect to the database and execute the tool. Available Sources ----------------- * * * ##### [AlloyDB for PostgreSQL](https://mcp-toolbox.dev/v0.24.0/resources/sources/alloydb-pg/) AlloyDB for PostgreSQL is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. ##### [AlloyDB Admin](https://mcp-toolbox.dev/v0.24.0/resources/sources/alloydb-admin/) The “alloydb-admin” source provides a client for the AlloyDB API. ##### [BigQuery](https://mcp-toolbox.dev/v0.24.0/resources/sources/bigquery/) BigQuery is Google Cloud’s fully managed, petabyte-scale, and cost-effective analytics data warehouse that lets you run analytics over vast amounts of data in near real time. With BigQuery, there’s no infrastructure to set up or manage, letting you focus on finding meaningful insights using GoogleSQL and taking advantage of flexible pricing models across on-demand and flat-rate options. ##### [Bigtable](https://mcp-toolbox.dev/v0.24.0/resources/sources/bigtable/) Bigtable is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. ##### [Cassandra](https://mcp-toolbox.dev/v0.24.0/resources/sources/cassandra/) Apache Cassandra is a NoSQL distributed database known for its horizontal scalability, distributed architecture, and flexible schema definition. ##### [ClickHouse](https://mcp-toolbox.dev/v0.24.0/resources/sources/clickhouse/) ClickHouse is an open-source, OLTP database. ##### [Cloud Healthcare API](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-healthcare/) The Cloud Healthcare API provides a managed solution for storing and accessing healthcare data in Google Cloud, providing a critical bridge between existing care systems and applications hosted on Google Cloud. ##### [Cloud Monitoring](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-monitoring/) A “cloud-monitoring” source provides a client for the Cloud Monitoring API. ##### [Cloud SQL for MySQL](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-sql-mysql/) Cloud SQL for MySQL is a fully-managed database service for MySQL. ##### [Cloud SQL for PostgreSQL](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-sql-pg/) Cloud SQL for PostgreSQL is a fully-managed database service for Postgres. ##### [Cloud SQL for SQL Server](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-sql-mssql/) Cloud SQL for SQL Server is a fully-managed database service for SQL Server. ##### [Cloud SQL Admin](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-sql-admin/) A “cloud-sql-admin” source provides a client for the Cloud SQL Admin API. ##### [Couchbase](https://mcp-toolbox.dev/v0.24.0/resources/sources/couchbase/) A “couchbase” source connects to a Couchbase database. ##### [Dataplex](https://mcp-toolbox.dev/v0.24.0/resources/sources/dataplex/) Dataplex Universal Catalog is a unified, intelligent governance solution for data and AI assets in Google Cloud. Dataplex Universal Catalog powers AI, analytics, and business intelligence at scale. ##### [Dgraph](https://mcp-toolbox.dev/v0.24.0/resources/sources/dgraph/) Dgraph is fully open-source, built-for-scale graph database for Gen AI workloads ##### [Elasticsearch](https://mcp-toolbox.dev/v0.24.0/resources/sources/elasticsearch/) Elasticsearch is a distributed, free and open search and analytics engine for all types of data, including textual, numerical, geospatial, structured, and unstructured. ##### [Firebird](https://mcp-toolbox.dev/v0.24.0/resources/sources/firebird/) Firebird is a powerful, cross-platform, and open-source relational database. ##### [Firestore](https://mcp-toolbox.dev/v0.24.0/resources/sources/firestore/) Firestore is a NoSQL document database built for automatic scaling, high performance, and ease of application development. It’s a fully managed, serverless database that supports mobile, web, and server development. ##### [Gemini Data Analytics](https://mcp-toolbox.dev/v0.24.0/resources/sources/cloud-gda/) A “cloud-gemini-data-analytics” source provides a client for the Gemini Data Analytics API. ##### [HTTP](https://mcp-toolbox.dev/v0.24.0/resources/sources/http/) The HTTP source enables the Toolbox to retrieve data from a remote server using HTTP requests. ##### [Looker](https://mcp-toolbox.dev/v0.24.0/resources/sources/looker/) Looker is a business intelligence tool that also provides a semantic layer. ##### [MariaDB](https://mcp-toolbox.dev/v0.24.0/resources/sources/mariadb/) MariaDB is an open-source relational database compatible with MySQL. ##### [MindsDB](https://mcp-toolbox.dev/v0.24.0/resources/sources/mindsdb/) MindsDB is an AI federated database that enables SQL queries across hundreds of datasources and ML models. ##### [MongoDB](https://mcp-toolbox.dev/v0.24.0/resources/sources/mongodb/) MongoDB is a no-sql data platform that can not only serve general purpose data requirements also perform VectorSearch where both operational data and embeddings used of search can reside in same document. ##### [MySQL](https://mcp-toolbox.dev/v0.24.0/resources/sources/mysql/) MySQL is a relational database management system that stores and manages data. ##### [Neo4j](https://mcp-toolbox.dev/v0.24.0/resources/sources/neo4j/) Neo4j is a powerful, open source graph database system ##### [OceanBase](https://mcp-toolbox.dev/v0.24.0/resources/sources/oceanbase/) OceanBase is a distributed relational database that provides high availability, scalability, and compatibility with MySQL. ##### [Oracle](https://mcp-toolbox.dev/v0.24.0/resources/sources/oracle/) Oracle Database is a widely-used relational database management system. ##### [PostgreSQL](https://mcp-toolbox.dev/v0.24.0/resources/sources/postgres/) PostgreSQL is a powerful, open source object-relational database. ##### [Redis](https://mcp-toolbox.dev/v0.24.0/resources/sources/redis/) Redis is a in-memory data structure store. ##### [Serverless for Apache Spark](https://mcp-toolbox.dev/v0.24.0/resources/sources/serverless-spark/) Google Cloud Serverless for Apache Spark lets you run Spark workloads without requiring you to provision and manage your own Spark cluster. ##### [SingleStore](https://mcp-toolbox.dev/v0.24.0/resources/sources/singlestore/) SingleStore is the cloud-native database built with speed and scale to power data-intensive applications. ##### [Spanner](https://mcp-toolbox.dev/v0.24.0/resources/sources/spanner/) Spanner is a fully managed database service from Google Cloud that combines relational, key-value, graph, and search capabilities. ##### [SQL Server](https://mcp-toolbox.dev/v0.24.0/resources/sources/mssql/) SQL Server is a relational database management system (RDBMS). ##### [SQLite](https://mcp-toolbox.dev/v0.24.0/resources/sources/sqlite/) SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. ##### [TiDB](https://mcp-toolbox.dev/v0.24.0/resources/sources/tidb/) TiDB is a distributed SQL database that combines the best of traditional RDBMS and NoSQL databases. ##### [Trino](https://mcp-toolbox.dev/v0.24.0/resources/sources/trino/) Trino is a distributed SQL query engine for big data analytics. ##### [Valkey](https://mcp-toolbox.dev/v0.24.0/resources/sources/valkey/) Valkey is an open-source, in-memory data structure store, forked from Redis. ##### [YugabyteDB](https://mcp-toolbox.dev/v0.24.0/resources/sources/yugabytedb/) YugabyteDB is a high-performance, distributed SQL database. Last modified April 23, 2025: [feat: Support env replacement for tool.yaml (#462) (eadb678a7bd)](https://github.com/googleapis/genai-toolbox/commit/eadb678a7bd4ce74a3b1160f5ed8966ffbb13c61) --- # Bigtable | MCP Toolbox for Databases Bigtable ======== Bigtable is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. Bigtable Source =============== [Bigtable](https://cloud.google.com/bigtable/docs) is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. If you are new to Bigtable, you can try to [create an instance and write data with the cbt CLI](https://cloud.google.com/bigtable/docs/create-instance-write-data-cbt-cli) . You can use [GoogleSQL statements](https://cloud.google.com/bigtable/docs/googlesql-overview) to query your Bigtable data. GoogleSQL is an ANSI-compliant structured query language (SQL) that is also implemented for other Google Cloud services. SQL queries are handled by cluster nodes in the same way as NoSQL data requests. Therefore, the same best practices apply when creating SQL queries to run against your Bigtable data, such as avoiding full table scans or complex filters. Available Tools --------------- * [`bigtable-sql`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigtable/bigtable-sql/) Run SQL-like queries over Bigtable rows. Requirements ------------ ### IAM Permissions Bigtable uses [Identity and Access Management (IAM)](https://cloud.google.com/bigtable/docs/access-control) to control user and group access to Bigtable resources at the project, instance, table, and backup level. Toolbox will use your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize and authenticate when interacting with [Bigtable](https://cloud.google.com/bigtable/docs) . In addition to [setting the ADC for your server](https://cloud.google.com/docs/authentication/provide-credentials-adc) , you need to ensure the IAM identity has been given the correct IAM permissions for the query provided. See [Apply IAM roles](https://cloud.google.com/bigtable/docs/access-control#iam-management-instance) for more information on applying IAM permissions and roles to an identity. Example ------- sources: my-bigtable-source: kind: "bigtable" project: "my-project-id" instance: "test-instance" Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “bigtable”. | | project | string | true | Id of the GCP project that the cluster was created in (e.g. “my-project-id”). | | instance | string | true | Name of the Bigtable instance. | Last modified July 22, 2025: [docs: add available tools for each source (#914) (a1def43b350)](https://github.com/googleapis/genai-toolbox/commit/a1def43b3502e90aacdfee669010ea29e0558452) --- # AlloyDB for PostgreSQL | MCP Toolbox for Databases AlloyDB for PostgreSQL ====================== AlloyDB for PostgreSQL is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. About ----- [AlloyDB for PostgreSQL](https://cloud.google.com/alloydb/docs) is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. It provides enterprise-grade performance and availability while maintaining 100% compatibility with open-source PostgreSQL. If you are new to AlloyDB for PostgreSQL, you can [create a free trial cluster](https://cloud.google.com/alloydb/docs/create-free-trial-cluster) . Available Tools --------------- * [`alloydb-ai-nl`](https://mcp-toolbox.dev/v0.24.0/resources/tools/alloydbainl/alloydb-ai-nl/) Use natural language queries on AlloyDB, powered by AlloyDB AI. * [`postgres-sql`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-sql/) Execute SQL queries as prepared statements in AlloyDB Postgres. * [`postgres-execute-sql`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-execute-sql/) Run parameterized SQL statements in AlloyDB Postgres. * [`postgres-list-tables`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-tables/) List tables in an AlloyDB for PostgreSQL database. * [`postgres-list-active-queries`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-active-queries/) List active queries in an AlloyDB for PostgreSQL database. * [`postgres-list-available-extensions`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-available-extensions/) List available extensions for installation in a PostgreSQL database. * [`postgres-list-installed-extensions`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-installed-extensions/) List installed extensions in a PostgreSQL database. * [`postgres-list-views`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-views/) List views in an AlloyDB for PostgreSQL database. * [`postgres-list-schemas`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-schemas/) List schemas in an AlloyDB for PostgreSQL database. * [`postgres-database-overview`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-database-overview/) Fetches the current state of the PostgreSQL server. * [`postgres-list-triggers`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-triggers/) List triggers in an AlloyDB for PostgreSQL database. * [`postgres-list-indexes`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-indexes/) List available user indexes in a PostgreSQL database. * [`postgres-list-sequences`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-sequences/) List sequences in a PostgreSQL database. * [`postgres-long-running-transactions`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-long-running-transactions/) List long running transactions in a PostgreSQL database. * [`postgres-list-locks`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-locks/) List lock stats in a PostgreSQL database. * [`postgres-replication-stats`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-replication-stats/) List replication stats in a PostgreSQL database. * [`postgres-list-query-stats`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-query-stats/) List query statistics in a PostgreSQL database. * [`postgres-get-column-cardinality`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-get-column-cardinality/) List cardinality of columns in a table in a PostgreSQL database. * [`postgres-list-table-stats`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-table-stats/) List statistics of a table in a PostgreSQL database. * [`postgres-list-publication-tables`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-publication-tables/) List publication tables in a PostgreSQL database. * [`postgres-list-tablespaces`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-tablespaces/) List tablespaces in an AlloyDB for PostgreSQL database. * [`postgres-list-pg-settings`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-pg-settings/) List configuration parameters for the PostgreSQL server. * [`postgres-list-database-stats`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-database-stats/) Lists the key performance and activity statistics for each database in the AlloyDB instance. * [`postgres-list-roles`](https://mcp-toolbox.dev/v0.24.0/resources/tools/postgres/postgres-list-roles/) Lists all the user-created roles in PostgreSQL database.. ### Pre-built Configurations * [AlloyDB using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. * [AlloyDB Admin API using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. Requirements ------------ ### IAM Permissions By default, AlloyDB for PostgreSQL source uses the [AlloyDB Go Connector](https://github.com/GoogleCloudPlatform/alloydb-go-connector) to authorize and establish mTLS connections to your AlloyDB instance. The Go connector uses your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize your connection to AlloyDB. In addition to [setting the ADC for your server](https://cloud.google.com/docs/authentication/provide-credentials-adc) , you need to ensure the IAM identity has been given the following IAM roles (or corresponding permissions): * `roles/alloydb.client` * `roles/serviceusage.serviceUsageConsumer` ### Networking AlloyDB supports connecting over both from external networks via the internet ([public IP](https://cloud.google.com/alloydb/docs/connect-public-ip) ), and internal networks ([private IP](https://cloud.google.com/alloydb/docs/private-ip) ). For more information on choosing between the two options, see the AlloyDB page [Connection overview](https://cloud.google.com/alloydb/docs/connection-overview) . You can configure the `ipType` parameter in your source configuration to `public` or `private` to match your cluster’s configuration. Regardless of which you choose, all connections use IAM-based authorization and are encrypted with mTLS. ### Authentication This source supports both password-based authentication and IAM authentication (using your [Application Default Credentials](https://cloud.google.com/docs/authentication#adc) ). #### Standard Authentication To connect using user/password, [create a PostgreSQL user](https://cloud.google.com/alloydb/docs/database-users/about) and input your credentials in the `user` and `password` fields. user: ${USER_NAME} password: ${PASSWORD} #### IAM Authentication To connect using IAM authentication: 1. Prepare your database instance and user following this [guide](https://cloud.google.com/alloydb/docs/database-users/manage-iam-auth) . 2. You could choose one of the two ways to log in: * Specify your IAM email as the `user`. * Leave your `user` field blank. Toolbox will fetch the [ADC](https://cloud.google.com/docs/authentication#adc) automatically and log in using the email associated with it. 3. Leave the `password` field blank. Example ------- sources: my-alloydb-pg-source: kind: alloydb-postgres project: my-project-id region: us-central1 cluster: my-cluster instance: my-instance database: my_db user: ${USER_NAME} password: ${PASSWORD} # ipType: "public" Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “alloydb-postgres”. | | project | string | true | Id of the GCP project that the cluster was created in (e.g. “my-project-id”). | | region | string | true | Name of the GCP region that the cluster was created in (e.g. “us-central1”). | | cluster | string | true | Name of the AlloyDB cluster (e.g. “my-cluster”). | | instance | string | true | Name of the AlloyDB instance within the cluster (e.g. “my-instance”). | | database | string | true | Name of the Postgres database to connect to (e.g. “my\_db”). | | user | string | false | Name of the Postgres user to connect as (e.g. “my-pg-user”). Defaults to IAM auth using [ADC](https://cloud.google.com/docs/authentication#adc)
email if unspecified. | | password | string | false | Password of the Postgres user (e.g. “my-password”). Defaults to attempting IAM authentication if unspecified. | | ipType | string | false | IP Type of the AlloyDB instance; must be one of `public` or `private`. Default: `public`. | Last modified December 10, 2025: [feat: add list-table-stats-tool to list table statistics. (#2055) (78b02f08c3c)](https://github.com/googleapis/genai-toolbox/commit/78b02f08c3cc3062943bb2f91cf60d5149c8d28d) --- # Cassandra | MCP Toolbox for Databases Cassandra ========= Apache Cassandra is a NoSQL distributed database known for its horizontal scalability, distributed architecture, and flexible schema definition. About ----- [Apache Cassandra](https://cassandra.apache.org/) is a NoSQL distributed database. By design, NoSQL databases are lightweight, open-source, non-relational, and largely distributed. Counted among their strengths are horizontal scalability, distributed architectures, and a flexible approach to schema definition. Available Tools --------------- * [`cassandra-cql`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cassandra/cassandra-cql/) Run parameterized CQL queries in Cassandra. Example ------- sources: my-cassandra-source: kind: cassandra hosts: - 127.0.0.1 keyspace: my_keyspace protoVersion: 4 username: ${USER_NAME} password: ${PASSWORD} caPath: /path/to/ca.crt # Optional: path to CA certificate certPath: /path/to/client.crt # Optional: path to client certificate keyPath: /path/to/client.key # Optional: path to client key enableHostVerification: true # Optional: enable host verification Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “cassandra”. | | hosts | string\[\] | true | List of IP addresses to connect to (e.g., \[“192.168.1.1:9042”, “192.168.1.2:9042”,“192.168.1.3:9042”\]). The default port is 9042 if not specified. | | keyspace | string | true | Name of the Cassandra keyspace to connect to (e.g., “my\_keyspace”). | | protoVersion | integer | false | Protocol version for the Cassandra connection (e.g., 4). | | username | string | false | Name of the Cassandra user to connect as (e.g., “my-cassandra-user”). | | password | string | false | Password of the Cassandra user (e.g., “my-password”). | | caPath | string | false | Path to the CA certificate for SSL/TLS (e.g., “/path/to/ca.crt”). | | certPath | string | false | Path to the client certificate for SSL/TLS (e.g., “/path/to/client.crt”). | | keyPath | string | false | Path to the client key for SSL/TLS (e.g., “/path/to/client.key”). | | enableHostVerification | boolean | false | Enable host verification for SSL/TLS (e.g., true). By default, host verification is disabled. | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # AuthServices | MCP Toolbox for Databases AuthServices ============ AuthServices represent services that handle authentication and authorization. AuthServices represent services that handle authentication and authorization. It can primarily be used by [Tools](https://mcp-toolbox.dev/v0.24.0/resources/tools/) in two different ways: * [**Authorized Invocation**](https://mcp-toolbox.dev/v0.24.0/resources/tools/#authorized-invocations) is when a tool is validated by the auth service before the call can be invoked. Toolbox will reject any calls that fail to validate or have an invalid token. * [**Authenticated Parameters**](https://mcp-toolbox.dev/v0.24.0/resources/tools/#authenticated-parameters) replace the value of a parameter with a field from an [OIDC](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) claim. Toolbox will automatically resolve the ID token provided by the client and replace the parameter in the tool call. Example ------- The following configurations are placed at the top level of a `tools.yaml` file. Tip If you are accessing Toolbox with multiple applications, each application should register their own Client ID even if they use the same “kind” of auth provider. authServices: my_auth_app_1: kind: google clientId: ${YOUR_CLIENT_ID_1} my_auth_app_2: kind: google clientId: ${YOUR_CLIENT_ID_2} Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. After you’ve configured an `authService` you’ll, need to reference it in the configuration for each tool that should use it: * **Authorized Invocations** for authorizing a tool call, [use the `authRequired` field in a tool config](https://mcp-toolbox.dev/v0.24.0/resources/tools/#authorized-invocations) * **Authenticated Parameters** for using the value from a OIDC claim, [use the `authServices` field in a parameter config](https://mcp-toolbox.dev/v0.24.0/resources/tools/#authenticated-parameters) Specifying ID Tokens from Clients --------------------------------- After [configuring](https://mcp-toolbox.dev/v0.24.0/resources/authservices/#example) your `authServices` section, use a Toolbox SDK to add your ID tokens to the header of a Tool invocation request. When specifying a token you will provide a function (that returns an id). This function is called when the tool is invoked. This allows you to cache and refresh the ID token as needed. The primary method for providing these getters is via the `auth_token_getters` parameter when loading tools, or the `add_auth_token_getter`() / `add_auth_token_getters()` methods on a loaded tool object. ### Specifying tokens during load #### Python Use the [Python SDK](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main) . * Core * LangChain * Llamaindex import asyncio from toolbox_core import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): async with ToolboxClient("") as toolbox: auth_tool = await toolbox.load_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) result = await auth_tool(param="value") print(result) if **name** == "**main**": asyncio.run(main()) import asyncio from toolbox_langchain import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): toolbox = ToolboxClient("") auth_tool = await toolbox.aload_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) result = await auth_tool.ainvoke({"param": "value"}) print(result) if **name** == "**main**": asyncio.run(main()) import asyncio from toolbox_llamaindex import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): toolbox = ToolboxClient("") auth_tool = await toolbox.aload_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) # result = await auth_tool.acall(param="value") # print(result.content) if **name** == "**main**": asyncio.run(main()) #### Javascript/Typescript Use the [JS SDK](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main) . import { ToolboxClient } from '@toolbox-sdk/core'; async function getAuthToken() { // ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) // This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" // Placeholder } const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const authTool = await client.loadTool("my-tool", {"my_auth_app_1": getAuthToken}); const result = await authTool({param:"value"}); console.log(result); print(result) #### Go Use the [Go SDK](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main) . import "github.com/googleapis/mcp-toolbox-sdk-go/core" import "fmt" func getAuthToken() string { // ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) // This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" // Placeholder } func main() { URL := 'http://127.0.0.1:5000' client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } dynamicTokenSource := core.NewCustomTokenSource(getAuthToken) authTool, err := client.LoadTool( "my-tool", ctx, core.WithAuthTokenSource("my_auth_app_1", dynamicTokenSource)) if err != nil { log.Fatalf("Failed to load tool: %v", err) } inputs := map[string]any{"param": "value"} result, err := authTool.Invoke(ctx, inputs) if err != nil { log.Fatalf("Failed to invoke tool: %v", err) } fmt.Println(result) } ### Specifying tokens for existing tools #### Python Use the [Python SDK](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main) . * Core * LangChain * Llamaindex tools = await toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) tools = toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) tools = toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) #### Javascript/Typescript Use the [JS SDK](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main) . const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); let tool = await client.loadTool("my-tool") // for a single token const authorizedTool = tool.addAuthTokenGetter("my_auth", get_auth_token) // OR, if multiple tokens are needed const multiAuthTool = tool.addAuthTokenGetters({ "my_auth_1": getAuthToken1, "my_auth_2": getAuthToken2, }) #### Go Use the [Go SDK](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main) . import "github.com/googleapis/mcp-toolbox-sdk-go/core" func main() { URL := 'http://127.0.0.1:5000' client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } tool, err := client.LoadTool("my-tool", ctx)) if err != nil { log.Fatalf("Failed to load tool: %v", err) } dynamicTokenSource1 := core.NewCustomTokenSource(getAuthToken1) dynamicTokenSource2 := core.NewCustomTokenSource(getAuthToken1) // For a single token authTool, err := tool.ToolFrom( core.WithAuthTokenSource("my-auth", dynamicTokenSource), ) // OR, if multiple tokens are needed authTool, err := tool.ToolFrom( core.WithAuthTokenSource("my-auth_1", dynamicTokenSource1), core.WithAuthTokenSource("my-auth_2", dynamicTokenSource2), ) } Kinds of Auth Services ---------------------- * * * ##### [Google Sign-In](https://mcp-toolbox.dev/v0.24.0/resources/authservices/google/) Use Google Sign-In for Oauth 2.0 flow and token lifecycle. Last modified September 18, 2025: [docs: fix docs linting (#1520) (3d8a041782d)](https://github.com/googleapis/genai-toolbox/commit/3d8a041782db4ec94d25f1e96d69cb9e5941e9e6) --- # ClickHouse | MCP Toolbox for Databases ClickHouse ========== ClickHouse is an open-source, OLTP database. About ----- [ClickHouse](https://clickhouse.com/docs) is a fast, open-source, column-oriented database Available Tools --------------- * [`clickhouse-execute-sql`](https://mcp-toolbox.dev/v0.24.0/resources/tools/clickhouse/clickhouse-execute-sql/) Execute parameterized SQL queries in ClickHouse with query logging. * [`clickhouse-sql`](https://mcp-toolbox.dev/v0.24.0/resources/tools/clickhouse/clickhouse-sql/) Execute SQL queries as prepared statements in ClickHouse. Requirements ------------ ### Database User This source uses standard ClickHouse authentication. You will need to [create a ClickHouse user](https://clickhouse.com/docs/en/sql-reference/statements/create/user) (or with [ClickHouse Cloud](https://clickhouse.com/docs/getting-started/quick-start/cloud#connect-with-your-app) ) to connect to the database with. The user should have appropriate permissions for the operations you plan to perform. ### Network Access ClickHouse supports multiple protocols: * **HTTPS protocol** (default port 8443) - Secure HTTP access (default) * **HTTP protocol** (default port 8123) - Good for web-based access Example ------- ### Secure Connection Example sources: secure-clickhouse-source: kind: clickhouse host: clickhouse.example.com port: "8443" database: analytics user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} protocol: https secure: true ### HTTP Protocol Example sources: http-clickhouse-source: kind: clickhouse host: localhost port: "8123" database: logs user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} protocol: http secure: false Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “clickhouse”. | | host | string | true | IP address or hostname to connect to (e.g. “127.0.0.1” or “clickhouse.example.com”) | | port | string | true | Port to connect to (e.g. “8443” for HTTPS, “8123” for HTTP) | | database | string | true | Name of the ClickHouse database to connect to (e.g. “my\_database”). | | user | string | true | Name of the ClickHouse user to connect as (e.g. “analytics\_user”). | | password | string | false | Password of the ClickHouse user (e.g. “my-password”). | | protocol | string | false | Connection protocol: “https” (default) or “http”. | | secure | boolean | false | Whether to use a secure connection (TLS). Default: false. | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Connect via MCP Client | MCP Toolbox for Databases Connect via MCP Client ====================== How to connect to Toolbox from a MCP Client. Toolbox SDKs vs Model Context Protocol (MCP) -------------------------------------------- Toolbox now supports connections via both the native Toolbox SDKs and via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) . However, Toolbox has several features which are not supported in the MCP specification (such as Authenticated Parameters and Authorized invocation). We recommend using the native SDKs over MCP clients to leverage these features. The native SDKs can be combined with MCP clients in many cases. ### Protocol Versions Toolbox currently supports the following versions of MCP specification: * [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) * [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) * [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26) * [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05) ### Toolbox AuthZ/AuthN Not Supported by MCP The auth implementation in Toolbox is not supported in MCP’s auth specification. This includes: * [Authenticated Parameters](https://mcp-toolbox.dev/v0.28.0/resources/tools/#authenticated-parameters) * [Authorized Invocations](https://mcp-toolbox.dev/v0.28.0/resources/tools/#authorized-invocations) Connecting to Toolbox with an MCP client ---------------------------------------- ### Before you begin Note MCP is only compatible with Toolbox version 0.3.0 and above. 1. [Install](https://mcp-toolbox.dev/v0.28.0/getting-started/introduction/#installing-the-server) Toolbox version 0.3.0+. 2. Make sure you’ve set up and initialized your database. 3. [Set up](https://mcp-toolbox.dev/v0.28.0/getting-started/configure/) your `tools.yaml` file. ### Connecting via Standard Input/Output (stdio) Toolbox supports the [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) transport protocol. Users that wish to use stdio will have to include the `--stdio` flag when running Toolbox. ./toolbox --stdio When running with stdio, Toolbox will listen via stdio instead of acting as a remote HTTP server. Logs will be set to the `warn` level by default. `debug` and `info` logs are not supported with stdio. Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. ### Connecting via HTTP Toolbox supports the HTTP transport protocol with and without SSE. * HTTP with SSE (deprecated) * Streamable HTTP Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "sse", "url": "http://127.0.0.1:5000/mcp/sse", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}/sse"`. HTTP with SSE is only supported in version `2024-11-05` and is currently deprecated. Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "http", "url": "http://127.0.0.1:5000/mcp", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}"`. ### Using the MCP Inspector with Toolbox Use MCP [Inspector](https://github.com/modelcontextprotocol/inspector) for testing and debugging Toolbox server. * STDIO * HTTP with SSE (deprecated) * Streamable HTTP 1. Run Inspector with Toolbox as a subprocess: npx @modelcontextprotocol/inspector ./toolbox --stdio 2. For `Transport Type` dropdown menu, select `STDIO`. 3. In `Command`, make sure that it is set to :`./toolbox` (or the correct path to where the Toolbox binary is installed). 4. In `Arguments`, make sure that it’s filled with `--stdio`. 5. Click the `Connect` button. It might take awhile to spin up Toolbox. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.28.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `SSE`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp/sse` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}/sse` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.28.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `Streamable HTTP`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! ### Tested Clients | Client | SSE Works | MCP Config Docs | | --- | --- | --- | | Claude Desktop | ✅ | [https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop](https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop) | | MCP Inspector | ✅ | [https://github.com/modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) | | Cursor | ✅ | [https://docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol) | | Windsurf | ✅ | [https://docs.windsurf.com/windsurf/mcp](https://docs.windsurf.com/windsurf/mcp) | | VS Code (Insiders) | ✅ | [https://code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Last modified January 15, 2026: [feat: add new v20251125 version (#2303) (4d23a3bbf27)](https://github.com/googleapis/genai-toolbox/commit/4d23a3bbf2797b1f7fe328aeb5789e778121da23) --- # BigQuery | MCP Toolbox for Databases BigQuery ======== BigQuery is Google Cloud’s fully managed, petabyte-scale, and cost-effective analytics data warehouse that lets you run analytics over vast amounts of data in near real time. With BigQuery, there’s no infrastructure to set up or manage, letting you focus on finding meaningful insights using GoogleSQL and taking advantage of flexible pricing models across on-demand and flat-rate options. BigQuery Source =============== [BigQuery](https://cloud.google.com/bigquery/docs) is Google Cloud’s fully managed, petabyte-scale, and cost-effective analytics data warehouse that lets you run analytics over vast amounts of data in near real time. With BigQuery, there’s no infrastructure to set up or manage, letting you focus on finding meaningful insights using GoogleSQL and taking advantage of flexible pricing models across on-demand and flat-rate options. If you are new to BigQuery, you can try to [load and query data with the bq tool](https://cloud.google.com/bigquery/docs/quickstarts/quickstart-command-line) . BigQuery uses [GoogleSQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/) for querying data. GoogleSQL is an ANSI-compliant structured query language (SQL) that is also implemented for other Google Cloud services. SQL queries are handled by cluster nodes in the same way as NoSQL data requests. Therefore, the same best practices apply when creating SQL queries to run against your BigQuery data, such as avoiding full table scans or complex filters. Available Tools --------------- * [`bigquery-analyze-contribution`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-analyze-contribution/) Performs contribution analysis, also called key driver analysis in BigQuery. * [`bigquery-conversational-analytics`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-conversational-analytics/) Allows conversational interaction with a BigQuery source. * [`bigquery-execute-sql`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-execute-sql/) Execute structured queries using parameters. * [`bigquery-forecast`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-forecast/) Forecasts time series data in BigQuery. * [`bigquery-get-dataset-info`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-get-dataset-info/) Retrieve metadata for a specific dataset. * [`bigquery-get-table-info`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-get-table-info/) Retrieve metadata for a specific table. * [`bigquery-list-dataset-ids`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-list-dataset-ids/) List available dataset IDs. * [`bigquery-list-table-ids`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-list-table-ids/) List tables in a given dataset. * [`bigquery-sql`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-sql/) Run SQL queries directly against BigQuery datasets. * [`bigquery-search-catalog`](https://mcp-toolbox.dev/v0.24.0/resources/tools/bigquery/bigquery-search-catalog/) List all entries in Dataplex Catalog (e.g. tables, views, models) that matches given user query. ### Pre-built Configurations * [BigQuery using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. Requirements ------------ ### IAM Permissions BigQuery uses [Identity and Access Management (IAM)](https://cloud.google.com/bigquery/docs/access-control) to control user and group access to BigQuery resources like projects, datasets, and tables. ### Authentication via Application Default Credentials (ADC) By **default**, Toolbox will use your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize and authenticate when interacting with [BigQuery](https://cloud.google.com/bigquery/docs) . When using this method, you need to ensure the IAM identity associated with your ADC (such as a service account) has the correct permissions for the queries you intend to run. Common roles include `roles/bigquery.user` (which includes permissions to run jobs and read data) or `roles/bigbigquery.dataViewer`. Follow this [guide](https://cloud.google.com/docs/authentication/provide-credentials-adc) to set up your ADC. ### Authentication via User’s OAuth Access Token If the `useClientOAuth` parameter is set to `true`, Toolbox will instead use the OAuth access token for authentication. This token is parsed from the `Authorization` header passed in with the tool invocation request. This method allows Toolbox to make queries to [BigQuery](https://cloud.google.com/bigquery/docs) on behalf of the client or the end-user. When using this on-behalf-of authentication, you must ensure that the identity used has been granted the correct IAM permissions. Example ------- Initialize a BigQuery source that uses ADC: sources: my-bigquery-source: kind: "bigquery" project: "my-project-id" # location: "US" # Optional: Specifies the location for query jobs. # writeMode: "allowed" # One of: allowed, blocked, protected. Defaults to "allowed". # allowedDatasets: # Optional: Restricts tool access to a specific list of datasets. # - "my_dataset_1" # - "other_project.my_dataset_2" # impersonateServiceAccount: "[email protected]" # Optional: Service account to impersonate Initialize a BigQuery source that uses the client’s access token: sources: my-bigquery-client-auth-source: kind: "bigquery" project: "my-project-id" useClientOAuth: true # location: "US" # Optional: Specifies the location for query jobs. # writeMode: "allowed" # One of: allowed, blocked, protected. Defaults to "allowed". # allowedDatasets: # Optional: Restricts tool access to a specific list of datasets. # - "my_dataset_1" # - "other_project.my_dataset_2" # impersonateServiceAccount: "[email protected]" # Optional: Service account to impersonate Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “bigquery”. | | project | string | true | Id of the Google Cloud project to use for billing and as the default project for BigQuery resources. | | location | string | false | Specifies the location (e.g., ‘us’, ‘asia-northeast1’) in which to run the query job. This location must match the location of any tables referenced in the query. Defaults to the table’s location or ‘US’ if the location cannot be determined. [Learn More](https://cloud.google.com/bigquery/docs/locations) | | writeMode | string | false | Controls the write behavior for tools. `allowed` (default): All queries are permitted. `blocked`: Only `SELECT` statements are allowed for the `bigquery-execute-sql` tool. `protected`: Enables session-based execution where all tools associated with this source instance share the same [BigQuery session](https://cloud.google.com/bigquery/docs/sessions-intro)
. This allows for stateful operations using temporary tables (e.g., `CREATE TEMP TABLE`). For `bigquery-execute-sql`, `SELECT` statements can be used on all tables, but write operations are restricted to the session’s temporary dataset. For tools like `bigquery-sql`, `bigquery-forecast`, and `bigquery-analyze-contribution`, the `writeMode` restrictions do not apply, but they will operate within the shared session. **Note:** The `protected` mode cannot be used with `useClientOAuth: true`. It is also not recommended for multi-user server environments, as all users would share the same session. A session is terminated automatically after 24 hours of inactivity or after 7 days, whichever comes first. A new session is created on the next request, and any temporary data from the previous session will be lost. | | allowedDatasets | \[\]string | false | An optional list of dataset IDs that tools using this source are allowed to access. If provided, any tool operation attempting to access a dataset not in this list will be rejected. To enforce this, two types of operations are also disallowed: 1) Dataset-level operations (e.g., `CREATE SCHEMA`), and 2) operations where table access cannot be statically analyzed (e.g., `EXECUTE IMMEDIATE`, `CREATE PROCEDURE`). If a single dataset is provided, it will be treated as the default for prebuilt tools. | | useClientOAuth | bool | false | If true, forwards the client’s OAuth access token from the “Authorization” header to downstream queries. **Note:** This cannot be used with `writeMode: protected`. | | impersonateServiceAccount | string | false | Service account email to impersonate when making BigQuery and Dataplex API calls. The authenticated principal must have the `roles/iam.serviceAccountTokenCreator` role on the target service account. [Learn More](https://cloud.google.com/iam/docs/service-account-impersonation) | Last modified October 31, 2025: [feat(source/bigquery): add service account impersonation support for bigquery (#1641) (e09d182f88b)](https://github.com/googleapis/genai-toolbox/commit/e09d182f88bf697a169428f477aebc9f1741e35f) --- # Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server Admin using MCP ======================================== Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for SQL Server instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.28.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for SQL Server using MCP. The `cloud-sql-mssql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for SQL Server instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for SQL Server instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Resources | MCP Toolbox for Databases Resources ========= List of reference documentation for resources in Toolbox. * * * ##### [AuthServices](https://mcp-toolbox.dev/v0.26.0/resources/authservices/) AuthServices represent services that handle authentication and authorization. ##### [Sources](https://mcp-toolbox.dev/v0.26.0/resources/sources/) Sources represent your different data sources that a tool can interact with. ##### [EmbeddingModels](https://mcp-toolbox.dev/v0.26.0/resources/embeddingmodels/) EmbeddingModels represent services that transform text into vector embeddings for semantic search. ##### [Tools](https://mcp-toolbox.dev/v0.26.0/resources/tools/) Tools define actions an agent can take – such as reading and writing to a source. ##### [Prompts](https://mcp-toolbox.dev/v0.26.0/resources/prompts/) Prompts allow servers to provide structured messages and instructions for interacting with language models. Last modified June 4, 2025: [docs: update llms.txt (#652) (1830702fd89)](https://github.com/googleapis/genai-toolbox/commit/1830702fd8918b9296e6e5c5620ed9e2257573bc) --- # Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for PostgreSQL Admin using MCP ======================================== Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for PostgreSQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for PostgreSQL using MCP. The `cloud-sql-postgres-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for PostgreSQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for PostgreSQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # SQLite using MCP | MCP Toolbox for Databases SQLite using MCP ================ Connect your IDE to SQLite using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQLite. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQLite instance: * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQLite database file.](https://www.sqlite.org/download.html) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.29.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } Use Tools --------- Your AI tool is now connected to SQLite using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 13, 2026: [chore(main): release 0.29.0 (#2608) (39832a0faa6)](https://github.com/googleapis/genai-toolbox/commit/39832a0faa6e967734f4cf2283ec270aa17fc363) --- # Connect via Gemini CLI Extensions | MCP Toolbox for Databases Connect via Gemini CLI Extensions ================================= Connect to Toolbox via Gemini CLI Extensions. Gemini CLI Extensions --------------------- [Gemini CLI](https://google-gemini.github.io/gemini-cli/) is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an agentic interface for interacting with database and analytics services and popular open-source databases. ### How extensions work Gemini CLI is highly extensible, allowing for the addition of new tools and capabilities through extensions. You can load the extensions from a GitHub URL, a local directory, or a configurable registry. They provide new tools, slash commands, and prompts to assist with your workflow. Use the Gemini CLI Extensions to load prebuilt or custom tools to interact with your databases. Below are a list of Gemini CLI Extensions powered by MCP Toolbox: * [alloydb](https://github.com/gemini-cli-extensions/alloydb) * [alloydb-observability](https://github.com/gemini-cli-extensions/alloydb-observability) * [bigquery-conversational-analytics](https://github.com/gemini-cli-extensions/bigquery-conversational-analytics) * [bigquery-data-analytics](https://github.com/gemini-cli-extensions/bigquery-data-analytics) * [cloud-sql-mysql](https://github.com/gemini-cli-extensions/cloud-sql-mysql) * [cloud-sql-mysql-observability](https://github.com/gemini-cli-extensions/cloud-sql-mysql-observability) * [cloud-sql-postgresql](https://github.com/gemini-cli-extensions/cloud-sql-postgresql) * [cloud-sql-postgresql-observability](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability) * [cloud-sql-sqlserver](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver) * [cloud-sql-sqlserver-observability](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability) * [dataplex](https://github.com/gemini-cli-extensions/dataplex) * [firestore-native](https://github.com/gemini-cli-extensions/firestore-native) * [looker](https://github.com/gemini-cli-extensions/looker) * [mcp-toolbox](https://github.com/gemini-cli-extensions/mcp-toolbox) * [mysql](https://github.com/gemini-cli-extensions/mysql) * [postgres](https://github.com/gemini-cli-extensions/postgres) * [spanner](https://github.com/gemini-cli-extensions/spanner) * [sql-server](https://github.com/gemini-cli-extensions/sql-server) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Google Sign-In | MCP Toolbox for Databases Google Sign-In ============== Use Google Sign-In for Oauth 2.0 flow and token lifecycle. Getting Started --------------- Google Sign-In manages the OAuth 2.0 flow and token lifecycle. To integrate the Google Sign-In workflow to your web app [follow this guide](https://developers.google.com/identity/sign-in/web/sign-in) . After setting up the Google Sign-In workflow, you should have registered your application and retrieved a [Client ID](https://developers.google.com/identity/sign-in/web/sign-in#create_authorization_credentials) . Configure your auth service in with the `Client ID`. Behavior -------- ### Authorized Invocations When using [Authorized Invocations](https://mcp-toolbox.dev/v0.25.0/resources/tools/#authorized-invocations) , a tool will be considered authorized if it has a valid Oauth 2.0 token that matches the Client ID. ### Authenticated Parameters When using [Authenticated Parameters](https://mcp-toolbox.dev/v0.25.0/resources/tools/#authenticated-parameters) , any [claim provided by the id-token](https://developers.google.com/identity/openid-connect/openid-connect#obtaininguserprofileinformation) can be used for the parameter. Example ------- authServices: my-google-auth: kind: google clientId: ${YOUR_GOOGLE_CLIENT_ID} Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “google”. | | clientId | string | true | Client ID of your application from registering your application. | Last modified August 15, 2025: [docs: fix typos across docs (#1154) (c65c11af246)](https://github.com/googleapis/genai-toolbox/commit/c65c11af2463009b06c3fc3d5dbdf350bdcd2494) --- # Toolbox UI | MCP Toolbox for Databases Toolbox UI ========== How to effectively use Toolbox UI. Toolbox UI is a built-in web interface that allows users to visually inspect and test out configured resources such as tools and toolsets. Launching Toolbox UI -------------------- To launch Toolbox’s interactive UI, use the `--ui` flag. ./toolbox --ui Toolbox UI will be served from the same host and port as the Toolbox Server, with the `/ui` suffix. Once Toolbox is launched, the following INFO log with Toolbox UI’s url will be shown: INFO "Toolbox UI is up and running at: http://localhost:5000/ui" Navigating the Tools Page ------------------------- The tools page shows all tools loaded from your configuration file. This corresponds to the default toolset (represented by an empty string). Each tool’s name on this page will exactly match its name in the configuration file. To view details for a specific tool, click on the tool name. The main content area will be populated with the tool name, description, and available parameters. ![Tools Page](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/tools.png) ### Invoking a Tool 1. Click on a Tool 2. Enter appropriate parameters in each parameter field 3. Click “Run Tool” 4. Done! Your results will appear in the response field 5. (Optional) Uncheck “Prettify JSON” to format the response as plain text ![Run Tool Demo GIF](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/run-tool.gif) ### Optional Parameters Toolbox allows users to add [optional parameters](https://mcp-toolbox.dev/v0.28.0/resources/tools/#basic-parameters) with or without a default value. To exclude a parameter, uncheck the box to the right of an associated parameter, and that parameter will not be included in the request body. If the parameter is not sent, Toolbox will either use it as `nil` value or the `default` value, if configured. If the parameter is required, Toolbox will throw an error. When the box is checked, parameter will be sent exactly as entered in the response field (e.g. empty string). ![Optional Parameter checked example](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/optional-param-checked.png) ![Optional Parameter unchecked example](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/optional-param-unchecked.png) ### Editing Headers To edit headers, press the “Edit Headers” button to display the header modal. Within this modal, users can make direct edits by typing into the header’s text area. Toolbox UI validates that the headers are in correct JSON format. Other header-related errors (e.g., incorrect header names or values required by the tool) will be reported in the Response section after running the tool. ![Edit Headers](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/edit-headers.png) #### Google OAuth Currently, Toolbox supports Google OAuth 2.0 as an AuthService, which allows tools to utilize authorized parameters. When a tool uses an authorized parameter, the parameter will be displayed but not editable, as it will be populated from the authentication token. To provide the token, add your Google OAuth ID Token to the request header using the “Edit Headers” button and modal described above. The key should be the name of your AuthService as defined in your tool configuration file, suffixed with `_token`. The value should be your ID token as a string. 1. Select a tool that requires [authenticated parameters](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/) 2. The auth parameter’s text field is greyed out. This is because it cannot be entered manually and will be parsed from the resolved auth token 3. To update request headers with the token, select “Edit Headers” 4. (Optional) If you wish to manually edit the header, checkout the dropdown “How to extract Google OAuth ID Token manually” for guidance on retrieving ID token 5. To edit the header automatically, click the “Auto Setup” button that is associated with your Auth Profile 6. Enter the Client ID defined in your tools configuration file 7. Click “Continue” 8. Click “Sign in With Google” and login with your associated google account. This should automatically populate the header text area with your token 9. Click “Save” 10. Click “Run Tool” { "Content-Type": "application/json", "my-google-auth_token": "YOUR_ID_TOKEN_HERE" } ![Using Authenticated Parameter GIF](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/edit-headers.gif) Navigating the Toolsets Page ---------------------------- Through the toolsets page, users can search for a specific toolset to retrieve tools from. Simply enter the toolset name in the search bar, and press “Enter” to retrieve the associated tools. If the toolset name is not defined within the tools configuration file, an error message will be displayed. ![Toolsets Page](https://mcp-toolbox.dev/v0.28.0/how-to/toolbox-ui/toolsets.png) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # AlloyDB Admin | MCP Toolbox for Databases AlloyDB Admin ============= The “alloydb-admin” source provides a client for the AlloyDB API. About ----- The `alloydb-admin` source provides a client to interact with the [Google AlloyDB API](https://cloud.google.com/alloydb/docs/reference/rest) . This allows tools to perform administrative tasks on AlloyDB resources, such as managing clusters, instances, and users. Authentication can be handled in two ways: 1. **Application Default Credentials (ADC):** By default, the source uses ADC to authenticate with the API. 2. **Client-side OAuth:** If `useClientOAuth` is set to `true`, the source will expect an OAuth 2.0 access token to be provided by the client (e.g., a web browser) for each request. Example ------- sources: my-alloydb-admin: kind: alloy-admin my-oauth-alloydb-admin: kind: alloydb-admin useClientOAuth: true Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “alloydb-admin”. | | defaultProject | string | false | The Google Cloud project ID to use for AlloyDB infrastructure tools. | | useClientOAuth | boolean | false | If true, the source will use client-side OAuth for authorization. Otherwise, it will use Application Default Credentials. Defaults to `false`. | Last modified November 11, 2025: [feat(source/alloydb, source/cloud-sql-postgres,source/cloud-sql-mysql,source/cloud-sql-mssql): Use project from env for alloydb and cloud sql control plane tools (#1588) (12bdd954597)](https://github.com/googleapis/genai-toolbox/commit/12bdd954597e49d3ec6b247cc104584c5a4d1943) --- # Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for MySQL Admin using MCP =================================== Create and manage Cloud SQL for MySQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for MySQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for MySQL using MCP. The `cloud-sql-mysql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for MySQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for MySQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Export Telemetry | MCP Toolbox for Databases Export Telemetry ================ How to set up and configure Toolbox to use the Otel Collector. About ----- The [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) offers a vendor-agnostic implementation of how to receive, process and export telemetry data. It removes the need to run, operate, and maintain multiple agents/collectors. Configure the Collector ----------------------- To configure the collector, you will have to provide a configuration file. The configuration file consists of four classes of pipeline component that access telemetry data. * `Receivers` * `Processors` * `Exporters` * `Connectors` Example of setting up the classes of pipeline components (in this example, we don’t use connectors): receivers: otlp: protocols: http: endpoint: "127.0.0.1:4553" exporters: googlecloud: project: processors: batch: send_batch_size: 200 After each pipeline component is configured, you will enable it within the `service` section of the configuration file. service: pipelines: traces: receivers: ["otlp"] processors: ["batch"] exporters: ["googlecloud"] Running the Collector --------------------- There are a couple of steps to run and use a Collector. 1. [Install the Collector](https://opentelemetry.io/docs/collector/installation/) binary. Pull a binary or Docker image for the OpenTelemetry contrib collector. 2. Set up credentials for telemetry backend. 3. Set up the Collector config. Below are some examples for setting up the Collector config: * [Google Cloud Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter) * [Google Managed Service for Prometheus Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter#example-configuration) 4. Run the Collector with the configuration file. ./otelcol-contrib --config=collector-config.yaml 5. Run toolbox with the `--telemetry-otlp` flag. Configure it to send them to `127.0.0.1:4553` (for HTTP) or the Collector’s URL. ./toolbox --telemetry-otlp=127.0.0.1:4553 Tip To pass an insecure endpoint, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. 6. Once telemetry datas are collected, you can view them in your telemetry backend. If you are using GCP exporters, telemetry will be visible in GCP dashboard at [Metrics Explorer](https://console.cloud.google.com/monitoring/metrics-explorer) and [Trace Explorer](https://console.cloud.google.com/traces) . Note If you are exporting to Google Cloud monitoring, we recommend that you use the Google Cloud Exporter for traces and the Google Managed Service for Prometheus Exporter for metrics. Last modified December 18, 2025: [docs: telemetry docs to provide endpoint without scheme or path (#2179) (6e873494314)](https://github.com/googleapis/genai-toolbox/commit/6e8734943147dc919800db98af7987f2302c937d) --- # Deploy using Docker Compose | MCP Toolbox for Databases Deploy using Docker Compose =========================== How to deploy Toolbox using Docker Compose. Before you begin ---------------- 1. [Install Docker Compose.](https://docs.docker.com/compose/install/) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://github.com/googleapis/genai-toolbox/blob/main/README.md#configuration) section. Deploy using Docker Compose --------------------------- 1. Create a `docker-compose.yml` file, customizing as needed: services: toolbox: # TODO: It is recommended to pin to a specific image version instead of latest. image: us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest hostname: toolbox platform: linux/amd64 ports: - "5000:5000" volumes: - ./config:/config command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0"] depends_on: db: condition: service_healthy networks: - tool-network db: # TODO: It is recommended to pin to a specific image version instead of latest. image: postgres hostname: db environment: POSTGRES_USER: toolbox_user POSTGRES_PASSWORD: my-password POSTGRES_DB: toolbox_db ports: - "5432:5432" volumes: - ./db:/var/lib/postgresql/data # This file can be used to bootstrap your schema if needed. # See "initialization scripts" on https://hub.docker.com/_/postgres/ for more info - ./config/init.sql:/docker-entrypoint-initdb.d/init.sql healthcheck: test: ["CMD-SHELL", "pg_isready -U toolbox_user -d toolbox_db"] interval: 10s timeout: 5s retries: 5 networks: - tool-network networks: tool-network: TipTo prevent DNS rebinding attack, use the --allowed-hosts flag to specify a list of hosts for validation. E.g. command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0", "--allowed-hosts", "localhost:5000"] To implement CORs, use the --allowed-origins flag to specify a list of origins permitted to access the server. E.g. command: [ "toolbox", "--tools-file", "/config/tools.yaml", "--address", "0.0.0.0", "--allowed-origins", "https://foo.bar"] 1. Run the following command to bring up the Toolbox and Postgres instance docker-compose up -d Tip You can use this setup to quickly set up Toolbox + Postgres to follow along in our [Quickstart](https://mcp-toolbox.dev/v0.27.0/getting-started/local_quickstart/) Connecting with Toolbox Client SDK ---------------------------------- Next, we will use Toolbox with the Client SDKs: 1. The url for the Toolbox server running using docker-compose will be: http://localhost:5000 2. Import and initialize the client with the URL: * LangChain * Llamaindex from toolbox_langchain import ToolboxClient # Replace with the cloud run service URL generated above async with ToolboxClient("http://$YOUR_URL") as toolbox: from toolbox_llamaindex import ToolboxClient # Replace with the cloud run service URL generated above async with ToolboxClient("http://$YOUR_URL") as toolbox: Last modified January 8, 2026: [feat: add allowed-hosts flag (#2254) (17b41f64531)](https://github.com/googleapis/genai-toolbox/commit/17b41f64531b8fe417c28ada45d1992ba430dc1b) --- # Sources | MCP Toolbox for Databases Sources ======= Sources represent your different data sources that a tool can interact with. A Source represents a data sources that a tool can interact with. You can define Sources as a map in the `sources` section of your `tools.yaml` file. Typically, a source configuration will contain any information needed to connect with and interact with the database. Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-cloud-sql-source: kind: cloud-sql-postgres project: my-project-id region: us-central1 instance: my-instance-name database: my_db user: ${USER_NAME} password: ${PASSWORD} In implementation, each source is a different connection pool or client that used to connect to the database and execute the tool. Available Sources ----------------- * * * ##### [AlloyDB for PostgreSQL](https://mcp-toolbox.dev/v0.25.0/resources/sources/alloydb-pg/) AlloyDB for PostgreSQL is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. ##### [AlloyDB Admin](https://mcp-toolbox.dev/v0.25.0/resources/sources/alloydb-admin/) The “alloydb-admin” source provides a client for the AlloyDB API. ##### [BigQuery](https://mcp-toolbox.dev/v0.25.0/resources/sources/bigquery/) BigQuery is Google Cloud’s fully managed, petabyte-scale, and cost-effective analytics data warehouse that lets you run analytics over vast amounts of data in near real time. With BigQuery, there’s no infrastructure to set up or manage, letting you focus on finding meaningful insights using GoogleSQL and taking advantage of flexible pricing models across on-demand and flat-rate options. ##### [Bigtable](https://mcp-toolbox.dev/v0.25.0/resources/sources/bigtable/) Bigtable is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. ##### [Cassandra](https://mcp-toolbox.dev/v0.25.0/resources/sources/cassandra/) Apache Cassandra is a NoSQL distributed database known for its horizontal scalability, distributed architecture, and flexible schema definition. ##### [ClickHouse](https://mcp-toolbox.dev/v0.25.0/resources/sources/clickhouse/) ClickHouse is an open-source, OLTP database. ##### [Cloud Healthcare API](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-healthcare/) The Cloud Healthcare API provides a managed solution for storing and accessing healthcare data in Google Cloud, providing a critical bridge between existing care systems and applications hosted on Google Cloud. ##### [Cloud Monitoring](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-monitoring/) A “cloud-monitoring” source provides a client for the Cloud Monitoring API. ##### [Cloud SQL for MySQL](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-sql-mysql/) Cloud SQL for MySQL is a fully-managed database service for MySQL. ##### [Cloud SQL for PostgreSQL](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-sql-pg/) Cloud SQL for PostgreSQL is a fully-managed database service for Postgres. ##### [Cloud SQL for SQL Server](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-sql-mssql/) Cloud SQL for SQL Server is a fully-managed database service for SQL Server. ##### [Cloud SQL Admin](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-sql-admin/) A “cloud-sql-admin” source provides a client for the Cloud SQL Admin API. ##### [Couchbase](https://mcp-toolbox.dev/v0.25.0/resources/sources/couchbase/) A “couchbase” source connects to a Couchbase database. ##### [Dataplex](https://mcp-toolbox.dev/v0.25.0/resources/sources/dataplex/) Dataplex Universal Catalog is a unified, intelligent governance solution for data and AI assets in Google Cloud. Dataplex Universal Catalog powers AI, analytics, and business intelligence at scale. ##### [Dgraph](https://mcp-toolbox.dev/v0.25.0/resources/sources/dgraph/) Dgraph is fully open-source, built-for-scale graph database for Gen AI workloads ##### [Elasticsearch](https://mcp-toolbox.dev/v0.25.0/resources/sources/elasticsearch/) Elasticsearch is a distributed, free and open search and analytics engine for all types of data, including textual, numerical, geospatial, structured, and unstructured. ##### [Firebird](https://mcp-toolbox.dev/v0.25.0/resources/sources/firebird/) Firebird is a powerful, cross-platform, and open-source relational database. ##### [Firestore](https://mcp-toolbox.dev/v0.25.0/resources/sources/firestore/) Firestore is a NoSQL document database built for automatic scaling, high performance, and ease of application development. It’s a fully managed, serverless database that supports mobile, web, and server development. ##### [Gemini Data Analytics](https://mcp-toolbox.dev/v0.25.0/resources/sources/cloud-gda/) A “cloud-gemini-data-analytics” source provides a client for the Gemini Data Analytics API. ##### [HTTP](https://mcp-toolbox.dev/v0.25.0/resources/sources/http/) The HTTP source enables the Toolbox to retrieve data from a remote server using HTTP requests. ##### [Looker](https://mcp-toolbox.dev/v0.25.0/resources/sources/looker/) Looker is a business intelligence tool that also provides a semantic layer. ##### [MariaDB](https://mcp-toolbox.dev/v0.25.0/resources/sources/mariadb/) MariaDB is an open-source relational database compatible with MySQL. ##### [MindsDB](https://mcp-toolbox.dev/v0.25.0/resources/sources/mindsdb/) MindsDB is an AI federated database that enables SQL queries across hundreds of datasources and ML models. ##### [MongoDB](https://mcp-toolbox.dev/v0.25.0/resources/sources/mongodb/) MongoDB is a no-sql data platform that can not only serve general purpose data requirements also perform VectorSearch where both operational data and embeddings used of search can reside in same document. ##### [MySQL](https://mcp-toolbox.dev/v0.25.0/resources/sources/mysql/) MySQL is a relational database management system that stores and manages data. ##### [Neo4j](https://mcp-toolbox.dev/v0.25.0/resources/sources/neo4j/) Neo4j is a powerful, open source graph database system ##### [OceanBase](https://mcp-toolbox.dev/v0.25.0/resources/sources/oceanbase/) OceanBase is a distributed relational database that provides high availability, scalability, and compatibility with MySQL. ##### [Oracle](https://mcp-toolbox.dev/v0.25.0/resources/sources/oracle/) Oracle Database is a widely-used relational database management system. ##### [PostgreSQL](https://mcp-toolbox.dev/v0.25.0/resources/sources/postgres/) PostgreSQL is a powerful, open source object-relational database. ##### [Redis](https://mcp-toolbox.dev/v0.25.0/resources/sources/redis/) Redis is a in-memory data structure store. ##### [Serverless for Apache Spark](https://mcp-toolbox.dev/v0.25.0/resources/sources/serverless-spark/) Google Cloud Serverless for Apache Spark lets you run Spark workloads without requiring you to provision and manage your own Spark cluster. ##### [SingleStore](https://mcp-toolbox.dev/v0.25.0/resources/sources/singlestore/) SingleStore is the cloud-native database built with speed and scale to power data-intensive applications. ##### [Snowflake](https://mcp-toolbox.dev/v0.25.0/resources/sources/snowflake/) Snowflake is a cloud-based data platform. ##### [Spanner](https://mcp-toolbox.dev/v0.25.0/resources/sources/spanner/) Spanner is a fully managed database service from Google Cloud that combines relational, key-value, graph, and search capabilities. ##### [SQL Server](https://mcp-toolbox.dev/v0.25.0/resources/sources/mssql/) SQL Server is a relational database management system (RDBMS). ##### [SQLite](https://mcp-toolbox.dev/v0.25.0/resources/sources/sqlite/) SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. ##### [TiDB](https://mcp-toolbox.dev/v0.25.0/resources/sources/tidb/) TiDB is a distributed SQL database that combines the best of traditional RDBMS and NoSQL databases. ##### [Trino](https://mcp-toolbox.dev/v0.25.0/resources/sources/trino/) Trino is a distributed SQL query engine for big data analytics. ##### [Valkey](https://mcp-toolbox.dev/v0.25.0/resources/sources/valkey/) Valkey is an open-source, in-memory data structure store, forked from Redis. ##### [YugabyteDB](https://mcp-toolbox.dev/v0.25.0/resources/sources/yugabytedb/) YugabyteDB is a high-performance, distributed SQL database. Last modified April 23, 2025: [feat: Support env replacement for tool.yaml (#462) (eadb678a7bd)](https://github.com/googleapis/genai-toolbox/commit/eadb678a7bd4ce74a3b1160f5ed8966ffbb13c61) --- # Bigtable | MCP Toolbox for Databases Bigtable ======== Bigtable is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. Bigtable Source =============== [Bigtable](https://cloud.google.com/bigtable/docs) is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. If you are new to Bigtable, you can try to [create an instance and write data with the cbt CLI](https://cloud.google.com/bigtable/docs/create-instance-write-data-cbt-cli) . You can use [GoogleSQL statements](https://cloud.google.com/bigtable/docs/googlesql-overview) to query your Bigtable data. GoogleSQL is an ANSI-compliant structured query language (SQL) that is also implemented for other Google Cloud services. SQL queries are handled by cluster nodes in the same way as NoSQL data requests. Therefore, the same best practices apply when creating SQL queries to run against your Bigtable data, such as avoiding full table scans or complex filters. Available Tools --------------- * [`bigtable-sql`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigtable/bigtable-sql/) Run SQL-like queries over Bigtable rows. Requirements ------------ ### IAM Permissions Bigtable uses [Identity and Access Management (IAM)](https://cloud.google.com/bigtable/docs/access-control) to control user and group access to Bigtable resources at the project, instance, table, and backup level. Toolbox will use your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize and authenticate when interacting with [Bigtable](https://cloud.google.com/bigtable/docs) . In addition to [setting the ADC for your server](https://cloud.google.com/docs/authentication/provide-credentials-adc) , you need to ensure the IAM identity has been given the correct IAM permissions for the query provided. See [Apply IAM roles](https://cloud.google.com/bigtable/docs/access-control#iam-management-instance) for more information on applying IAM permissions and roles to an identity. Example ------- sources: my-bigtable-source: kind: "bigtable" project: "my-project-id" instance: "test-instance" Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “bigtable”. | | project | string | true | Id of the GCP project that the cluster was created in (e.g. “my-project-id”). | | instance | string | true | Name of the Bigtable instance. | Last modified July 22, 2025: [docs: add available tools for each source (#914) (a1def43b350)](https://github.com/googleapis/genai-toolbox/commit/a1def43b3502e90aacdfee669010ea29e0558452) --- # Connect via MCP Client | MCP Toolbox for Databases Connect via MCP Client ====================== How to connect to Toolbox from a MCP Client. Toolbox SDKs vs Model Context Protocol (MCP) -------------------------------------------- Toolbox now supports connections via both the native Toolbox SDKs and via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) . However, Toolbox has several features which are not supported in the MCP specification (such as Authenticated Parameters and Authorized invocation). We recommend using the native SDKs over MCP clients to leverage these features. The native SDKs can be combined with MCP clients in many cases. ### Protocol Versions Toolbox currently supports the following versions of MCP specification: * [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) * [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) * [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26) * [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05) ### Toolbox AuthZ/AuthN Not Supported by MCP The auth implementation in Toolbox is not supported in MCP’s auth specification. This includes: * [Authenticated Parameters](https://mcp-toolbox.dev/v0.29.0/resources/tools/#authenticated-parameters) * [Authorized Invocations](https://mcp-toolbox.dev/v0.29.0/resources/tools/#authorized-invocations) Connecting to Toolbox with an MCP client ---------------------------------------- ### Before you begin Note MCP is only compatible with Toolbox version 0.3.0 and above. 1. [Install](https://mcp-toolbox.dev/v0.29.0/getting-started/introduction/#installing-the-server) Toolbox version 0.3.0+. 2. Make sure you’ve set up and initialized your database. 3. [Set up](https://mcp-toolbox.dev/v0.29.0/getting-started/configure/) your `tools.yaml` file. ### Connecting via Standard Input/Output (stdio) Toolbox supports the [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) transport protocol. Users that wish to use stdio will have to include the `--stdio` flag when running Toolbox. ./toolbox --stdio When running with stdio, Toolbox will listen via stdio instead of acting as a remote HTTP server. Logs will be set to the `warn` level by default. `debug` and `info` logs are not supported with stdio. Note Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. ### Connecting via HTTP Toolbox supports the HTTP transport protocol with and without SSE. * HTTP with SSE (deprecated) * Streamable HTTP Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "sse", "url": "http://127.0.0.1:5000/mcp/sse", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}/sse"`. HTTP with SSE is only supported in version `2024-11-05` and is currently deprecated. Add the following configuration to your MCP client configuration: { "mcpServers": { "toolbox": { "type": "http", "url": "http://127.0.0.1:5000/mcp", } } } If you would like to connect to a specific toolset, replace `url` with `"http://127.0.0.1:5000/mcp/{toolset_name}"`. ### Using the MCP Inspector with Toolbox Use MCP [Inspector](https://github.com/modelcontextprotocol/inspector) for testing and debugging Toolbox server. * STDIO * HTTP with SSE (deprecated) * Streamable HTTP 1. Run Inspector with Toolbox as a subprocess: npx @modelcontextprotocol/inspector ./toolbox --stdio 2. For `Transport Type` dropdown menu, select `STDIO`. 3. In `Command`, make sure that it is set to :`./toolbox` (or the correct path to where the Toolbox binary is installed). 4. In `Arguments`, make sure that it’s filled with `--stdio`. 5. Click the `Connect` button. It might take awhile to spin up Toolbox. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.29.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `SSE`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp/sse` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}/sse` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! 1. [Run Toolbox](https://mcp-toolbox.dev/v0.29.0/getting-started/introduction/#running-the-server) . 2. In a separate terminal, run Inspector directly through `npx`: npx @modelcontextprotocol/inspector 3. For `Transport Type` dropdown menu, select `Streamable HTTP`. 4. For `URL`, type in `http://127.0.0.1:5000/mcp` to use all tool or `http//127.0.0.1:5000/mcp/{toolset_name}` to use a specific toolset. 5. Click the `Connect` button. Voila! You should be able to inspect your toolbox tools! ### Tested Clients | Client | SSE Works | MCP Config Docs | | --- | --- | --- | | Claude Desktop | ✅ | [https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop](https://modelcontextprotocol.io/quickstart/user#1-download-claude-for-desktop) | | MCP Inspector | ✅ | [https://github.com/modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) | | Cursor | ✅ | [https://docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol) | | Windsurf | ✅ | [https://docs.windsurf.com/windsurf/cascade/mcp#model-context-protocol-mcp](https://docs.windsurf.com/windsurf/cascade/mcp#model-context-protocol-mcp) | | VS Code (Insiders) | ✅ | [https://code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Last modified March 10, 2026: [docs: fix links (#2612) (63d448d4282)](https://github.com/googleapis/genai-toolbox/commit/63d448d42826246e09da49f43f13028724d8c81b) --- # AuthServices | MCP Toolbox for Databases AuthServices ============ AuthServices represent services that handle authentication and authorization. AuthServices represent services that handle authentication and authorization. It can primarily be used by [Tools](https://mcp-toolbox.dev/v0.25.0/resources/tools/) in two different ways: * [**Authorized Invocation**](https://mcp-toolbox.dev/v0.25.0/resources/tools/#authorized-invocations) is when a tool is validated by the auth service before the call can be invoked. Toolbox will reject any calls that fail to validate or have an invalid token. * [**Authenticated Parameters**](https://mcp-toolbox.dev/v0.25.0/resources/tools/#authenticated-parameters) replace the value of a parameter with a field from an [OIDC](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) claim. Toolbox will automatically resolve the ID token provided by the client and replace the parameter in the tool call. Example ------- The following configurations are placed at the top level of a `tools.yaml` file. Tip If you are accessing Toolbox with multiple applications, each application should register their own Client ID even if they use the same “kind” of auth provider. authServices: my_auth_app_1: kind: google clientId: ${YOUR_CLIENT_ID_1} my_auth_app_2: kind: google clientId: ${YOUR_CLIENT_ID_2} Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. After you’ve configured an `authService` you’ll, need to reference it in the configuration for each tool that should use it: * **Authorized Invocations** for authorizing a tool call, [use the `authRequired` field in a tool config](https://mcp-toolbox.dev/v0.25.0/resources/tools/#authorized-invocations) * **Authenticated Parameters** for using the value from a OIDC claim, [use the `authServices` field in a parameter config](https://mcp-toolbox.dev/v0.25.0/resources/tools/#authenticated-parameters) Specifying ID Tokens from Clients --------------------------------- After [configuring](https://mcp-toolbox.dev/v0.25.0/resources/authservices/#example) your `authServices` section, use a Toolbox SDK to add your ID tokens to the header of a Tool invocation request. When specifying a token you will provide a function (that returns an id). This function is called when the tool is invoked. This allows you to cache and refresh the ID token as needed. The primary method for providing these getters is via the `auth_token_getters` parameter when loading tools, or the `add_auth_token_getter`() / `add_auth_token_getters()` methods on a loaded tool object. ### Specifying tokens during load #### Python Use the [Python SDK](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main) . * Core * LangChain * Llamaindex import asyncio from toolbox_core import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): async with ToolboxClient("") as toolbox: auth_tool = await toolbox.load_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) result = await auth_tool(param="value") print(result) if **name** == "**main**": asyncio.run(main()) import asyncio from toolbox_langchain import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): toolbox = ToolboxClient("") auth_tool = await toolbox.aload_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) result = await auth_tool.ainvoke({"param": "value"}) print(result) if **name** == "**main**": asyncio.run(main()) import asyncio from toolbox_llamaindex import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): toolbox = ToolboxClient("") auth_tool = await toolbox.aload_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) # result = await auth_tool.acall(param="value") # print(result.content) if **name** == "**main**": asyncio.run(main()) #### Javascript/Typescript Use the [JS SDK](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main) . import { ToolboxClient } from '@toolbox-sdk/core'; async function getAuthToken() { // ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) // This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" // Placeholder } const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const authTool = await client.loadTool("my-tool", {"my_auth_app_1": getAuthToken}); const result = await authTool({param:"value"}); console.log(result); print(result) #### Go Use the [Go SDK](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main) . import "github.com/googleapis/mcp-toolbox-sdk-go/core" import "fmt" func getAuthToken() string { // ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) // This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" // Placeholder } func main() { URL := 'http://127.0.0.1:5000' client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } dynamicTokenSource := core.NewCustomTokenSource(getAuthToken) authTool, err := client.LoadTool( "my-tool", ctx, core.WithAuthTokenSource("my_auth_app_1", dynamicTokenSource)) if err != nil { log.Fatalf("Failed to load tool: %v", err) } inputs := map[string]any{"param": "value"} result, err := authTool.Invoke(ctx, inputs) if err != nil { log.Fatalf("Failed to invoke tool: %v", err) } fmt.Println(result) } ### Specifying tokens for existing tools #### Python Use the [Python SDK](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main) . * Core * LangChain * Llamaindex tools = await toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) tools = toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) tools = toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) #### Javascript/Typescript Use the [JS SDK](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main) . const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); let tool = await client.loadTool("my-tool") // for a single token const authorizedTool = tool.addAuthTokenGetter("my_auth", get_auth_token) // OR, if multiple tokens are needed const multiAuthTool = tool.addAuthTokenGetters({ "my_auth_1": getAuthToken1, "my_auth_2": getAuthToken2, }) #### Go Use the [Go SDK](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main) . import "github.com/googleapis/mcp-toolbox-sdk-go/core" func main() { URL := 'http://127.0.0.1:5000' client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } tool, err := client.LoadTool("my-tool", ctx)) if err != nil { log.Fatalf("Failed to load tool: %v", err) } dynamicTokenSource1 := core.NewCustomTokenSource(getAuthToken1) dynamicTokenSource2 := core.NewCustomTokenSource(getAuthToken1) // For a single token authTool, err := tool.ToolFrom( core.WithAuthTokenSource("my-auth", dynamicTokenSource), ) // OR, if multiple tokens are needed authTool, err := tool.ToolFrom( core.WithAuthTokenSource("my-auth_1", dynamicTokenSource1), core.WithAuthTokenSource("my-auth_2", dynamicTokenSource2), ) } Kinds of Auth Services ---------------------- * * * ##### [Google Sign-In](https://mcp-toolbox.dev/v0.25.0/resources/authservices/google/) Use Google Sign-In for Oauth 2.0 flow and token lifecycle. Last modified September 18, 2025: [docs: fix docs linting (#1520) (3d8a041782d)](https://github.com/googleapis/genai-toolbox/commit/3d8a041782db4ec94d25f1e96d69cb9e5941e9e6) --- # AlloyDB for PostgreSQL | MCP Toolbox for Databases AlloyDB for PostgreSQL ====================== AlloyDB for PostgreSQL is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. About ----- [AlloyDB for PostgreSQL](https://cloud.google.com/alloydb/docs) is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. It provides enterprise-grade performance and availability while maintaining 100% compatibility with open-source PostgreSQL. If you are new to AlloyDB for PostgreSQL, you can [create a free trial cluster](https://cloud.google.com/alloydb/docs/create-free-trial-cluster) . Available Tools --------------- * [`alloydb-ai-nl`](https://mcp-toolbox.dev/v0.25.0/resources/tools/alloydbainl/alloydb-ai-nl/) Use natural language queries on AlloyDB, powered by AlloyDB AI. * [`postgres-sql`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-sql/) Execute SQL queries as prepared statements in AlloyDB Postgres. * [`postgres-execute-sql`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-execute-sql/) Run parameterized SQL statements in AlloyDB Postgres. * [`postgres-list-tables`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-tables/) List tables in an AlloyDB for PostgreSQL database. * [`postgres-list-active-queries`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-active-queries/) List active queries in an AlloyDB for PostgreSQL database. * [`postgres-list-available-extensions`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-available-extensions/) List available extensions for installation in a PostgreSQL database. * [`postgres-list-installed-extensions`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-installed-extensions/) List installed extensions in a PostgreSQL database. * [`postgres-list-views`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-views/) List views in an AlloyDB for PostgreSQL database. * [`postgres-list-schemas`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-schemas/) List schemas in an AlloyDB for PostgreSQL database. * [`postgres-database-overview`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-database-overview/) Fetches the current state of the PostgreSQL server. * [`postgres-list-triggers`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-triggers/) List triggers in an AlloyDB for PostgreSQL database. * [`postgres-list-indexes`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-indexes/) List available user indexes in a PostgreSQL database. * [`postgres-list-sequences`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-sequences/) List sequences in a PostgreSQL database. * [`postgres-long-running-transactions`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-long-running-transactions/) List long running transactions in a PostgreSQL database. * [`postgres-list-locks`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-locks/) List lock stats in a PostgreSQL database. * [`postgres-replication-stats`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-replication-stats/) List replication stats in a PostgreSQL database. * [`postgres-list-query-stats`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-query-stats/) List query statistics in a PostgreSQL database. * [`postgres-get-column-cardinality`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-get-column-cardinality/) List cardinality of columns in a table in a PostgreSQL database. * [`postgres-list-table-stats`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-table-stats/) List statistics of a table in a PostgreSQL database. * [`postgres-list-publication-tables`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-publication-tables/) List publication tables in a PostgreSQL database. * [`postgres-list-tablespaces`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-tablespaces/) List tablespaces in an AlloyDB for PostgreSQL database. * [`postgres-list-pg-settings`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-pg-settings/) List configuration parameters for the PostgreSQL server. * [`postgres-list-database-stats`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-database-stats/) Lists the key performance and activity statistics for each database in the AlloyDB instance. * [`postgres-list-roles`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-roles/) Lists all the user-created roles in PostgreSQL database. * [`postgres-list-stored-procedure`](https://mcp-toolbox.dev/v0.25.0/resources/tools/postgres/postgres-list-stored-procedure/) Lists all the stored procedure in PostgreSQL database. ### Pre-built Configurations * [AlloyDB using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. * [AlloyDB Admin API using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. Requirements ------------ ### IAM Permissions By default, AlloyDB for PostgreSQL source uses the [AlloyDB Go Connector](https://github.com/GoogleCloudPlatform/alloydb-go-connector) to authorize and establish mTLS connections to your AlloyDB instance. The Go connector uses your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize your connection to AlloyDB. In addition to [setting the ADC for your server](https://cloud.google.com/docs/authentication/provide-credentials-adc) , you need to ensure the IAM identity has been given the following IAM roles (or corresponding permissions): * `roles/alloydb.client` * `roles/serviceusage.serviceUsageConsumer` ### Networking AlloyDB supports connecting over both from external networks via the internet ([public IP](https://cloud.google.com/alloydb/docs/connect-public-ip) ), and internal networks ([private IP](https://cloud.google.com/alloydb/docs/private-ip) ). For more information on choosing between the two options, see the AlloyDB page [Connection overview](https://cloud.google.com/alloydb/docs/connection-overview) . You can configure the `ipType` parameter in your source configuration to `public` or `private` to match your cluster’s configuration. Regardless of which you choose, all connections use IAM-based authorization and are encrypted with mTLS. ### Authentication This source supports both password-based authentication and IAM authentication (using your [Application Default Credentials](https://cloud.google.com/docs/authentication#adc) ). #### Standard Authentication To connect using user/password, [create a PostgreSQL user](https://cloud.google.com/alloydb/docs/database-users/about) and input your credentials in the `user` and `password` fields. user: ${USER_NAME} password: ${PASSWORD} #### IAM Authentication To connect using IAM authentication: 1. Prepare your database instance and user following this [guide](https://cloud.google.com/alloydb/docs/database-users/manage-iam-auth) . 2. You could choose one of the two ways to log in: * Specify your IAM email as the `user`. * Leave your `user` field blank. Toolbox will fetch the [ADC](https://cloud.google.com/docs/authentication#adc) automatically and log in using the email associated with it. 3. Leave the `password` field blank. Example ------- sources: my-alloydb-pg-source: kind: alloydb-postgres project: my-project-id region: us-central1 cluster: my-cluster instance: my-instance database: my_db user: ${USER_NAME} password: ${PASSWORD} # ipType: "public" Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “alloydb-postgres”. | | project | string | true | Id of the GCP project that the cluster was created in (e.g. “my-project-id”). | | region | string | true | Name of the GCP region that the cluster was created in (e.g. “us-central1”). | | cluster | string | true | Name of the AlloyDB cluster (e.g. “my-cluster”). | | instance | string | true | Name of the AlloyDB instance within the cluster (e.g. “my-instance”). | | database | string | true | Name of the Postgres database to connect to (e.g. “my\_db”). | | user | string | false | Name of the Postgres user to connect as (e.g. “my-pg-user”). Defaults to IAM auth using [ADC](https://cloud.google.com/docs/authentication#adc)
email if unspecified. | | password | string | false | Password of the Postgres user (e.g. “my-password”). Defaults to attempting IAM authentication if unspecified. | | ipType | string | false | IP Type of the AlloyDB instance; must be one of `public` or `private`. Default: `public`. | Last modified January 6, 2026: [feat: add tool to list store procedure (#2156) (cf0fc515b57)](https://github.com/googleapis/genai-toolbox/commit/cf0fc515b57d9b84770076f3c0c5597c4597ef62) --- # Cloud SQL for PostgreSQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for PostgreSQL Admin using MCP ======================================== Create and manage Cloud SQL for PostgreSQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for PostgreSQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_pg_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-postgres-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-postgres-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for PostgreSQL using MCP. The `cloud-sql-postgres-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for PostgreSQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for PostgreSQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # SQLite using MCP | MCP Toolbox for Databases SQLite using MCP ================ Connect your IDE to SQLite using Toolbox. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol for connecting Large Language Models (LLMs) to data sources like SQLite. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to a SQLite instance: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/sqlite_mcp/#configure-your-mcp-client) Set up the database ------------------- 1. [Create or select a SQLite database file.](https://www.sqlite.org/download.html) Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.10.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.30.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "sqlite", "--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 4. Open [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration, replace the environment variables with your values, and save: { "servers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration, replace the environment variables with your values, and save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration, replace the environment variables with your values, and then save: { "mcpServers": { "sqlite": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","sqlite","--stdio"], "env": { "SQLITE_DATABASE": "./sample.db" } } } } Use Tools --------- Your AI tool is now connected to SQLite using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements. The following tools are available to the LLM: 1. **list\_tables**: lists tables and descriptions 2. **execute\_sql**: execute any SQL statement Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified March 20, 2026: [chore(main): release 0.30.0 (#2758) (5ef1c0ddda3)](https://github.com/googleapis/genai-toolbox/commit/5ef1c0ddda3dcb6cf3ce26915ecf62ac49570549) --- # Deploy ADK Agent and MCP Toolbox | MCP Toolbox for Databases Deploy ADK Agent and MCP Toolbox ================================ How to deploy your ADK Agent to Vertex AI Agent Engine and connect it to an MCP Toolbox deployed on Cloud Run. Before you begin ---------------- This guide assumes you have already done the following: 1. Completed the [Python Quickstart (Local)](https://mcp-toolbox.dev/v0.28.0/getting-started/local_quickstart/) and have a working ADK agent running locally. 2. Installed the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) . 3. A Google Cloud project with billing enabled. Step 1: Deploy MCP Toolbox to Cloud Run --------------------------------------- Before deploying your agent, your MCP Toolbox server needs to be accessible from the cloud. We will deploy MCP Toolbox to Cloud Run. Follow the [Deploy to Cloud Run](https://mcp-toolbox.dev/v0.28.0/how-to/deploy_toolbox/) guide to deploy your MCP Toolbox instance. #### Important After deployment, note down the Service URL of your MCP Toolbox Cloud Run service. You will need this to configure your agent. Step 2: Prepare your Agent for Deployment ----------------------------------------- We will use the `agent-starter-pack` tool to enhance your local agent project with the necessary configuration for deployment to Vertex AI Agent Engine. 1. Open a terminal and navigate to the **parent directory** of your agent project (the directory containing the `my_agent` folder). 2. Run the following command to enhance your project: uvx agent-starter-pack enhance --adk -d agent_engine 3. Follow the interactive prompts to configure your deployment settings. This process will generate deployment configuration files (like a `Makefile` and `Dockerfile`) in your project directory. 4. Add `google-adk[toolbox]` as a dependency to the new project: uv add google-adk[toolbox] Step 3: Configure Google Cloud Authentication --------------------------------------------- Ensure your local environment is authenticated with Google Cloud to perform the deployment. 1. Login with Application Default Credentials (ADC): gcloud auth application-default login 2. Set your active project: gcloud config set project Step 4: Connect Agent to Deployed MCP Toolbox --------------------------------------------- You need to update your agent’s code to connect to the Cloud Run URL of your MCP Toolbox instead of the local address. 1. Recall that you can find the Cloud Run deployment URL of the MCP Toolbox server using the following command: gcloud run services describe toolbox --format 'value(status.url)' 2. Open your agent file (`my_agent/agent.py`). 3. Update the `ToolboxToolset` initialization to point to your Cloud Run service URL. Replace the existing initialization code with the following: #### Note Since Cloud Run services are secured by default, you also need to provide a workload identity. from google.adk import Agent from google.adk.apps import App from google.adk.tools.toolbox_toolset import ToolboxToolset from toolbox_adk import CredentialStrategy # TODO(developer): Replace with your Toolbox Cloud Run Service URL TOOLBOX_URL = "https://your-toolbox-service-xyz.a.run.app" # Initialize the toolset with Workload Identity (generates ID token for the URL) toolset = ToolboxToolset( server_url=TOOLBOX_URL, credentials=CredentialStrategy.workload_identity(target_audience=TOOLBOX_URL) ) root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to provide accurate and useful information.", tools=[toolset], ) app = App(root_agent=root_agent, name="my_agent") #### Important Ensure that the `name` parameter in the `App` initialization matches the name of your agent’s parent directory (e.g., `my_agent`). ... app = App(root_agent=root_agent, name="my_agent") Step 5: Deploy to Agent Engine ------------------------------ Run the deployment command: make deploy This command will build your agent’s container image and deploy it to Vertex AI. Step 6: Test your Deployment ---------------------------- Once the deployment command (`make deploy`) completes, it will output the URL for the Agent Engine Playground. You can click on this URL to open the Playground in your browser and start chatting with your agent to test the tools. For additional test scenarios, refer to the [Test deployed agent](https://google.github.io/adk-docs/deploy/agent-engine/#test-deployment) section in the ADK documentation. Last modified February 11, 2026: [docs(adk): align quickstart script with other orchestrations (#2423) (1f8019c50a0)](https://github.com/googleapis/genai-toolbox/commit/1f8019c50a06d65553abd93da833b6dba09c612b) --- # AlloyDB Admin | MCP Toolbox for Databases AlloyDB Admin ============= The “alloydb-admin” source provides a client for the AlloyDB API. About ----- The `alloydb-admin` source provides a client to interact with the [Google AlloyDB API](https://cloud.google.com/alloydb/docs/reference/rest) . This allows tools to perform administrative tasks on AlloyDB resources, such as managing clusters, instances, and users. Authentication can be handled in two ways: 1. **Application Default Credentials (ADC):** By default, the source uses ADC to authenticate with the API. 2. **Client-side OAuth:** If `useClientOAuth` is set to `true`, the source will expect an OAuth 2.0 access token to be provided by the client (e.g., a web browser) for each request. Example ------- sources: my-alloydb-admin: kind: alloy-admin my-oauth-alloydb-admin: kind: alloydb-admin useClientOAuth: true Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “alloydb-admin”. | | defaultProject | string | false | The Google Cloud project ID to use for AlloyDB infrastructure tools. | | useClientOAuth | boolean | false | If true, the source will use client-side OAuth for authorization. Otherwise, it will use Application Default Credentials. Defaults to `false`. | Last modified November 11, 2025: [feat(source/alloydb, source/cloud-sql-postgres,source/cloud-sql-mysql,source/cloud-sql-mssql): Use project from env for alloydb and cloud sql control plane tools (#1588) (12bdd954597)](https://github.com/googleapis/genai-toolbox/commit/12bdd954597e49d3ec6b247cc104584c5a4d1943) --- # Google Sign-In | MCP Toolbox for Databases Google Sign-In ============== Use Google Sign-In for Oauth 2.0 flow and token lifecycle. Getting Started --------------- Google Sign-In manages the OAuth 2.0 flow and token lifecycle. To integrate the Google Sign-In workflow to your web app [follow this guide](https://developers.google.com/identity/sign-in/web/sign-in) . After setting up the Google Sign-In workflow, you should have registered your application and retrieved a [Client ID](https://developers.google.com/identity/sign-in/web/sign-in#create_authorization_credentials) . Configure your auth service in with the `Client ID`. Behavior -------- ### Authorized Invocations When using [Authorized Invocations](https://mcp-toolbox.dev/v0.26.0/resources/tools/#authorized-invocations) , a tool will be considered authorized if it has a valid Oauth 2.0 token that matches the Client ID. ### Authenticated Parameters When using [Authenticated Parameters](https://mcp-toolbox.dev/v0.26.0/resources/tools/#authenticated-parameters) , any [claim provided by the id-token](https://developers.google.com/identity/openid-connect/openid-connect#obtaininguserprofileinformation) can be used for the parameter. Example ------- authServices: my-google-auth: kind: google clientId: ${YOUR_GOOGLE_CLIENT_ID} Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “google”. | | clientId | string | true | Client ID of your application from registering your application. | Last modified August 15, 2025: [docs: fix typos across docs (#1154) (c65c11af246)](https://github.com/googleapis/genai-toolbox/commit/c65c11af2463009b06c3fc3d5dbdf350bdcd2494) --- # Cassandra | MCP Toolbox for Databases Cassandra ========= Apache Cassandra is a NoSQL distributed database known for its horizontal scalability, distributed architecture, and flexible schema definition. About ----- [Apache Cassandra](https://cassandra.apache.org/) is a NoSQL distributed database. By design, NoSQL databases are lightweight, open-source, non-relational, and largely distributed. Counted among their strengths are horizontal scalability, distributed architectures, and a flexible approach to schema definition. Available Tools --------------- * [`cassandra-cql`](https://mcp-toolbox.dev/v0.25.0/resources/tools/cassandra/cassandra-cql/) Run parameterized CQL queries in Cassandra. Example ------- sources: my-cassandra-source: kind: cassandra hosts: - 127.0.0.1 keyspace: my_keyspace protoVersion: 4 username: ${USER_NAME} password: ${PASSWORD} caPath: /path/to/ca.crt # Optional: path to CA certificate certPath: /path/to/client.crt # Optional: path to client certificate keyPath: /path/to/client.key # Optional: path to client key enableHostVerification: true # Optional: enable host verification Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “cassandra”. | | hosts | string\[\] | true | List of IP addresses to connect to (e.g., \[“192.168.1.1:9042”, “192.168.1.2:9042”,“192.168.1.3:9042”\]). The default port is 9042 if not specified. | | keyspace | string | true | Name of the Cassandra keyspace to connect to (e.g., “my\_keyspace”). | | protoVersion | integer | false | Protocol version for the Cassandra connection (e.g., 4). | | username | string | false | Name of the Cassandra user to connect as (e.g., “my-cassandra-user”). | | password | string | false | Password of the Cassandra user (e.g., “my-password”). | | caPath | string | false | Path to the CA certificate for SSL/TLS (e.g., “/path/to/ca.crt”). | | certPath | string | false | Path to the client certificate for SSL/TLS (e.g., “/path/to/client.crt”). | | keyPath | string | false | Path to the client key for SSL/TLS (e.g., “/path/to/client.key”). | | enableHostVerification | boolean | false | Enable host verification for SSL/TLS (e.g., true). By default, host verification is disabled. | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # ClickHouse | MCP Toolbox for Databases ClickHouse ========== ClickHouse is an open-source, OLTP database. About ----- [ClickHouse](https://clickhouse.com/docs) is a fast, open-source, column-oriented database Available Tools --------------- * [`clickhouse-execute-sql`](https://mcp-toolbox.dev/v0.25.0/resources/tools/clickhouse/clickhouse-execute-sql/) Execute parameterized SQL queries in ClickHouse with query logging. * [`clickhouse-sql`](https://mcp-toolbox.dev/v0.25.0/resources/tools/clickhouse/clickhouse-sql/) Execute SQL queries as prepared statements in ClickHouse. Requirements ------------ ### Database User This source uses standard ClickHouse authentication. You will need to [create a ClickHouse user](https://clickhouse.com/docs/en/sql-reference/statements/create/user) (or with [ClickHouse Cloud](https://clickhouse.com/docs/getting-started/quick-start/cloud#connect-with-your-app) ) to connect to the database with. The user should have appropriate permissions for the operations you plan to perform. ### Network Access ClickHouse supports multiple protocols: * **HTTPS protocol** (default port 8443) - Secure HTTP access (default) * **HTTP protocol** (default port 8123) - Good for web-based access Example ------- ### Secure Connection Example sources: secure-clickhouse-source: kind: clickhouse host: clickhouse.example.com port: "8443" database: analytics user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} protocol: https secure: true ### HTTP Protocol Example sources: http-clickhouse-source: kind: clickhouse host: localhost port: "8123" database: logs user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} protocol: http secure: false Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “clickhouse”. | | host | string | true | IP address or hostname to connect to (e.g. “127.0.0.1” or “clickhouse.example.com”) | | port | string | true | Port to connect to (e.g. “8443” for HTTPS, “8123” for HTTP) | | database | string | true | Name of the ClickHouse database to connect to (e.g. “my\_database”). | | user | string | true | Name of the ClickHouse user to connect as (e.g. “analytics\_user”). | | password | string | false | Password of the ClickHouse user (e.g. “my-password”). | | protocol | string | false | Connection protocol: “https” (default) or “http”. | | secure | boolean | false | Whether to use a secure connection (TLS). Default: false. | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Sources | MCP Toolbox for Databases Sources ======= Sources represent your different data sources that a tool can interact with. A Source represents a data sources that a tool can interact with. You can define Sources as a map in the `sources` section of your `tools.yaml` file. Typically, a source configuration will contain any information needed to connect with and interact with the database. Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. sources: my-cloud-sql-source: kind: cloud-sql-postgres project: my-project-id region: us-central1 instance: my-instance-name database: my_db user: ${USER_NAME} password: ${PASSWORD} In implementation, each source is a different connection pool or client that used to connect to the database and execute the tool. Available Sources ----------------- * * * ##### [AlloyDB for PostgreSQL](https://mcp-toolbox.dev/v0.26.0/resources/sources/alloydb-pg/) AlloyDB for PostgreSQL is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. ##### [AlloyDB Admin](https://mcp-toolbox.dev/v0.26.0/resources/sources/alloydb-admin/) The “alloydb-admin” source provides a client for the AlloyDB API. ##### [BigQuery](https://mcp-toolbox.dev/v0.26.0/resources/sources/bigquery/) BigQuery is Google Cloud’s fully managed, petabyte-scale, and cost-effective analytics data warehouse that lets you run analytics over vast amounts of data in near real time. With BigQuery, there’s no infrastructure to set up or manage, letting you focus on finding meaningful insights using GoogleSQL and taking advantage of flexible pricing models across on-demand and flat-rate options. ##### [Bigtable](https://mcp-toolbox.dev/v0.26.0/resources/sources/bigtable/) Bigtable is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. ##### [Cassandra](https://mcp-toolbox.dev/v0.26.0/resources/sources/cassandra/) Apache Cassandra is a NoSQL distributed database known for its horizontal scalability, distributed architecture, and flexible schema definition. ##### [ClickHouse](https://mcp-toolbox.dev/v0.26.0/resources/sources/clickhouse/) ClickHouse is an open-source, OLTP database. ##### [Cloud Healthcare API](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-healthcare/) The Cloud Healthcare API provides a managed solution for storing and accessing healthcare data in Google Cloud, providing a critical bridge between existing care systems and applications hosted on Google Cloud. ##### [Cloud Monitoring](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-monitoring/) A “cloud-monitoring” source provides a client for the Cloud Monitoring API. ##### [Cloud SQL for MySQL](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-sql-mysql/) Cloud SQL for MySQL is a fully-managed database service for MySQL. ##### [Cloud SQL for PostgreSQL](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-sql-pg/) Cloud SQL for PostgreSQL is a fully-managed database service for Postgres. ##### [Cloud SQL for SQL Server](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-sql-mssql/) Cloud SQL for SQL Server is a fully-managed database service for SQL Server. ##### [Cloud SQL Admin](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-sql-admin/) A “cloud-sql-admin” source provides a client for the Cloud SQL Admin API. ##### [Couchbase](https://mcp-toolbox.dev/v0.26.0/resources/sources/couchbase/) A “couchbase” source connects to a Couchbase database. ##### [Dataplex](https://mcp-toolbox.dev/v0.26.0/resources/sources/dataplex/) Dataplex Universal Catalog is a unified, intelligent governance solution for data and AI assets in Google Cloud. Dataplex Universal Catalog powers AI, analytics, and business intelligence at scale. ##### [Dgraph](https://mcp-toolbox.dev/v0.26.0/resources/sources/dgraph/) Dgraph is fully open-source, built-for-scale graph database for Gen AI workloads ##### [Elasticsearch](https://mcp-toolbox.dev/v0.26.0/resources/sources/elasticsearch/) Elasticsearch is a distributed, free and open search and analytics engine for all types of data, including textual, numerical, geospatial, structured, and unstructured. ##### [Firebird](https://mcp-toolbox.dev/v0.26.0/resources/sources/firebird/) Firebird is a powerful, cross-platform, and open-source relational database. ##### [Firestore](https://mcp-toolbox.dev/v0.26.0/resources/sources/firestore/) Firestore is a NoSQL document database built for automatic scaling, high performance, and ease of application development. It’s a fully managed, serverless database that supports mobile, web, and server development. ##### [Gemini Data Analytics](https://mcp-toolbox.dev/v0.26.0/resources/sources/cloud-gda/) A “cloud-gemini-data-analytics” source provides a client for the Gemini Data Analytics API. ##### [HTTP](https://mcp-toolbox.dev/v0.26.0/resources/sources/http/) The HTTP source enables the Toolbox to retrieve data from a remote server using HTTP requests. ##### [Looker](https://mcp-toolbox.dev/v0.26.0/resources/sources/looker/) Looker is a business intelligence tool that also provides a semantic layer. ##### [MariaDB](https://mcp-toolbox.dev/v0.26.0/resources/sources/mariadb/) MariaDB is an open-source relational database compatible with MySQL. ##### [MindsDB](https://mcp-toolbox.dev/v0.26.0/resources/sources/mindsdb/) MindsDB is an AI federated database that enables SQL queries across hundreds of datasources and ML models. ##### [MongoDB](https://mcp-toolbox.dev/v0.26.0/resources/sources/mongodb/) MongoDB is a no-sql data platform that can not only serve general purpose data requirements also perform VectorSearch where both operational data and embeddings used of search can reside in same document. ##### [MySQL](https://mcp-toolbox.dev/v0.26.0/resources/sources/mysql/) MySQL is a relational database management system that stores and manages data. ##### [Neo4j](https://mcp-toolbox.dev/v0.26.0/resources/sources/neo4j/) Neo4j is a powerful, open source graph database system ##### [OceanBase](https://mcp-toolbox.dev/v0.26.0/resources/sources/oceanbase/) OceanBase is a distributed relational database that provides high availability, scalability, and compatibility with MySQL. ##### [Oracle](https://mcp-toolbox.dev/v0.26.0/resources/sources/oracle/) Oracle Database is a widely-used relational database management system. ##### [PostgreSQL](https://mcp-toolbox.dev/v0.26.0/resources/sources/postgres/) PostgreSQL is a powerful, open source object-relational database. ##### [Redis](https://mcp-toolbox.dev/v0.26.0/resources/sources/redis/) Redis is a in-memory data structure store. ##### [Serverless for Apache Spark](https://mcp-toolbox.dev/v0.26.0/resources/sources/serverless-spark/) Google Cloud Serverless for Apache Spark lets you run Spark workloads without requiring you to provision and manage your own Spark cluster. ##### [SingleStore](https://mcp-toolbox.dev/v0.26.0/resources/sources/singlestore/) SingleStore is the cloud-native database built with speed and scale to power data-intensive applications. ##### [Snowflake](https://mcp-toolbox.dev/v0.26.0/resources/sources/snowflake/) Snowflake is a cloud-based data platform. ##### [Spanner](https://mcp-toolbox.dev/v0.26.0/resources/sources/spanner/) Spanner is a fully managed database service from Google Cloud that combines relational, key-value, graph, and search capabilities. ##### [SQL Server](https://mcp-toolbox.dev/v0.26.0/resources/sources/mssql/) SQL Server is a relational database management system (RDBMS). ##### [SQLite](https://mcp-toolbox.dev/v0.26.0/resources/sources/sqlite/) SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine. ##### [TiDB](https://mcp-toolbox.dev/v0.26.0/resources/sources/tidb/) TiDB is a distributed SQL database that combines the best of traditional RDBMS and NoSQL databases. ##### [Trino](https://mcp-toolbox.dev/v0.26.0/resources/sources/trino/) Trino is a distributed SQL query engine for big data analytics. ##### [Valkey](https://mcp-toolbox.dev/v0.26.0/resources/sources/valkey/) Valkey is an open-source, in-memory data structure store, forked from Redis. ##### [YugabyteDB](https://mcp-toolbox.dev/v0.26.0/resources/sources/yugabytedb/) YugabyteDB is a high-performance, distributed SQL database. Last modified April 23, 2025: [feat: Support env replacement for tool.yaml (#462) (eadb678a7bd)](https://github.com/googleapis/genai-toolbox/commit/eadb678a7bd4ce74a3b1160f5ed8966ffbb13c61) --- # Bigtable | MCP Toolbox for Databases Bigtable ======== Bigtable is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. Bigtable Source =============== [Bigtable](https://cloud.google.com/bigtable/docs) is a low-latency NoSQL database service for machine learning, operational analytics, and user-facing operations. It’s a wide-column, key-value store that can scale to billions of rows and thousands of columns. With Bigtable, you can replicate your data to regions across the world for high availability and data resiliency. If you are new to Bigtable, you can try to [create an instance and write data with the cbt CLI](https://cloud.google.com/bigtable/docs/create-instance-write-data-cbt-cli) . You can use [GoogleSQL statements](https://cloud.google.com/bigtable/docs/googlesql-overview) to query your Bigtable data. GoogleSQL is an ANSI-compliant structured query language (SQL) that is also implemented for other Google Cloud services. SQL queries are handled by cluster nodes in the same way as NoSQL data requests. Therefore, the same best practices apply when creating SQL queries to run against your Bigtable data, such as avoiding full table scans or complex filters. Available Tools --------------- * [`bigtable-sql`](https://mcp-toolbox.dev/v0.26.0/resources/tools/bigtable/bigtable-sql/) Run SQL-like queries over Bigtable rows. Requirements ------------ ### IAM Permissions Bigtable uses [Identity and Access Management (IAM)](https://cloud.google.com/bigtable/docs/access-control) to control user and group access to Bigtable resources at the project, instance, table, and backup level. Toolbox will use your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize and authenticate when interacting with [Bigtable](https://cloud.google.com/bigtable/docs) . In addition to [setting the ADC for your server](https://cloud.google.com/docs/authentication/provide-credentials-adc) , you need to ensure the IAM identity has been given the correct IAM permissions for the query provided. See [Apply IAM roles](https://cloud.google.com/bigtable/docs/access-control#iam-management-instance) for more information on applying IAM permissions and roles to an identity. Example ------- sources: my-bigtable-source: kind: "bigtable" project: "my-project-id" instance: "test-instance" Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “bigtable”. | | project | string | true | Id of the GCP project that the cluster was created in (e.g. “my-project-id”). | | instance | string | true | Name of the Bigtable instance. | Last modified July 22, 2025: [docs: add available tools for each source (#914) (a1def43b350)](https://github.com/googleapis/genai-toolbox/commit/a1def43b3502e90aacdfee669010ea29e0558452) --- # BigQuery | MCP Toolbox for Databases BigQuery ======== BigQuery is Google Cloud’s fully managed, petabyte-scale, and cost-effective analytics data warehouse that lets you run analytics over vast amounts of data in near real time. With BigQuery, there’s no infrastructure to set up or manage, letting you focus on finding meaningful insights using GoogleSQL and taking advantage of flexible pricing models across on-demand and flat-rate options. BigQuery Source =============== [BigQuery](https://cloud.google.com/bigquery/docs) is Google Cloud’s fully managed, petabyte-scale, and cost-effective analytics data warehouse that lets you run analytics over vast amounts of data in near real time. With BigQuery, there’s no infrastructure to set up or manage, letting you focus on finding meaningful insights using GoogleSQL and taking advantage of flexible pricing models across on-demand and flat-rate options. If you are new to BigQuery, you can try to [load and query data with the bq tool](https://cloud.google.com/bigquery/docs/quickstarts/quickstart-command-line) . BigQuery uses [GoogleSQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/) for querying data. GoogleSQL is an ANSI-compliant structured query language (SQL) that is also implemented for other Google Cloud services. SQL queries are handled by cluster nodes in the same way as NoSQL data requests. Therefore, the same best practices apply when creating SQL queries to run against your BigQuery data, such as avoiding full table scans or complex filters. Available Tools --------------- * [`bigquery-analyze-contribution`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-analyze-contribution/) Performs contribution analysis, also called key driver analysis in BigQuery. * [`bigquery-conversational-analytics`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-conversational-analytics/) Allows conversational interaction with a BigQuery source. * [`bigquery-execute-sql`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-execute-sql/) Execute structured queries using parameters. * [`bigquery-forecast`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-forecast/) Forecasts time series data in BigQuery. * [`bigquery-get-dataset-info`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-get-dataset-info/) Retrieve metadata for a specific dataset. * [`bigquery-get-table-info`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-get-table-info/) Retrieve metadata for a specific table. * [`bigquery-list-dataset-ids`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-list-dataset-ids/) List available dataset IDs. * [`bigquery-list-table-ids`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-list-table-ids/) List tables in a given dataset. * [`bigquery-sql`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-sql/) Run SQL queries directly against BigQuery datasets. * [`bigquery-search-catalog`](https://mcp-toolbox.dev/v0.25.0/resources/tools/bigquery/bigquery-search-catalog/) List all entries in Dataplex Catalog (e.g. tables, views, models) that matches given user query. ### Pre-built Configurations * [BigQuery using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/bigquery_mcp/) Connect your IDE to BigQuery using Toolbox. Requirements ------------ ### IAM Permissions BigQuery uses [Identity and Access Management (IAM)](https://cloud.google.com/bigquery/docs/access-control) to control user and group access to BigQuery resources like projects, datasets, and tables. ### Authentication via Application Default Credentials (ADC) By **default**, Toolbox will use your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize and authenticate when interacting with [BigQuery](https://cloud.google.com/bigquery/docs) . When using this method, you need to ensure the IAM identity associated with your ADC (such as a service account) has the correct permissions for the queries you intend to run. Common roles include `roles/bigquery.user` (which includes permissions to run jobs and read data) or `roles/bigbigquery.dataViewer`. Follow this [guide](https://cloud.google.com/docs/authentication/provide-credentials-adc) to set up your ADC. If you are running on Google Compute Engine (GCE) or Google Kubernetes Engine (GKE), you might need to explicitly set the access scopes for the service account. While you can configure scopes when creating the VM or node pool, you can also specify them in the source configuration using the `scopes` field. Common scopes include `https://www.googleapis.com/auth/bigquery` or `https://www.googleapis.com/auth/cloud-platform`. ### Authentication via User’s OAuth Access Token If the `useClientOAuth` parameter is set to `true`, Toolbox will instead use the OAuth access token for authentication. This token is parsed from the `Authorization` header passed in with the tool invocation request. This method allows Toolbox to make queries to [BigQuery](https://cloud.google.com/bigquery/docs) on behalf of the client or the end-user. When using this on-behalf-of authentication, you must ensure that the identity used has been granted the correct IAM permissions. Example ------- Initialize a BigQuery source that uses ADC: sources: my-bigquery-source: kind: "bigquery" project: "my-project-id" # location: "US" # Optional: Specifies the location for query jobs. # writeMode: "allowed" # One of: allowed, blocked, protected. Defaults to "allowed". # allowedDatasets: # Optional: Restricts tool access to a specific list of datasets. # - "my_dataset_1" # - "other_project.my_dataset_2" # impersonateServiceAccount: "[email protected]" # Optional: Service account to impersonate # scopes: # Optional: List of OAuth scopes to request. # - "https://www.googleapis.com/auth/bigquery" # - "https://www.googleapis.com/auth/drive.readonly" Initialize a BigQuery source that uses the client’s access token: sources: my-bigquery-client-auth-source: kind: "bigquery" project: "my-project-id" useClientOAuth: true # location: "US" # Optional: Specifies the location for query jobs. # writeMode: "allowed" # One of: allowed, blocked, protected. Defaults to "allowed". # allowedDatasets: # Optional: Restricts tool access to a specific list of datasets. # - "my_dataset_1" # - "other_project.my_dataset_2" # impersonateServiceAccount: "[email protected]" # Optional: Service account to impersonate # scopes: # Optional: List of OAuth scopes to request. # - "https://www.googleapis.com/auth/bigquery" # - "https://www.googleapis.com/auth/drive.readonly" Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “bigquery”. | | project | string | true | Id of the Google Cloud project to use for billing and as the default project for BigQuery resources. | | location | string | false | Specifies the location (e.g., ‘us’, ‘asia-northeast1’) in which to run the query job. This location must match the location of any tables referenced in the query. Defaults to the table’s location or ‘US’ if the location cannot be determined. [Learn More](https://cloud.google.com/bigquery/docs/locations) | | writeMode | string | false | Controls the write behavior for tools. `allowed` (default): All queries are permitted. `blocked`: Only `SELECT` statements are allowed for the `bigquery-execute-sql` tool. `protected`: Enables session-based execution where all tools associated with this source instance share the same [BigQuery session](https://cloud.google.com/bigquery/docs/sessions-intro)
. This allows for stateful operations using temporary tables (e.g., `CREATE TEMP TABLE`). For `bigquery-execute-sql`, `SELECT` statements can be used on all tables, but write operations are restricted to the session’s temporary dataset. For tools like `bigquery-sql`, `bigquery-forecast`, and `bigquery-analyze-contribution`, the `writeMode` restrictions do not apply, but they will operate within the shared session. **Note:** The `protected` mode cannot be used with `useClientOAuth: true`. It is also not recommended for multi-user server environments, as all users would share the same session. A session is terminated automatically after 24 hours of inactivity or after 7 days, whichever comes first. A new session is created on the next request, and any temporary data from the previous session will be lost. | | allowedDatasets | \[\]string | false | An optional list of dataset IDs that tools using this source are allowed to access. If provided, any tool operation attempting to access a dataset not in this list will be rejected. To enforce this, two types of operations are also disallowed: 1) Dataset-level operations (e.g., `CREATE SCHEMA`), and 2) operations where table access cannot be statically analyzed (e.g., `EXECUTE IMMEDIATE`, `CREATE PROCEDURE`). If a single dataset is provided, it will be treated as the default for prebuilt tools. | | useClientOAuth | bool | false | If true, forwards the client’s OAuth access token from the “Authorization” header to downstream queries. **Note:** This cannot be used with `writeMode: protected`. | | scopes | \[\]string | false | A list of OAuth 2.0 scopes to use for the credentials. If not provided, default scopes are used. | | impersonateServiceAccount | string | false | Service account email to impersonate when making BigQuery and Dataplex API calls. The authenticated principal must have the `roles/iam.serviceAccountTokenCreator` role on the target service account. [Learn More](https://cloud.google.com/iam/docs/service-account-impersonation) | Last modified January 6, 2026: [feat(bigquery): Make credentials scope configurable (#2210) (a4506009b93)](https://github.com/googleapis/genai-toolbox/commit/a4506009b93771b77fb05ae97044f914967e67ed) --- # Cloud Healthcare API | MCP Toolbox for Databases Cloud Healthcare API ==================== The Cloud Healthcare API provides a managed solution for storing and accessing healthcare data in Google Cloud, providing a critical bridge between existing care systems and applications hosted on Google Cloud. About ----- The [Cloud Healthcare API](https://cloud.google.com/healthcare/docs) provides a managed solution for storing and accessing healthcare data in Google Cloud, providing a critical bridge between existing care systems and applications hosted on Google Cloud. It supports healthcare data standards such as HL7® FHIR®, HL7® v2, and DICOM®. It provides a fully managed, highly scalable, enterprise-grade development environment for building clinical and analytics solutions securely on Google Cloud. A dataset is a container in your Google Cloud project that holds modality-specific healthcare data. Datasets contain other data stores, such as FHIR stores and DICOM stores, which in turn hold their own types of healthcare data. A single dataset can contain one or many data stores, and those stores can all service the same modality or different modalities as application needs dictate. Using multiple stores in the same dataset might be appropriate in various situations. If you are new to the Cloud Healthcare API, you can try to [create and view datasets and stores using curl](https://cloud.google.com/healthcare-api/docs/store-healthcare-data-rest) . Available Tools --------------- * [`cloud-healthcare-get-dataset`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-get-dataset/) Retrieves a dataset’s details. * [`cloud-healthcare-list-fhir-stores`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-list-fhir-stores/) Lists the available FHIR stores in the healthcare dataset. * [`cloud-healthcare-list-dicom-stores`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-list-dicom-stores/) Lists the available DICOM stores in the healthcare dataset. * [`cloud-healthcare-get-fhir-store`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-get-fhir-store/) Retrieves information about a FHIR store. * [`cloud-healthcare-get-fhir-store-metrics`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-get-fhir-store-metrics/) Retrieves metrics for a FHIR store. * [`cloud-healthcare-get-fhir-resource`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-get-fhir-resource/) Retrieves a specific FHIR resource from a FHIR store. * [`cloud-healthcare-fhir-patient-search`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-fhir-patient-search/) Searches for patients in a FHIR store based on a set of criteria. * [`cloud-healthcare-fhir-patient-everything`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-fhir-patient-everything/) Retrieves all information for a given patient. * [`cloud-healthcare-fhir-fetch-page`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-fhir-fetch-page/) Fetches a page of FHIR resources from a given URL. * [`cloud-healthcare-get-dicom-store`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-get-dicom-store/) Retrieves information about a DICOM store. * [`cloud-healthcare-get-dicom-store-metrics`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-get-dicom-store-metrics/) Retrieves metrics for a DICOM store. * [`cloud-healthcare-search-dicom-studies`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-search-dicom-studies/) Searches for DICOM studies in a DICOM store. * [`cloud-healthcare-search-dicom-series`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-search-dicom-series/) Searches for DICOM series in a DICOM store. * [`cloud-healthcare-search-dicom-instances`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-search-dicom-instances/) Searches for DICOM instances in a DICOM store. * [`cloud-healthcare-retrieve-rendered-dicom-instance`](https://mcp-toolbox.dev/v0.24.0/resources/tools/cloudhealthcare/cloud-healthcare-retrieve-rendered-dicom-instance/) Retrieves a rendered DICOM instance from a DICOM store. Requirements ------------ ### IAM Permissions The Cloud Healthcare API uses [Identity and Access Management (IAM)](https://cloud.google.com/healthcare/docs/access-control) to control user and group access to Cloud Healthcare resources like projects, datasets, and stores. ### Authentication via Application Default Credentials (ADC) By **default**, Toolbox will use your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize and authenticate when interacting with the [Cloud Healthcare API](https://cloud.google.com/healthcare/docs) . When using this method, you need to ensure the IAM identity associated with your ADC (such as a service account) has the correct permissions for the queries you intend to run. Common roles include `roles/healthcare.fhirResourceReader` (which includes permissions to read and search for FHIR resources) or `roles/healthcare.dicomViewer` (for retrieving DICOM images). Follow this [guide](https://cloud.google.com/docs/authentication/provide-credentials-adc) to set up your ADC. ### Authentication via User’s OAuth Access Token If the `useClientOAuth` parameter is set to `true`, Toolbox will instead use the OAuth access token for authentication. This token is parsed from the `Authorization` header passed in with the tool invocation request. This method allows Toolbox to make queries to the [Cloud Healthcare API](https://cloud.google.com/healthcare/docs) on behalf of the client or the end-user. When using this on-behalf-of authentication, you must ensure that the identity used has been granted the correct IAM permissions. Example ------- Initialize a Cloud Healthcare API source that uses ADC: sources: my-healthcare-source: kind: "cloud-healthcare" project: "my-project-id" region: "us-central1" dataset: "my-healthcare-dataset-id" # allowedFhirStores: # Optional: Restricts tool access to a specific list of FHIR store IDs. # - "my_fhir_store_1" # allowedDicomStores: # Optional: Restricts tool access to a specific list of DICOM store IDs. # - "my_dicom_store_1" # - "my_dicom_store_2" Initialize a Cloud Healthcare API source that uses the client’s access token: sources: my-healthcare-client-auth-source: kind: "cloud-healthcare" project: "my-project-id" region: "us-central1" dataset: "my-healthcare-dataset-id" useClientOAuth: true # allowedFhirStores: # Optional: Restricts tool access to a specific list of FHIR store IDs. # - "my_fhir_store_1" # allowedDicomStores: # Optional: Restricts tool access to a specific list of DICOM store IDs. # - "my_dicom_store_1" # - "my_dicom_store_2" Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “cloud-healthcare”. | | project | string | true | ID of the GCP project that the dataset lives in. | | region | string | true | Specifies the region (e.g., ‘us’, ‘asia-northeast1’) of the healthcare dataset. [Learn More](https://cloud.google.com/healthcare-api/docs/regions) | | dataset | string | true | ID of the healthcare dataset. | | allowedFhirStores | \[\]string | false | An optional list of FHIR store IDs that tools using this source are allowed to access. If provided, any tool operation attempting to access a store not in this list will be rejected. If a single store is provided, it will be treated as the default for prebuilt tools. | | allowedDicomStores | \[\]string | false | An optional list of DICOM store IDs that tools using this source are allowed to access. If provided, any tool operation attempting to access a store not in this list will be rejected. If a single store is provided, it will be treated as the default for prebuilt tools. | | useClientOAuth | bool | false | If true, forwards the client’s OAuth access token from the “Authorization” header to downstream queries. | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Toolbox UI | MCP Toolbox for Databases Toolbox UI ========== How to effectively use Toolbox UI. Toolbox UI is a built-in web interface that allows users to visually inspect and test out configured resources such as tools and toolsets. Launching Toolbox UI -------------------- To launch Toolbox’s interactive UI, use the `--ui` flag. ./toolbox --ui Toolbox UI will be served from the same host and port as the Toolbox Server, with the `/ui` suffix. Once Toolbox is launched, the following INFO log with Toolbox UI’s url will be shown: INFO "Toolbox UI is up and running at: http://localhost:5000/ui" Navigating the Tools Page ------------------------- The tools page shows all tools loaded from your configuration file. This corresponds to the default toolset (represented by an empty string). Each tool’s name on this page will exactly match its name in the configuration file. To view details for a specific tool, click on the tool name. The main content area will be populated with the tool name, description, and available parameters. ![Tools Page](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/tools.png) ### Invoking a Tool 1. Click on a Tool 2. Enter appropriate parameters in each parameter field 3. Click “Run Tool” 4. Done! Your results will appear in the response field 5. (Optional) Uncheck “Prettify JSON” to format the response as plain text ![Run Tool Demo GIF](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/run-tool.gif) ### Optional Parameters Toolbox allows users to add [optional parameters](https://mcp-toolbox.dev/v0.29.0/resources/tools/#basic-parameters) with or without a default value. To exclude a parameter, uncheck the box to the right of an associated parameter, and that parameter will not be included in the request body. If the parameter is not sent, Toolbox will either use it as `nil` value or the `default` value, if configured. If the parameter is required, Toolbox will throw an error. When the box is checked, parameter will be sent exactly as entered in the response field (e.g. empty string). ![Optional Parameter checked example](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/optional-param-checked.png) ![Optional Parameter unchecked example](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/optional-param-unchecked.png) ### Editing Headers To edit headers, press the “Edit Headers” button to display the header modal. Within this modal, users can make direct edits by typing into the header’s text area. Toolbox UI validates that the headers are in correct JSON format. Other header-related errors (e.g., incorrect header names or values required by the tool) will be reported in the Response section after running the tool. ![Edit Headers](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/edit-headers.png) #### Google OAuth Currently, Toolbox supports Google OAuth 2.0 as an AuthService, which allows tools to utilize authorized parameters. When a tool uses an authorized parameter, the parameter will be displayed but not editable, as it will be populated from the authentication token. To provide the token, add your Google OAuth ID Token to the request header using the “Edit Headers” button and modal described above. The key should be the name of your AuthService as defined in your tool configuration file, suffixed with `_token`. The value should be your ID token as a string. 1. Select a tool that requires [authenticated parameters](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/) 2. The auth parameter’s text field is greyed out. This is because it cannot be entered manually and will be parsed from the resolved auth token 3. To update request headers with the token, select “Edit Headers” 4. (Optional) If you wish to manually edit the header, checkout the dropdown “How to extract Google OAuth ID Token manually” for guidance on retrieving ID token 5. To edit the header automatically, click the “Auto Setup” button that is associated with your Auth Profile 6. Enter the Client ID defined in your tools configuration file 7. Click “Continue” 8. Click “Sign in With Google” and login with your associated google account. This should automatically populate the header text area with your token 9. Click “Save” 10. Click “Run Tool” { "Content-Type": "application/json", "my-google-auth_token": "YOUR_ID_TOKEN_HERE" } ![Using Authenticated Parameter GIF](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/edit-headers.gif) Navigating the Toolsets Page ---------------------------- Through the toolsets page, users can search for a specific toolset to retrieve tools from. Simply enter the toolset name in the search bar, and press “Enter” to retrieve the associated tools. If the toolset name is not defined within the tools configuration file, an error message will be displayed. ![Toolsets Page](https://mcp-toolbox.dev/v0.29.0/how-to/toolbox-ui/toolsets.png) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server Admin using MCP ======================================== Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for SQL Server instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.29.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for SQL Server using MCP. The `cloud-sql-mssql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for SQL Server instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for SQL Server instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Deploy to Cloud Run | MCP Toolbox for Databases Deploy to Cloud Run =================== How to set up and configure Toolbox to run on Cloud Run. Before you begin ---------------- 1. [Install](https://cloud.google.com/sdk/docs/install) the Google Cloud CLI. 2. Set the PROJECT\_ID environment variable: export PROJECT_ID="my-project-id" 3. Initialize gcloud CLI: gcloud init gcloud config set project $PROJECT_ID 4. Make sure you’ve set up and initialized your database. 5. You must have the following APIs enabled: gcloud services enable run.googleapis.com \ cloudbuild.googleapis.com \ artifactregistry.googleapis.com \ iam.googleapis.com \ secretmanager.googleapis.com 6. To create an IAM account, you must have the following IAM permissions (or roles): * Create Service Account role (roles/iam.serviceAccountCreator) 7. To create a secret, you must have the following roles: * Secret Manager Admin role (roles/secretmanager.admin) 8. To deploy to Cloud Run, you must have the following set of roles: * Cloud Run Developer (roles/run.developer) * Service Account User role (roles/iam.serviceAccountUser) Note If you are using sources that require VPC-access (such as AlloyDB or Cloud SQL over private IP), make sure your Cloud Run service and the database are in the same VPC network. Create a service account ------------------------ 1. Create a backend service account if you don’t already have one: gcloud iam service-accounts create toolbox-identity 2. Grant permissions to use secret manager: gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/secretmanager.secretAccessor 3. Grant additional permissions to the service account that are specific to the source, e.g.: * [AlloyDB for PostgreSQL](https://mcp-toolbox.dev/v0.28.0/resources/sources/alloydb-pg/#iam-permissions) * [Cloud SQL for PostgreSQL](https://mcp-toolbox.dev/v0.28.0/resources/sources/cloud-sql-pg/#iam-permissions) Configure `tools.yaml` file --------------------------- Create a `tools.yaml` file that contains your configuration for Toolbox. For details, see the [configuration](https://mcp-toolbox.dev/v0.28.0/resources/sources/) section. Deploy to Cloud Run ------------------- 1. Upload `tools.yaml` as a secret: gcloud secrets create tools --data-file=tools.yaml If you already have a secret and want to update the secret version, execute the following: gcloud secrets versions add tools --data-file=tools.yaml 2. Set an environment variable to the container image that you want to use for cloud run: export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest Note **The `$PORT` Environment Variable** Google Cloud Run dictates the port your application must listen on by setting the `$PORT` environment variable inside your container. This value defaults to **8080**. Your application’s `--port` argument **must** be set to listen on this port. If there is a mismatch, the container will fail to start and the deployment will time out. 3. Deploy Toolbox to Cloud Run using the following command: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud ### Update deployed server to be secure To prevent DNS rebinding attack, use the `--allowed-hosts` flag to specify a list of hosts. In order to do that, you will have to re-deploy the cloud run service with the new flag. To implement CORs checks, use the `--allowed-origins` flag to specify a list of origins permitted to access the server. 1. Set an environment variable to the cloud run url: export URL= export HOST= 2. Redeploy Toolbox: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST" # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud If you are using a VPC network, use the command below: gcloud run deploy toolbox \ --image $IMAGE \ --service-account toolbox-identity \ --region us-central1 \ --set-secrets "/app/tools.yaml=tools:latest" \ --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--allowed-origins=$URL","--allowed-hosts=$HOST" \ # TODO(dev): update the following to match your VPC if necessary --network default \ --subnet default # --allow-unauthenticated # https://cloud.google.com/run/docs/authenticating/public#gcloud Connecting with Toolbox Client SDK ---------------------------------- You can connect to Toolbox Cloud Run instances directly through the SDK. 1. [Set up `Cloud Run Invoker` role access](https://cloud.google.com/run/docs/securing/managing-access#service-add-principals) to your Cloud Run service. 2. (Only for local runs) Set up [Application Default Credentials](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) for the principal you set up the `Cloud Run Invoker` role access to. 3. Run the following to retrieve a non-deterministic URL for the cloud run service: gcloud run services describe toolbox --format 'value(status.url)' 4. Import and initialize the toolbox client with the URL retrieved above: * Python * Javascript * Go import asyncio from toolbox_core import ToolboxClient, auth_methods # Replace with the Cloud Run service URL generated in the previous step URL = "https://cloud-run-url.app" auth_token_provider = auth_methods.aget_google_id_token(URL) # can also use sync method async def main(): async with ToolboxClient( URL, client_headers={"Authorization": auth_token_provider}, ) as toolbox: toolset = await toolbox.load_toolset() # ... asyncio.run(main()) import { ToolboxClient } from '@toolbox-sdk/core'; import {getGoogleIdToken} from '@toolbox-sdk/core/auth' // Replace with the Cloud Run service URL generated in the previous step. const URL = 'http://127.0.0.1:5000'; const authTokenProvider = () => getGoogleIdToken(URL); const client = new ToolboxClient(URL, null, {"Authorization": authTokenProvider}); import "github.com/googleapis/mcp-toolbox-sdk-go/core" func main() { // Replace with the Cloud Run service URL generated in the previous step. URL := "http://127.0.0.1:5000" auth_token_provider, err := core.GetGoogleIDToken(ctx, URL) if err != nil { log.Fatalf("Failed to fetch token %v", err) } toolboxClient, err := core.NewToolboxClient( URL, core.WithClientHeaderString("Authorization", auth_token_provider)) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } } Now, you can use this client to connect to the deployed Cloud Run instance! Troubleshooting --------------- Note For any deployment or runtime error, the best first step is to check the logs for your service in the Google Cloud Console’s Cloud Run section. They often contain the specific error message needed to diagnose the problem. * **Deployment Fails with “Container failed to start”:** This is almost always caused by a port mismatch. Ensure your container’s `--port` argument is set to `8080` to match the `$PORT` environment variable provided by Cloud Run. * **Client Receives Permission Denied Error (401 or 403):** If your client application (e.g., your local SDK) gets a `401 Unauthorized` or `403 Forbidden` error when trying to call your Cloud Run service, it means the client is not properly authenticated as an invoker. * Ensure the user or service account calling the service has the **Cloud Run Invoker** (`roles/run.invoker`) IAM role. * If running locally, make sure your Application Default Credentials are set up correctly by running `gcloud auth application-default login`. * **Service Fails to Access Secrets (in logs):** If your application starts but the logs show errors like “permission denied” when trying to access Secret Manager, it means the Toolbox service account is missing permissions. * Ensure the `toolbox-identity` service account has the **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`) IAM role. * **Cloud Run Connections via IAP:** Currently we do not support Cloud Run connections via [IAP](https://docs.cloud.google.com/iap/docs/concepts-overview) . Please disable IAP if you are using it. Last modified February 16, 2026: [refactor: remove explicit Protocol import and argument from ToolboxClient initialization example in deployment documentation (#2480) (41afeafaaee)](https://github.com/googleapis/genai-toolbox/commit/41afeafaaeea6c6f716f11c1ac83a4bb71cb56d3) --- # Connect via Gemini CLI Extensions | MCP Toolbox for Databases Connect via Gemini CLI Extensions ================================= Connect to Toolbox via Gemini CLI Extensions. Gemini CLI Extensions --------------------- [Gemini CLI](https://google-gemini.github.io/gemini-cli/) is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an agentic interface for interacting with database and analytics services and popular open-source databases. ### How extensions work Gemini CLI is highly extensible, allowing for the addition of new tools and capabilities through extensions. You can load the extensions from a GitHub URL, a local directory, or a configurable registry. They provide new tools, slash commands, and prompts to assist with your workflow. Use the Gemini CLI Extensions to load prebuilt or custom tools to interact with your databases. Below are a list of Gemini CLI Extensions powered by MCP Toolbox: * [alloydb](https://github.com/gemini-cli-extensions/alloydb) * [alloydb-observability](https://github.com/gemini-cli-extensions/alloydb-observability) * [bigquery-conversational-analytics](https://github.com/gemini-cli-extensions/bigquery-conversational-analytics) * [bigquery-data-analytics](https://github.com/gemini-cli-extensions/bigquery-data-analytics) * [cloud-sql-mysql](https://github.com/gemini-cli-extensions/cloud-sql-mysql) * [cloud-sql-mysql-observability](https://github.com/gemini-cli-extensions/cloud-sql-mysql-observability) * [cloud-sql-postgresql](https://github.com/gemini-cli-extensions/cloud-sql-postgresql) * [cloud-sql-postgresql-observability](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability) * [cloud-sql-sqlserver](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver) * [cloud-sql-sqlserver-observability](https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability) * [dataplex](https://github.com/gemini-cli-extensions/dataplex) * [firestore-native](https://github.com/gemini-cli-extensions/firestore-native) * [looker](https://github.com/gemini-cli-extensions/looker) * [mcp-toolbox](https://github.com/gemini-cli-extensions/mcp-toolbox) * [mysql](https://github.com/gemini-cli-extensions/mysql) * [postgres](https://github.com/gemini-cli-extensions/postgres) * [spanner](https://github.com/gemini-cli-extensions/spanner) * [sql-server](https://github.com/gemini-cli-extensions/sql-server) Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # AlloyDB for PostgreSQL | MCP Toolbox for Databases AlloyDB for PostgreSQL ====================== AlloyDB for PostgreSQL is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. About ----- [AlloyDB for PostgreSQL](https://cloud.google.com/alloydb/docs) is a fully-managed, PostgreSQL-compatible database for demanding transactional workloads. It provides enterprise-grade performance and availability while maintaining 100% compatibility with open-source PostgreSQL. If you are new to AlloyDB for PostgreSQL, you can [create a free trial cluster](https://cloud.google.com/alloydb/docs/create-free-trial-cluster) . Available Tools --------------- * [`alloydb-ai-nl`](https://mcp-toolbox.dev/v0.26.0/resources/tools/alloydbainl/alloydb-ai-nl/) Use natural language queries on AlloyDB, powered by AlloyDB AI. * [`postgres-sql`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-sql/) Execute SQL queries as prepared statements in AlloyDB Postgres. * [`postgres-execute-sql`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-execute-sql/) Run parameterized SQL statements in AlloyDB Postgres. * [`postgres-list-tables`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-tables/) List tables in an AlloyDB for PostgreSQL database. * [`postgres-list-active-queries`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-active-queries/) List active queries in an AlloyDB for PostgreSQL database. * [`postgres-list-available-extensions`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-available-extensions/) List available extensions for installation in a PostgreSQL database. * [`postgres-list-installed-extensions`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-installed-extensions/) List installed extensions in a PostgreSQL database. * [`postgres-list-views`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-views/) List views in an AlloyDB for PostgreSQL database. * [`postgres-list-schemas`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-schemas/) List schemas in an AlloyDB for PostgreSQL database. * [`postgres-database-overview`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-database-overview/) Fetches the current state of the PostgreSQL server. * [`postgres-list-triggers`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-triggers/) List triggers in an AlloyDB for PostgreSQL database. * [`postgres-list-indexes`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-indexes/) List available user indexes in a PostgreSQL database. * [`postgres-list-sequences`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-sequences/) List sequences in a PostgreSQL database. * [`postgres-long-running-transactions`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-long-running-transactions/) List long running transactions in a PostgreSQL database. * [`postgres-list-locks`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-locks/) List lock stats in a PostgreSQL database. * [`postgres-replication-stats`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-replication-stats/) List replication stats in a PostgreSQL database. * [`postgres-list-query-stats`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-query-stats/) List query statistics in a PostgreSQL database. * [`postgres-get-column-cardinality`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-get-column-cardinality/) List cardinality of columns in a table in a PostgreSQL database. * [`postgres-list-table-stats`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-table-stats/) List statistics of a table in a PostgreSQL database. * [`postgres-list-publication-tables`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-publication-tables/) List publication tables in a PostgreSQL database. * [`postgres-list-tablespaces`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-tablespaces/) List tablespaces in an AlloyDB for PostgreSQL database. * [`postgres-list-pg-settings`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-pg-settings/) List configuration parameters for the PostgreSQL server. * [`postgres-list-database-stats`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-database-stats/) Lists the key performance and activity statistics for each database in the AlloyDB instance. * [`postgres-list-roles`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-roles/) Lists all the user-created roles in PostgreSQL database. * [`postgres-list-stored-procedure`](https://mcp-toolbox.dev/v0.26.0/resources/tools/postgres/postgres-list-stored-procedure/) Lists all the stored procedure in PostgreSQL database. ### Pre-built Configurations * [AlloyDB using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/alloydb_pg_mcp/) Connect your IDE to AlloyDB using Toolbox. * [AlloyDB Admin API using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/alloydb_pg_admin_mcp/) Create your AlloyDB database with MCP Toolbox. Requirements ------------ ### IAM Permissions By default, AlloyDB for PostgreSQL source uses the [AlloyDB Go Connector](https://github.com/GoogleCloudPlatform/alloydb-go-connector) to authorize and establish mTLS connections to your AlloyDB instance. The Go connector uses your [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc) to authorize your connection to AlloyDB. In addition to [setting the ADC for your server](https://cloud.google.com/docs/authentication/provide-credentials-adc) , you need to ensure the IAM identity has been given the following IAM roles (or corresponding permissions): * `roles/alloydb.client` * `roles/serviceusage.serviceUsageConsumer` ### Networking AlloyDB supports connecting over both from external networks via the internet ([public IP](https://cloud.google.com/alloydb/docs/connect-public-ip) ), and internal networks ([private IP](https://cloud.google.com/alloydb/docs/private-ip) ). For more information on choosing between the two options, see the AlloyDB page [Connection overview](https://cloud.google.com/alloydb/docs/connection-overview) . You can configure the `ipType` parameter in your source configuration to `public` or `private` to match your cluster’s configuration. Regardless of which you choose, all connections use IAM-based authorization and are encrypted with mTLS. ### Authentication This source supports both password-based authentication and IAM authentication (using your [Application Default Credentials](https://cloud.google.com/docs/authentication#adc) ). #### Standard Authentication To connect using user/password, [create a PostgreSQL user](https://cloud.google.com/alloydb/docs/database-users/about) and input your credentials in the `user` and `password` fields. user: ${USER_NAME} password: ${PASSWORD} #### IAM Authentication To connect using IAM authentication: 1. Prepare your database instance and user following this [guide](https://cloud.google.com/alloydb/docs/database-users/manage-iam-auth) . 2. You could choose one of the two ways to log in: * Specify your IAM email as the `user`. * Leave your `user` field blank. Toolbox will fetch the [ADC](https://cloud.google.com/docs/authentication#adc) automatically and log in using the email associated with it. 3. Leave the `password` field blank. Example ------- sources: my-alloydb-pg-source: kind: alloydb-postgres project: my-project-id region: us-central1 cluster: my-cluster instance: my-instance database: my_db user: ${USER_NAME} password: ${PASSWORD} # ipType: "public" Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “alloydb-postgres”. | | project | string | true | Id of the GCP project that the cluster was created in (e.g. “my-project-id”). | | region | string | true | Name of the GCP region that the cluster was created in (e.g. “us-central1”). | | cluster | string | true | Name of the AlloyDB cluster (e.g. “my-cluster”). | | instance | string | true | Name of the AlloyDB instance within the cluster (e.g. “my-instance”). | | database | string | true | Name of the Postgres database to connect to (e.g. “my\_db”). | | user | string | false | Name of the Postgres user to connect as (e.g. “my-pg-user”). Defaults to IAM auth using [ADC](https://cloud.google.com/docs/authentication#adc)
email if unspecified. | | password | string | false | Password of the Postgres user (e.g. “my-password”). Defaults to attempting IAM authentication if unspecified. | | ipType | string | false | IP Type of the AlloyDB instance; must be one of `public` or `private`. Default: `public`. | Last modified January 6, 2026: [feat: add tool to list store procedure (#2156) (cf0fc515b57)](https://github.com/googleapis/genai-toolbox/commit/cf0fc515b57d9b84770076f3c0c5597c4597ef62) --- # AuthServices | MCP Toolbox for Databases AuthServices ============ AuthServices represent services that handle authentication and authorization. AuthServices represent services that handle authentication and authorization. It can primarily be used by [Tools](https://mcp-toolbox.dev/v0.26.0/resources/tools/) in two different ways: * [**Authorized Invocation**](https://mcp-toolbox.dev/v0.26.0/resources/tools/#authorized-invocations) is when a tool is validated by the auth service before the call can be invoked. Toolbox will reject any calls that fail to validate or have an invalid token. * [**Authenticated Parameters**](https://mcp-toolbox.dev/v0.26.0/resources/tools/#authenticated-parameters) replace the value of a parameter with a field from an [OIDC](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) claim. Toolbox will automatically resolve the ID token provided by the client and replace the parameter in the tool call. Example ------- The following configurations are placed at the top level of a `tools.yaml` file. Tip If you are accessing Toolbox with multiple applications, each application should register their own Client ID even if they use the same “kind” of auth provider. authServices: my_auth_app_1: kind: google clientId: ${YOUR_CLIENT_ID_1} my_auth_app_2: kind: google clientId: ${YOUR_CLIENT_ID_2} Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. After you’ve configured an `authService` you’ll, need to reference it in the configuration for each tool that should use it: * **Authorized Invocations** for authorizing a tool call, [use the `authRequired` field in a tool config](https://mcp-toolbox.dev/v0.26.0/resources/tools/#authorized-invocations) * **Authenticated Parameters** for using the value from a OIDC claim, [use the `authServices` field in a parameter config](https://mcp-toolbox.dev/v0.26.0/resources/tools/#authenticated-parameters) Specifying ID Tokens from Clients --------------------------------- After [configuring](https://mcp-toolbox.dev/v0.26.0/resources/authservices/#example) your `authServices` section, use a Toolbox SDK to add your ID tokens to the header of a Tool invocation request. When specifying a token you will provide a function (that returns an id). This function is called when the tool is invoked. This allows you to cache and refresh the ID token as needed. The primary method for providing these getters is via the `auth_token_getters` parameter when loading tools, or the `add_auth_token_getter`() / `add_auth_token_getters()` methods on a loaded tool object. ### Specifying tokens during load #### Python Use the [Python SDK](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main) . * Core * LangChain * Llamaindex import asyncio from toolbox_core import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): async with ToolboxClient("") as toolbox: auth_tool = await toolbox.load_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) result = await auth_tool(param="value") print(result) if **name** == "**main**": asyncio.run(main()) import asyncio from toolbox_langchain import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): toolbox = ToolboxClient("") auth_tool = await toolbox.aload_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) result = await auth_tool.ainvoke({"param": "value"}) print(result) if **name** == "**main**": asyncio.run(main()) import asyncio from toolbox_llamaindex import ToolboxClient async def get_auth_token(): # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) # This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" # Placeholder async def main(): toolbox = ToolboxClient("") auth_tool = await toolbox.aload_tool( "get_sensitive_data", auth_token_getters={"my_auth_app_1": get_auth_token} ) # result = await auth_tool.acall(param="value") # print(result.content) if **name** == "**main**": asyncio.run(main()) #### Javascript/Typescript Use the [JS SDK](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main) . import { ToolboxClient } from '@toolbox-sdk/core'; async function getAuthToken() { // ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) // This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" // Placeholder } const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); const authTool = await client.loadTool("my-tool", {"my_auth_app_1": getAuthToken}); const result = await authTool({param:"value"}); console.log(result); print(result) #### Go Use the [Go SDK](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main) . import "github.com/googleapis/mcp-toolbox-sdk-go/core" import "fmt" func getAuthToken() string { // ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) // This example just returns a placeholder. Replace with your actual token retrieval. return "YOUR_ID_TOKEN" // Placeholder } func main() { URL := 'http://127.0.0.1:5000' client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } dynamicTokenSource := core.NewCustomTokenSource(getAuthToken) authTool, err := client.LoadTool( "my-tool", ctx, core.WithAuthTokenSource("my_auth_app_1", dynamicTokenSource)) if err != nil { log.Fatalf("Failed to load tool: %v", err) } inputs := map[string]any{"param": "value"} result, err := authTool.Invoke(ctx, inputs) if err != nil { log.Fatalf("Failed to invoke tool: %v", err) } fmt.Println(result) } ### Specifying tokens for existing tools #### Python Use the [Python SDK](https://github.com/googleapis/mcp-toolbox-sdk-python/tree/main) . * Core * LangChain * Llamaindex tools = await toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) tools = toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) tools = toolbox.load_toolset() # for a single token authorized_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # OR, if multiple tokens are needed authorized_tool = tools[0].add_auth_token_getters({ "my_auth1": get_auth1_token, "my_auth2": get_auth2_token, }) #### Javascript/Typescript Use the [JS SDK](https://github.com/googleapis/mcp-toolbox-sdk-js/tree/main) . const URL = 'http://127.0.0.1:5000'; let client = new ToolboxClient(URL); let tool = await client.loadTool("my-tool") // for a single token const authorizedTool = tool.addAuthTokenGetter("my_auth", get_auth_token) // OR, if multiple tokens are needed const multiAuthTool = tool.addAuthTokenGetters({ "my_auth_1": getAuthToken1, "my_auth_2": getAuthToken2, }) #### Go Use the [Go SDK](https://github.com/googleapis/mcp-toolbox-sdk-go/tree/main) . import "github.com/googleapis/mcp-toolbox-sdk-go/core" func main() { URL := 'http://127.0.0.1:5000' client, err := core.NewToolboxClient(URL) if err != nil { log.Fatalf("Failed to create Toolbox client: %v", err) } tool, err := client.LoadTool("my-tool", ctx)) if err != nil { log.Fatalf("Failed to load tool: %v", err) } dynamicTokenSource1 := core.NewCustomTokenSource(getAuthToken1) dynamicTokenSource2 := core.NewCustomTokenSource(getAuthToken1) // For a single token authTool, err := tool.ToolFrom( core.WithAuthTokenSource("my-auth", dynamicTokenSource), ) // OR, if multiple tokens are needed authTool, err := tool.ToolFrom( core.WithAuthTokenSource("my-auth_1", dynamicTokenSource1), core.WithAuthTokenSource("my-auth_2", dynamicTokenSource2), ) } Kinds of Auth Services ---------------------- * * * ##### [Google Sign-In](https://mcp-toolbox.dev/v0.26.0/resources/authservices/google/) Use Google Sign-In for Oauth 2.0 flow and token lifecycle. Last modified September 18, 2025: [docs: fix docs linting (#1520) (3d8a041782d)](https://github.com/googleapis/genai-toolbox/commit/3d8a041782db4ec94d25f1e96d69cb9e5941e9e6) --- # Cassandra | MCP Toolbox for Databases Cassandra ========= Apache Cassandra is a NoSQL distributed database known for its horizontal scalability, distributed architecture, and flexible schema definition. About ----- [Apache Cassandra](https://cassandra.apache.org/) is a NoSQL distributed database. By design, NoSQL databases are lightweight, open-source, non-relational, and largely distributed. Counted among their strengths are horizontal scalability, distributed architectures, and a flexible approach to schema definition. Available Tools --------------- * [`cassandra-cql`](https://mcp-toolbox.dev/v0.26.0/resources/tools/cassandra/cassandra-cql/) Run parameterized CQL queries in Cassandra. Example ------- sources: my-cassandra-source: kind: cassandra hosts: - 127.0.0.1 keyspace: my_keyspace protoVersion: 4 username: ${USER_NAME} password: ${PASSWORD} caPath: /path/to/ca.crt # Optional: path to CA certificate certPath: /path/to/client.crt # Optional: path to client certificate keyPath: /path/to/client.key # Optional: path to client key enableHostVerification: true # Optional: enable host verification Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “cassandra”. | | hosts | string\[\] | true | List of IP addresses to connect to (e.g., \[“192.168.1.1:9042”, “192.168.1.2:9042”,“192.168.1.3:9042”\]). The default port is 9042 if not specified. | | keyspace | string | true | Name of the Cassandra keyspace to connect to (e.g., “my\_keyspace”). | | protoVersion | integer | false | Protocol version for the Cassandra connection (e.g., 4). | | username | string | false | Name of the Cassandra user to connect as (e.g., “my-cassandra-user”). | | password | string | false | Password of the Cassandra user (e.g., “my-password”). | | caPath | string | false | Path to the CA certificate for SSL/TLS (e.g., “/path/to/ca.crt”). | | certPath | string | false | Path to the client certificate for SSL/TLS (e.g., “/path/to/client.crt”). | | keyPath | string | false | Path to the client key for SSL/TLS (e.g., “/path/to/client.key”). | | enableHostVerification | boolean | false | Enable host verification for SSL/TLS (e.g., true). By default, host verification is disabled. | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # ClickHouse | MCP Toolbox for Databases ClickHouse ========== ClickHouse is an open-source, OLTP database. About ----- [ClickHouse](https://clickhouse.com/docs) is a fast, open-source, column-oriented database Available Tools --------------- * [`clickhouse-execute-sql`](https://mcp-toolbox.dev/v0.26.0/resources/tools/clickhouse/clickhouse-execute-sql/) Execute parameterized SQL queries in ClickHouse with query logging. * [`clickhouse-sql`](https://mcp-toolbox.dev/v0.26.0/resources/tools/clickhouse/clickhouse-sql/) Execute SQL queries as prepared statements in ClickHouse. Requirements ------------ ### Database User This source uses standard ClickHouse authentication. You will need to [create a ClickHouse user](https://clickhouse.com/docs/en/sql-reference/statements/create/user) (or with [ClickHouse Cloud](https://clickhouse.com/docs/getting-started/quick-start/cloud#connect-with-your-app) ) to connect to the database with. The user should have appropriate permissions for the operations you plan to perform. ### Network Access ClickHouse supports multiple protocols: * **HTTPS protocol** (default port 8443) - Secure HTTP access (default) * **HTTP protocol** (default port 8123) - Good for web-based access Example ------- ### Secure Connection Example sources: secure-clickhouse-source: kind: clickhouse host: clickhouse.example.com port: "8443" database: analytics user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} protocol: https secure: true ### HTTP Protocol Example sources: http-clickhouse-source: kind: clickhouse host: localhost port: "8123" database: logs user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} protocol: http secure: false Tip Use environment variable replacement with the format ${ENV\_NAME} instead of hardcoding your secrets into the configuration file. Reference --------- | **field** | **type** | **required** | **description** | | --- | --- | --- | --- | | kind | string | true | Must be “clickhouse”. | | host | string | true | IP address or hostname to connect to (e.g. “127.0.0.1” or “clickhouse.example.com”) | | port | string | true | Port to connect to (e.g. “8443” for HTTPS, “8123” for HTTP) | | database | string | true | Name of the ClickHouse database to connect to (e.g. “my\_database”). | | user | string | true | Name of the ClickHouse user to connect as (e.g. “analytics\_user”). | | password | string | false | Password of the ClickHouse user (e.g. “my-password”). | | protocol | string | false | Connection protocol: “https” (default) or “http”. | | secure | boolean | false | Whether to use a secure connection (TLS). Default: false. | Last modified November 14, 2025: [docs: update long lines and tables (#1952) (735cb760ea6)](https://github.com/googleapis/genai-toolbox/commit/735cb760ea6077965e99260bf6da5f0ee4d4e809) --- # Cloud SQL for MySQL Admin using MCP | MCP Toolbox for Databases Cloud SQL for MySQL Admin using MCP =================================== Create and manage Cloud SQL for MySQL (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for MySQL instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mysql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mysql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mysql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for MySQL using MCP. The `cloud-sql-mysql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for MySQL instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for MySQL instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) --- # Cloud SQL for SQL Server Admin using MCP | MCP Toolbox for Databases Cloud SQL for SQL Server Admin using MCP ======================================== Create and manage Cloud SQL for SQL Server (Admin) using Toolbox. This guide covers how to use [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox) to expose your developer assistant tools to create and manage Cloud SQL for SQL Server instance, database and users: * [Cursor](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Windsurf](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Codium) * [Visual Studio Code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (Copilot) * [Cline](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) (VS Code extension) * [Claude desktop](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Claude code](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini CLI](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) * [Gemini Code Assist](https://mcp-toolbox.dev/v0.30.0/how-to/connect-ide/cloud_sql_mssql_admin_mcp/#configure-your-mcp-client) Before you begin ---------------- 1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard) , select or create a Google Cloud project. 2. [Make sure that billing is enabled for your Google Cloud project](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project) . 3. Grant the necessary IAM roles to the user that will be running the MCP server. The tools available will depend on the roles granted: * `roles/cloudsql.viewer`: Provides read-only access to resources. * `get_instance` * `list_instances` * `list_databases` * `wait_for_operation` * `roles/cloudsql.editor`: Provides permissions to manage existing resources. * All `viewer` tools * `create_database` * `create_backup` * `roles/cloudsql.admin`: Provides full control over all resources. * All `editor` and `viewer` tools * `create_instance` * `create_user` * `clone_instance` * `restore_backup` Install MCP Toolbox ------------------- 1. Download the latest version of Toolbox as a binary. Select the [correct binary](https://github.com/googleapis/genai-toolbox/releases) corresponding to your OS and CPU architecture. You are required to use Toolbox version V0.15.0+: * linux/amd64 * darwin/arm64 * darwin/amd64 * windows/amd64 curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox.exe 2. Make the binary executable: chmod +x toolbox 3. Verify the installation: ./toolbox --version Configure your MCP Client ------------------------- * Claude code * Claude desktop * Cline * Cursor * Visual Studio Code (Copilot) * Windsurf * Gemini CLI * Gemini Code Assist 1. Install [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) . 2. Create a `.mcp.json` file in your project root if it doesn’t exist. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude code to apply the new configuration. 1. Open [Claude desktop](https://claude.ai/download) and navigate to Settings. 2. Under the Developer tab, tap Edit Config to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. Restart Claude desktop. 5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. 1. Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon. 2. Tap Configure MCP Servers to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. You should see a green active status after the server is successfully connected. 1. Create a `.cursor` directory in your project root if it doesn’t exist. 2. Create a `.cursor/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 4. [Cursor](https://www.cursor.com/) and navigate to **Settings > Cursor Settings > MCP**. You should see a green active status after the server is successfully connected. 1. Open [VS Code](https://code.visualstudio.com/docs/copilot/overview) and create a `.vscode` directory in your project root if it doesn’t exist. 2. Create a `.vscode/mcp.json` file if it doesn’t exist and open it. 3. Add the following configuration and save: { "servers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant. 2. Tap on the hammer (MCP) icon, then Configure to open the configuration file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini CLI](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quickstart) . 2. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 3. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } 1. Install the [Gemini Code Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist) extension in Visual Studio Code. 2. Enable Agent Mode in Gemini Code Assist chat. 3. In your working directory, create a folder named `.gemini`. Within it, create a `settings.json` file. 4. Add the following configuration and save: { "mcpServers": { "cloud-sql-mssql-admin": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","cloud-sql-mssql-admin","--stdio"], "env": { } } } } Use Tools --------- Your AI tool is now connected to Cloud SQL for SQL Server using MCP. The `cloud-sql-mssql-admin` server provides tools for managing your Cloud SQL instances and interacting with your database: * **create\_instance**: Creates a new Cloud SQL for SQL Server instance. * **get\_instance**: Gets information about a Cloud SQL instance. * **list\_instances**: Lists Cloud SQL instances in a project. * **create\_database**: Creates a new database in a Cloud SQL instance. * **list\_databases**: Lists all databases for a Cloud SQL instance. * **create\_user**: Creates a new user in a Cloud SQL instance. * **wait\_for\_operation**: Waits for a Cloud SQL operation to complete. * **clone\_instance**: Creates a clone of an existing Cloud SQL for SQL Server instance. * **create\_backup**: Creates a backup on a Cloud SQL instance. * **restore\_backup**: Restores a backup of a Cloud SQL instance. Note Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn’t affect most users. Last modified January 16, 2026: [feat(prebuilt/cloud-sql): Add restore backup tool for cloud sql (#2171) (00c3e6d8cba)](https://github.com/googleapis/genai-toolbox/commit/00c3e6d8cba54e2ab6cb271c7e6b378895df53e1) ---