Muistiinpano
Tämän sivun käyttö edellyttää valtuutusta. Voit yrittää kirjautua sisään tai vaihtaa hakemistoa.
Tämän sivun käyttö edellyttää valtuutusta. Voit yrittää vaihtaa hakemistoa.
Connect an existing Microsoft Foundry toolbox to GitHub Copilot in Visual Studio Code (VS Code) from the Foundry portal. The toolbox exposes its tools through one Model Context Protocol (MCP) endpoint, so you don't configure each tool separately in VS Code.
This article covers consuming a toolbox from Copilot Chat, not creating a toolbox or deploying a Foundry agent.
Prerequisites
- VS Code with GitHub Copilot set up and access to agent chat.
- A local workspace folder that you trust.
- An existing Foundry project and toolbox with a default version and at least one configured tool.
- A Microsoft Entra account with the Foundry User role on the project.
- Network access from VS Code to the toolbox endpoint. For private projects, see Network isolation for a toolbox.
Important
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
The example prompt in this article requires a toolbox with web search. If your toolbox has different tools, choose a read-only request that one of those tools supports.
Install the toolbox from Foundry
Use the portal's installation link to add the toolbox's remote HTTP endpoint to VS Code.
Open your project in the Foundry portal.
Select Build > Tools, and open the toolbox you want to use.
Select Install in VS Code. If your browser asks permission to open VS Code, allow it.
In VS Code, review the toolbox name and endpoint on the MCP server installation page.
Select Install in Workspace to add the connection to your open workspace.
Open
.mcp.jsonat the workspace root. Confirm that the toolbox appears under the top-levelmcpServersobject:{ "mcpServers": { "my-toolbox": { "type": "http", "url": "<toolbox-mcp-endpoint>" } } }In this example,
my-toolboxrepresents your toolbox's name, and<toolbox-mcp-endpoint>represents the URL supplied by the portal. Keep the actual values added by installation.Reference: VS Code MCP configuration.
This walkthrough uses workspace-root .mcp.json with mcpServers, not .vscode/mcp.json with servers. Don't create a duplicate entry in .vscode/mcp.json or copy the mcpServers object into that file.
The installation adds the toolbox URL, not a local copy of its tools. You don't need to paste an access token into the configuration. The consumer endpoint follows the toolbox's default version. For endpoint details, see Get the toolbox MCP endpoint.
Sign in and check the connection
Authentication to the toolbox uses your Microsoft Entra account, which is separate from the GitHub account you use for Copilot.
- Open the Command Palette with Ctrl+Shift+P, and run MCP: List Servers.
- Select the toolbox entry whose configuration source is your workspace-root
.mcp.json. If it isn't running, select Start Server. - Follow the Microsoft sign-in prompt. Use the account and tenant that have access to your Foundry project.
- Select Show Output for the toolbox and check that MCP initialization completes without authentication or connection errors.
- In Copilot Chat, confirm that the toolbox is available to the selected session. Use Configure Tools for Local sessions, or Chat: Open Customizations > Tools for Copilot sessions.
For a successful MCP connection, the server initializes and its tools become available in the selected session. A Running state alone isn't sufficient. If the toolbox doesn't appear, check that you opened the workspace containing .mcp.json and selected the intended session.
Call a toolbox tool from Copilot Chat
Start with a read-only request that explicitly names the toolbox. This approach helps you distinguish a toolbox result from Copilot's built-in tools or model knowledge.
Open Copilot Chat and select Agent.
Submit the following prompt, replacing
<toolbox-name>with your toolbox's name:Use the web search tool from <toolbox-name> to find the official VS Code documentation about MCP servers. Return the documentation link and a short summary. Use this toolbox, not another search tool. Don't change files or resources.If Copilot requests approval, review the tool name and arguments before allowing the read-only call.
Expand the tool call in the conversation. Confirm that it belongs to the toolbox configured in workspace-root
.mcp.jsonand returns a result rather than an authentication or connection error.Check that Copilot's answer uses the returned documentation and link.
Use these checks to verify a successful connection and tool call:
| Check | Expected result |
|---|---|
| Configuration source | The toolbox uses workspace-root .mcp.json under mcpServers, not a duplicate entry in .vscode/mcp.json. |
| MCP connection | Initialization succeeds, and the toolbox's tools are available to the selected session. |
| Tool execution | The expanded call identifies your toolbox and returns documentation search results without an error. |
| Copilot response | The answer summarizes the returned documentation and includes its link. |
A plausible answer without a successful tool call isn't sufficient. Keep the tool-call details visible when checking the result.
Understand downstream authentication
Signing in to the toolbox doesn't automatically sign you in to every service behind it. Each tool uses its configured authentication, such as a key, a service identity, or a separate user OAuth sign-in.
Direct toolbox clients can't use agent blueprint sign-in or AgentOnBehalfOfUser. A tool that requires per-user OAuth also requires the client to handle the authorization request and continue after sign-in. Don't assume every tool works in every MCP client. See Direct toolbox clients and agent-mediated access.
Troubleshoot
Run MCP: List Servers, select the toolbox, and select Show Output to inspect connection errors.
| Symptom | What to check |
|---|---|
| The browser doesn't open VS Code. | Confirm that VS Code is installed and that the browser allows the application link. |
| The toolbox isn't available in chat. | Check the selected session, workspace, configuration scope, and enabled tools. Review Workspace Trust if the workspace is in Restricted Mode. |
| The toolbox entry is missing or uses the wrong configuration. | Confirm that .mcp.json is at the workspace root and uses mcpServers. The separate .vscode/mcp.json format uses servers; don't mix the two schemas. |
| Sign-in fails or the endpoint returns HTTP 401 or 403. | Check the Microsoft Entra account, tenant, project role, and endpoint. Read the authentication error before retrying. |
| A tool requests additional authorization. | Review the tool's downstream authentication requirements. Toolbox sign-in alone doesn't satisfy a separate OAuth connection. |
| Copilot answers without calling the toolbox. | Name the toolbox and tool capability in your prompt, check that the tool is enabled, and inspect the tool call rather than only the final answer. |
For more diagnostics, see Manage and troubleshoot MCP servers in VS Code.
Remove the local connection
To stop using the toolbox in this workspace, run MCP: List Servers, select the toolbox, and select Uninstall if available. Otherwise, remove only that toolbox's entry from mcpServers in the workspace-root .mcp.json.
Removing the local MCP connection doesn't delete the toolbox or its versions in Foundry.
Related content
Learn more about managing the shared toolbox and its tools: