|
| 1 | +--- |
| 2 | +title: "Quickstart (MCP)" |
| 3 | +type: docs |
| 4 | +weight: 3 |
| 5 | +description: > |
| 6 | + How to get started running Toolbox locally with MCP Inspector. |
| 7 | +--- |
| 8 | + |
| 9 | +## Overview |
| 10 | +[Model Context Protocol](https://modelcontextprotocol.io) is an open protocol |
| 11 | +that standardizes how applications provide context to LLMs. Check out this page |
| 12 | +on how to [connect to Toolbox via MCP](../../how-to/connect_via_mcp.md). |
| 13 | + |
| 14 | +## Step 1: Set up your database |
| 15 | + |
| 16 | +In this section, we will create a database, insert some data that needs to be |
| 17 | +access by our agent, and create a database user for Toolbox to connect with. |
| 18 | + |
| 19 | +1. Connect to postgres using the `psql` command: |
| 20 | + |
| 21 | + ```bash |
| 22 | + psql -h 127.0.0.1 -U postgres |
| 23 | + ``` |
| 24 | + |
| 25 | + Here, `postgres` denotes the default postgres superuser. |
| 26 | + |
| 27 | +1. Create a new database and a new user: |
| 28 | + |
| 29 | + {{< notice tip >}} |
| 30 | + For a real application, it's best to follow the principle of least permission |
| 31 | + and only grant the privileges your application needs. |
| 32 | + {{< /notice >}} |
| 33 | +
|
| 34 | + ```sql |
| 35 | + CREATE USER toolbox_user WITH PASSWORD 'my-password'; |
| 36 | +
|
| 37 | + CREATE DATABASE toolbox_db; |
| 38 | + GRANT ALL PRIVILEGES ON DATABASE toolbox_db TO toolbox_user; |
| 39 | +
|
| 40 | + ALTER DATABASE toolbox_db OWNER TO toolbox_user; |
| 41 | + ``` |
| 42 | +
|
| 43 | +
|
| 44 | +
|
| 45 | +1. End the database session: |
| 46 | +
|
| 47 | + ```bash |
| 48 | + \q |
| 49 | + ``` |
| 50 | +
|
| 51 | +1. Connect to your database with your new user: |
| 52 | +
|
| 53 | + ```bash |
| 54 | + psql -h 127.0.0.1 -U toolbox_user -d toolbox_db |
| 55 | + ``` |
| 56 | +
|
| 57 | +1. Create a table using the following command: |
| 58 | +
|
| 59 | + ```sql |
| 60 | + CREATE TABLE hotels( |
| 61 | + id INTEGER NOT NULL PRIMARY KEY, |
| 62 | + name VARCHAR NOT NULL, |
| 63 | + location VARCHAR NOT NULL, |
| 64 | + price_tier VARCHAR NOT NULL, |
| 65 | + checkin_date DATE NOT NULL, |
| 66 | + checkout_date DATE NOT NULL, |
| 67 | + booked BIT NOT NULL |
| 68 | + ); |
| 69 | + ``` |
| 70 | +
|
| 71 | +1. Insert data into the table. |
| 72 | +
|
| 73 | + ```sql |
| 74 | + INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked) |
| 75 | + VALUES |
| 76 | + (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'), |
| 77 | + (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'), |
| 78 | + (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'), |
| 79 | + (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'), |
| 80 | + (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'), |
| 81 | + (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'), |
| 82 | + (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'), |
| 83 | + (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'), |
| 84 | + (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'), |
| 85 | + (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0'); |
| 86 | + ``` |
| 87 | +
|
| 88 | +1. End the database session: |
| 89 | +
|
| 90 | + ```bash |
| 91 | + \q |
| 92 | + ``` |
| 93 | +
|
| 94 | +## Step 2: Install and configure Toolbox |
| 95 | +
|
| 96 | +In this section, we will download Toolbox, configure our tools in a |
| 97 | +`tools.yaml`, and then run the Toolbox server. |
| 98 | +
|
| 99 | +1. Download the latest version of Toolbox as a binary: |
| 100 | +
|
| 101 | + {{< notice tip >}} |
| 102 | + Select the |
| 103 | + [correct binary](https://github.com/googleapis/genai-toolbox/releases) |
| 104 | + corresponding to your OS and CPU architecture. |
| 105 | + {{< /notice >}} |
| 106 | + <!-- {x-release-please-start-version} --> |
| 107 | + ```bash |
| 108 | + export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 |
| 109 | + curl -O https://storage.googleapis.com/genai-toolbox/v0.2.1/$OS/toolbox |
| 110 | + ``` |
| 111 | + <!-- {x-release-please-end} --> |
| 112 | +
|
| 113 | +1. Make the binary executable: |
| 114 | +
|
| 115 | + ```bash |
| 116 | + chmod +x toolbox |
| 117 | + ``` |
| 118 | +
|
| 119 | +1. Write the following into a `tools.yaml` file. Be sure to update any fields |
| 120 | + such as `user`, `password`, or `database` that you may have customized in the |
| 121 | + previous step. |
| 122 | +
|
| 123 | + ```yaml |
| 124 | + sources: |
| 125 | + my-pg-source: |
| 126 | + kind: postgres |
| 127 | + host: 127.0.0.1 |
| 128 | + port: 5432 |
| 129 | + database: toolbox_db |
| 130 | + user: toolbox_user |
| 131 | + password: my-password |
| 132 | + tools: |
| 133 | + search-hotels-by-name: |
| 134 | + kind: postgres-sql |
| 135 | + source: my-pg-source |
| 136 | + description: Search for hotels based on name. |
| 137 | + parameters: |
| 138 | + - name: name |
| 139 | + type: string |
| 140 | + description: The name of the hotel. |
| 141 | + statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; |
| 142 | + search-hotels-by-location: |
| 143 | + kind: postgres-sql |
| 144 | + source: my-pg-source |
| 145 | + description: Search for hotels based on location. |
| 146 | + parameters: |
| 147 | + - name: location |
| 148 | + type: string |
| 149 | + description: The location of the hotel. |
| 150 | + statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%'; |
| 151 | + book-hotel: |
| 152 | + kind: postgres-sql |
| 153 | + source: my-pg-source |
| 154 | + description: >- |
| 155 | + Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not. |
| 156 | + parameters: |
| 157 | + - name: hotel_id |
| 158 | + type: string |
| 159 | + description: The ID of the hotel to book. |
| 160 | + statement: UPDATE hotels SET booked = B'1' WHERE id = $1; |
| 161 | + update-hotel: |
| 162 | + kind: postgres-sql |
| 163 | + source: my-pg-source |
| 164 | + description: >- |
| 165 | + Update a hotel's check-in and check-out dates by its ID. Returns a message |
| 166 | + indicating whether the hotel was successfully updated or not. |
| 167 | + parameters: |
| 168 | + - name: hotel_id |
| 169 | + type: string |
| 170 | + description: The ID of the hotel to update. |
| 171 | + - name: checkin_date |
| 172 | + type: string |
| 173 | + description: The new check-in date of the hotel. |
| 174 | + - name: checkout_date |
| 175 | + type: string |
| 176 | + description: The new check-out date of the hotel. |
| 177 | + statement: >- |
| 178 | + UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3 |
| 179 | + as date) WHERE id = $1; |
| 180 | + cancel-hotel: |
| 181 | + kind: postgres-sql |
| 182 | + source: my-pg-source |
| 183 | + description: Cancel a hotel by its ID. |
| 184 | + parameters: |
| 185 | + - name: hotel_id |
| 186 | + type: string |
| 187 | + description: The ID of the hotel to cancel. |
| 188 | + statement: UPDATE hotels SET booked = B'0' WHERE id = $1; |
| 189 | + ``` |
| 190 | + For more info on tools, check out the `Resources` section of the docs. |
| 191 | + |
| 192 | +1. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: |
| 193 | + |
| 194 | + ```bash |
| 195 | + ./toolbox --tools_file "tools.yaml" |
| 196 | + ``` |
| 197 | + |
| 198 | +## Step 3: Connect to MCP Inspector |
| 199 | + |
| 200 | +1. Run the MCP Inspector: |
| 201 | + |
| 202 | + ```bash |
| 203 | + npx @modelcontextprotocol/inspector |
| 204 | + ``` |
| 205 | + |
| 206 | +1. Type `y` when it asks to install the inspector package. |
| 207 | + |
| 208 | +1. It should show the folo=lowing when the MCP Inspector is up and runnning: |
| 209 | + |
| 210 | + ```bash |
| 211 | + 🔍 MCP Inspector is up and running at http://127.0.0.1:5173 🚀 |
| 212 | + ``` |
| 213 | + |
| 214 | +1. Open the above link in your browser. |
| 215 | + |
| 216 | +1. For `Transport Type`, select `SSE`. |
| 217 | + |
| 218 | +1. For `URL`, type in `http://127.0.0.1:5000/mcp/sse`. |
| 219 | + |
| 220 | +1. Click Connect. |
| 221 | + |
| 222 | +  |
| 223 | + |
| 224 | +1. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. |
| 225 | + |
| 226 | +  |
| 227 | + |
| 228 | +1. Test out your tools here! |
0 commit comments