MCP Servers

Purpose and Scope

Model Context Protocol, or MCP, is the mechanism VS Code uses to connect AI chat and agent experiences to external tools, resources, prompts, and services. In the product workflow, an MCP server can be installed from the MCP server gallery or configured in an mcp.json file, then made available to chat so the model can invoke server-provided tools. This page focuses on the repository-backed pieces that make that concept concrete: Codex MCP server inventory handling and the Copilot customization references that let prompts and agents name MCP-backed tools.

The important distinction for developers is that MCP servers are not the same thing as local built-in tool aliases. Built-in aliases such as read, search, edit, or execute describe VS Code and Copilot capabilities that are already known to the agent environment. MCP tools come from a named external server and are referenced by server-qualified patterns such as <server>/* in customization files. That separation lets a workspace give an agent access to a purpose-built external system without granting every local capability at the same time.

Sources: src/vs/platform/agentHost/node/codex/codexMcpServers.ts, extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md, extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md

Relevant Source Files

src/vs/platform/agentHost/node/codex/codexMcpServers.ts defines the Codex-side MCP inventory entry shape and the translation helpers that convert Codex MCP server state, tools, resources, and resource templates into the SDK-neutral data consumed by the agent host customization surface.
extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md documents custom agent frontmatter, including tools entries that may select MCP server tools with <server>/*, plus invocation controls, subagent fields, and inline hook examples.
extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md documents prompt-file frontmatter, including tools entries that can combine built-in tools, tool sets, MCP server tools, and extension tools for a reusable chat task.
extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md documents deterministic lifecycle hooks that can enforce policy before and after tool use, which is the relevant approval boundary around MCP-capable autonomous workflows.
extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md documents file-specific instructions loaded by description or applyTo patterns, which complement MCP tools by guiding when and how an agent should use capabilities.
extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md documents project-wide agent instructions in .github/copilot-instructions.md or AGENTS.md, which establish shared workspace policy for all chat requests.

Configuration Model

User-facing VS Code documentation describes MCP server configuration in mcp.json, either in a workspace at .vscode/mcp.json or in the user profile. The configuration has three main areas: servers, which maps server names to connection definitions; inputs, which supplies reusable variables for sensitive values such as API keys; and sandbox, which defines file-system and network access rules for sandboxed servers on supported platforms. Stdio servers are the common local form and typically declare a type, command, optional args, optional cwd, and environment configuration.

A practical workspace configuration usually starts small: add one named server, verify that VS Code can start it, then let the Chat view discover its tools. Once the server is trusted and running, the tool picker can show the server’s available tools so users can turn individual tools on or off. In customization files, the same server identity becomes the namespace used by agents or prompts. For example, a custom research agent can grant read and search locally while adding playwright/* or another server-qualified MCP tool pattern for browser or service-specific actions.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md, extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md

System-to-Code Mapping

The Codex integration code treats each MCP server as an inventory entry with a lifecycle state and three read-only payload groups: tools, resources, and resource templates. The ICodexMcpServerEntry interface captures that shape. Its comments explain that the state drives the agent host protocol customization surface, while cached tool and resource payloads back MCP list methods such as tools/list, resources/list, and resources/templates/list without forcing a round trip to Codex for every read. That design makes MCP availability visible to the host while keeping the richer server payloads in an inventory cache.

translateCodexMcpStartupState converts Codex startup lifecycle strings into the common McpServerState union. A ready server becomes McpServerStatus.Ready, starting becomes McpServerStatus.Starting, failed becomes McpServerStatus.Error with an mcp-server-failed error type, and cancelled or unknown statuses become McpServerStatus.Stopped. The source comments also call out a V1 boundary: Codex auth states are not surfaced as McpServerStatus.AuthRequired; a connected server is reported as ready regardless of its Codex auth status.

Sources: src/vs/platform/agentHost/node/codex/codexMcpServers.ts

Execution Flow

When Codex reports an MCP status list, the host code normalizes it into stable structures before exposing it to the customization layer. codexToolMapToArray flattens the Codex tools map into an array, drops missing entries allowed by the map type, and sorts the resulting tools by name. codexMcpStatusToEntry then marks a listed server as ready and attaches the sorted tools, resources, and resource templates. Finally, codexMcpListToInventory builds a Map keyed by server name, which gives the rest of the agent host a predictable snapshot of available servers.

That flow matters because agent customization needs a lightweight, server-level view as well as a detailed inventory. Custom agents and prompt files generally specify which capabilities they may use, not the full schema of every tool. The Codex cache keeps the server payloads available for list operations, while the customization controller can consume a neutral list of MCP servers and states. In effect, configuration and trust make the server available, Codex reports its inventory, and customization files decide which agents or prompts should receive access to named capabilities.

Customization and Approval Boundaries

MCP access becomes especially useful when combined with custom agents. A .agent.md file can define a persona, model preference, subagent behavior, and a minimal tool set. The reference examples show tools: [myserver/*] for an MCP-only agent, tools: [read, search] for read-only research, and tools: [] for conversational-only behavior. This is the right place to restrict an agent to a server-specific surface, for example giving a browser-testing agent only Playwright MCP tools instead of broad terminal access.

Prompt files provide a lighter-weight task template with similar tool selection. Their frontmatter can choose an agent, model, argument hint, and tools, and the documented priority order applies prompt tools before tools from a referenced custom agent and then default tools for the selected agent. Instructions files and project-wide agent instructions do not grant tools by themselves; they guide behavior. Use them to document when an MCP server should be used, what data boundaries apply, or which workflows require confirmation before invoking service-backed tools.

Hooks are the deterministic counterpart to these guidance files. The hooks reference defines lifecycle events such as PreToolUse and PostToolUse, and it describes permission decisions of allow, ask, and deny in hook output. That makes hooks the repository-documented place to enforce approval policy around tool invocation, including MCP tool use. Instructions can say “ask before modifying external systems,” but a PreToolUse hook can turn that into an auditable runtime decision before the agent proceeds.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md, extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md, extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md

Compact Reference

Area	Concrete names	Repository-backed behavior
Codex inventory entry	`ICodexMcpServerEntry`	Holds `state`, `tools`, `resources`, and `resourceTemplates` for one MCP server.
Startup translation	`translateCodexMcpStartupState(status, error)`	Maps `ready`, `starting`, `failed`, and `cancelled` into `McpServerStatus` states.
Tool normalization	`codexToolMapToArray(tools)`	Converts a name-keyed Codex tool map into a sorted `Tool[]`.
Inventory construction	`codexMcpStatusToEntry(status)`, `codexMcpListToInventory(data)`	Converts listed Codex servers into ready entries and then into a name-keyed `Map`.
Custom agent MCP access	`tools: [myserver/*]`	Grants a custom agent access to tools from a named MCP server pattern.
Prompt MCP access	`tools: [search, web]` or MCP patterns	Lets a reusable prompt choose its tool set, with prompt tools taking priority over agent defaults.
Approval boundary	`PreToolUse`, `PostToolUse` hooks	Lets hook commands ask, allow, deny, or block around tool invocation.

Next Steps

To add an MCP server as a user, start from the VS Code MCP management flow: install a server from the gallery or define it in mcp.json, trust it, and verify that its tools appear in chat. To wire it into a repeatable workflow, create a custom agent or prompt file with the narrowest possible tools list, using <server>/* only where that agent truly needs external capabilities. For team policy, pair the tool grant with concise project instructions and use hooks when an approval rule must be enforced rather than merely suggested.

Related pages: Custom Agents, Skills, and Prompts; Chat Tools and Approvals; Instructions and Agent Customization; Agent Hooks and Plugins

Ask a question...