Connect VS Code to GateRook: your first read-only call

This walkthrough connects local VS Code desktop to a GateRook endpoint, makes one read-only PostgreSQL call, and verifies the call in Activity. It uses a constant-only query, so no table contents or business records are needed.

VS Code browser sign-in was introduced in GateRook 0.9.0. For a new installation, use the current download; 0.9.2 updates GateRook's public addresses.

Before you start

• Run GateRook and stable VS Code desktop on the same computer. Have GitHub Copilot's agent mode and MCP support available in VS Code.
• Use an existing, reachable development PostgreSQL database and an account with only the access it needs. GateRook does not bundle a demo database.
• Add and test that database in GateRook first. Follow the PostgreSQL guide if needed. This example calls the saved connection demo-db; substitute your actual connection name.
• Keep GateRook running throughout the walkthrough. Connect your VPN if the development database needs it.

Microsoft's consumer Copilot app is different from GitHub Copilot inside VS Code. This guide is for VS Code desktop, not that Store app or a remote development environment.

1. Create a narrow endpoint

Open Endpoints → Create endpoint. Use a recognizable slug such as vscode-demo, choose Read-only dev under Start from, and select only your development connection under Connections to add.

Create the endpoint, then open Tools & policies. Check that sql_query is Read only and sql_execute is Off. For this one-tool exercise, leave other tools Off too. Do not enable Bypass.

The two SQL tools have different roles: sql_query handles reads; sql_execute handles changes. The Read only setting is not available for the mutating sql_execute tool. Keep database-side permissions restricted as a second boundary.

2. Open the VS Code connection flow

In GateRook, open AI apps, find VS Code, and choose Connect. Select the vscode-demo endpoint.

GateRook opens VS Code's MCP server installation flow. Review the server name and endpoint URL, choose the intended VS Code profile, and confirm the installation there.

Use the URL generated by GateRook. Its local form is:

http://127.0.0.1:<core-port>/mcp/<endpoint-slug>

The listener port is installation-specific. Do not copy an example port from another computer or put a database password into VS Code's MCP configuration.

GateRook hands the server name, HTTP transport and URL to VS Code. It does not edit your VS Code mcp.json itself; VS Code owns the configuration, profile selection and server trust.

3. Start the server and finish browser sign-in

Start the installed GateRook MCP server in VS Code. Review any server-trust prompt, then follow the browser authorization flow.

Check that the consent request matches the endpoint you intended to expose before authorizing it. Return to VS Code and confirm that the server is running and its tools are available.

Installing the server is only the first step. The OAuth token exchange must finish before the connection is established. Database credentials stay in GateRook rather than being copied into the client configuration.

4. Check the small read in Playground

In GateRook's Playground, choose the same endpoint, development connection and sql_query. Use this query:

SELECT 1 AS connection_check;

Set the row limit to 1. The corresponding tool arguments are:

{
  "connection": "demo-db",
  "sql": "SELECT 1 AS connection_check",
  "limit": 1
}

Replace demo-db with your saved connection name. If that connection has more than one selected database, also provide the database argument with the intended database name.

Expect one row with connection_check equal to 1. This verifies the connection and policy before introducing the AI client.

5. Ask VS Code to make the same call

Open GitHub Copilot in agent mode and enable the GateRook sql_query tool for the conversation. Ask:

Use GateRook's sql_query tool on demo-db to run SELECT 1 AS connection_check with limit 1. Do not use the terminal, read tables, change data, or call another server.

Substitute your connection name and, when required, name the selected database. Review any VS Code tool confirmation before allowing the call.

The expected result is again one row containing connection_check: 1. A correct-looking chat answer alone does not prove that Copilot used GateRook; check Activity next.

6. Verify the call in Activity

Open Activity → Calls in GateRook and refresh if necessary. Find the call made after the VS Code prompt, rather than the earlier Playground test.

Check its timestamp, tool and connection, AI app or endpoint, decision and duration. Open the call details to inspect the request and result. Confirm that it used sql_query, your development connection, the constant-only SQL, and a successful result.

If there is no matching Activity call, the exercise has not demonstrated routing through GateRook. Check which tool Copilot used and repeat only the same small read after correcting the connection.

If something does not connect

• No tools in VS Code: confirm that OAuth finished, the server is running, the correct endpoint contains the connection, and sql_query is enabled. Reload the server's tool list if it is cached.
• The read is denied: inspect Activity and the endpoint policy. Verify that you selected sql_query, not sql_execute, and that the connection and selected database match.
• Playground also fails: check the database host, VPN, TLS settings, credentials and database-side permissions using the PostgreSQL guide.
• A remote VS Code session cannot connect: its loopback address may refer to a different machine. This local walkthrough does not establish remote access. Use a deliberately configured reachable endpoint and its authorization flow.
• You are finished with the demo: revoke its OAuth access in Settings → Authorization → Signed in, and remove the MCP server from VS Code separately if you no longer need it.

Where to go next

Keep the endpoint limited to the resources and tools needed for the next task. Allowed results return to the AI client, so a cloud model may process them on its provider's infrastructure even though GateRook runs locally.

Read Getting started for the wider endpoint and approval model, or choose another integration guide.