Hook Local Sts Into Mssql
Apps & Automationhook-local-sts-into-mssqlHook Local Sts Into Mssql is an Agent Skill for apps & automation published in the microsoft/sqltoolsservice repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Wire a locally-published SQL Tools Service (STS) build into the vscode-mssql by setting MSSQL_SQLTOOLSSERVICE in launch.json. Use when: testing local STS changes in vscode-mssql, hooking up locally-built STS to MSSQL, debugging STS from VS Code, "use my local STS in MSSQL", "point MSSQL at local STS", "hook up STS to MSSQL", "set MSSQL_SQLTOOLSSERVICE". Assumes STS has already been local-published (see the `local-publish-sts` skill).
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/microsoft/sqltoolsservice/blob/HEAD/.github/skills/hook-local-sts-into-mssql/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/hook-local-sts-into-mssql, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Hook local STS into vscode-mssql
Update vscode-mssql's launch.json to point its Extension Development Host at a locally-published STS via the MSSQL_SQLTOOLSSERVICE environment variable.
After this, launching a debug session of the MSSQL extension uses your local STS instead of the bundled one.
When to use
- The user just built STS (or asks you to) and wants to test it in the MSSQL extension.
- The user says "use my local STS in MSSQL", "point MSSQL at local STS", "hook up local STS", "set
MSSQL_SQLTOOLSSERVICE", or "set the STS env var". - The MSSQL repo may or may not be in the same workspace as STS; this skill handles both cases.
Prerequisite
The STS publish folder must exist. If it doesn't, run the local-publish-sts skill first (or instruct the user to). The path you will need is:
<sts-repo-root>/artifacts/publish/Microsoft.SqlTools.ServiceLayer/default/net10.0
or similar (e.g. if .NET has been updated)
Procedure
Step 1 — Locate the STS publish folder
If the current working directory is an STS clone, derive the path from there. Otherwise ask the user for the STS repo root via ask_user.
Confirm the folder exists and contains MicrosoftSqlToolsServiceLayer.exe (Windows) or MicrosoftSqlToolsServiceLayer (Linux/macOS).
If missing, stop and tell the user they need to local-publish first (and offer to run it for them).
Step 2 — Locate the vscode-mssql repo
The agent may not have direct access to the MSSQL repo. Check, in this order:
- Sibling directory of the STS repo (
<sts-repo-parent>/vscode-mssql/). This is the most common layout. - Open editor workspace folders — check any
.code-workspacefile or${workspaceFolder}references that point at a vscode-mssql clone. - Common defaults:
~/Source/vscode-mssql/,~/source/repos/vscode-mssql/,~/code/vscode-mssql/,~/repos/vscode-mssql/.
The folder name mssql may also be used for vscode-mssql.
If none match, use ask_user to prompt for the absolute path to their vscode-mssql repo root. Do not guess silently.
Validate it's a real vscode-mssql clone before continuing; the repo should contain both extensions/mssql/package.json and .vscode/launch.json.
Step 3 — Update both launch.json files
vscode-mssql has two relevant launch.json files. Update both so the environment variable is set
whether the user opens the repo root or the extensions/mssql folder as their workspace:
| Path (relative to vscode-mssql root) | Active when… | Configurations |
|---|---|---|
.vscode/launch.json | Repo root is the workspace folder | "Run All Extensions" |
extensions/mssql/.vscode/launch.json | extensions/mssql is the workspace folder | "Launch Extension", "Launch Extension (With Other Extensions Disabled)" |
For every launch configuration in both files, set MSSQL_SQLTOOLSSERVICE inside the env block.
The shipped template typically has a commented-out placeholder:
// "MSSQL_SQLTOOLSSERVICE": "<Path to STS>"
Replace that line (uncommented) with the absolute STS publish path. If
no placeholder exists, add the entry to the existing env object.
"env": {
"MSSQL_SQLTOOLSSERVICE": "c:\\path\\to\\sqltoolsservice\\artifacts\\publish\\Microsoft.SqlTools.ServiceLayer\\default\\net10.0"
// Other env entries (e.g. MSSQL_SQLTOOLS_MCP); preserve any that are present
}
Path formatting rules:
- Use an absolute path.
${workspaceFolder}-relative paths break whenever the STS repo lives outside the launched workspace (which is always when the two repos are sibling directories). - On Windows, JSON requires either
\\or/as the path separator (single\is an invalid escape). Either works for VS Code. - Preserve any other entries already in the
envobject (e.g.MSSQL_SQLTOOLS_MCP, telemetry flags); only touchMSSQL_SQLTOOLSSERVICE.
Reference for the env var: https://github.com/microsoft/vscode-mssql/blob/main/DEVELOPMENT.md#using-mssql_sqltoolsservice-environment-variable
Step 4 — Verify and report
- Resolve the exact path you wrote and confirm it exists:
Test-Path "<the configured absolute path>/MicrosoftSqlToolsServiceLayer[.exe for Windows]" - Re-read both launch.json files and confirm
MSSQL_SQLTOOLSSERVICEshows up with the right value in every config'senvblock. - Tell the user:
- ✅ Both launch.json files updated with
MSSQL_SQLTOOLSSERVICE. - Which configurations now use the local STS.
- That they need to re-run the
local-publish-stsskill after each STS code change and stop any running EDH first to release file locks before re-publishing.
- ✅ Both launch.json files updated with
Common pitfalls
- Only updating one launch.json. The repo-root file and the
extensions/mssql/.vscode/file each ship with different launch configurations. If you only update one, F5 will silently fall back to the bundled STS when the user opens the "wrong" workspace folder. - Forgetting to escape backslashes in the JSON string.
"c:\Users\..."is invalid JSON. - Pointing at
…/Debug/net10.0/instead of…/publish/…/default/net10.0/. Thebin/Debugoutput isn't a published runnable; only theartifacts/publish/Microsoft.SqlTools.ServiceLayer/default/net10.0folder is. - Pointing at the wrong STS clone's artifact output stale path if the user has multiple STS clones. The user means to use the clone that this skill resides in.