# Model Context Protocol (MCP) Server Configuration in HVE Core: A Complete Guide > Learn how to configure Model Context Protocol MCP servers in HVE Core using mcpjson to proxy external services like GitHub and Azure DevOps. Get a complete guide for Copilot agents. - Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core) - Tags: how-to-guide - Published: 2026-03-09 --- **HVE Core uses a [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json) file to configure Model Context Protocol servers that proxy external services like GitHub, Azure DevOps, and Microsoft Docs to Copilot-powered agents.** The `microsoft/hve-core` repository implements a flexible Model Context Protocol (MCP) server configuration system that allows agents to securely interact with external platforms. This configuration is optional and only required when agents declare dependencies on MCP tools for accessing resources outside the core environment. ## What Is the Model Context Protocol in HVE Core? The **Model Context Protocol (MCP)** is a standardized interface that allows AI agents to communicate with external service endpoints. In HVE Core, MCP servers act as proxies that expose capabilities from platforms like Azure DevOps work-items, GitHub issues, Microsoft Learn documentation, and Upstash Context7 to Copilot-powered agents. Only agents that explicitly declare MCP tools in their configuration require a server. Agents without MCP dependencies function out-of-the-box without any additional configuration. ## MCP Configuration File Structure and Location ### The [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json) Workspace File Configuration lives in a **[`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json)** file at the workspace root. VS Code reads this file automatically when the HVE Core extension is active. The repository ships with a default configuration that defines a single GitHub server. The default file at [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json) contains: ```json { "servers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" } } } ``` ## Supported MCP Servers and Connection Types HVE Core supports four curated MCP servers, each using either `stdio` (standard input/output) or `http` transport: | Server | Type | Package / URL | Purpose | |--------|------|---------------|---------| | **context7** | `stdio` | `@upstash/context7-mcp` | Library and SDK documentation lookup | | **microsoft-docs** | `http` | `https://learn.microsoft.com/api/mcp` | Microsoft Learn documentation access | | **ado** (Azure DevOps) | `stdio` | `@azure-devops/mcp` | Work-item, pipeline, and repository access (requires organization name and optional tenant) | | **github** | `http` | `https://api.githubcopilot.com/mcp/` | Repository and issue management on GitHub | This table is documented in [`docs/getting-started/mcp-configuration.md`](https://github.com/microsoft/hve-core/blob/main/docs/getting-started/mcp-configuration.md) at lines 49-87. ## Configuring MCP Servers for Custom Agents ### Step 1: Select Your Integration Platform Decide which platform you need. The documentation recommends choosing either the **GitHub** server or the **ADO** server, depending on your primary platform. You only need both if you work across platforms simultaneously. ### Step 2: Define Server Connections and Inputs Copy the configuration template from [`docs/getting-started/mcp-configuration.md`](https://github.com/microsoft/hve-core/blob/main/docs/getting-started/mcp-configuration.md) (lines 90-129) into your [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json). Remove unused servers and supply required inputs via the `inputs` section. The full template structure: ```json { "inputs": [ { "id": "ado_org", "type": "promptString", "description": "Azure DevOps organization name (e.g. 'contoso')", "default": "" }, { "id": "ado_tenant", "type": "promptString", "description": "Azure tenant ID (required for multi-tenant scenarios)", "default": "" } ], "servers": { "context7": { "type": "stdio", "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }, "microsoft-docs": { "type": "http", "url": "https://learn.microsoft.com/api/mcp" }, "ado": { "type": "stdio", "command": "npx", "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--tenant", "${input:ado_tenant}", "-d", "core", "work", "work-items", "search", "repositories", "pipelines"] }, "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" } } } ``` ### Step 3: Declare MCP Dependencies in Agent Front Matter Custom agents declare required MCP servers in their front-matter using the `mcp-servers` field. The JSON schema at [`scripts/linting/schemas/agent-frontmatter.schema.json`](https://github.com/microsoft/hve-core/blob/main/scripts/linting/schemas/agent-frontmatter.schema.json) (lines 63-70) defines this field. Example agent front-matter: ```markdown --- name: github-backlog-manager description: Manage GitHub backlogs via Copilot tools: - github-issues - github-milestones mcp-servers: - github --- ``` When the agent runs, Copilot resolves the named server from [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json). If the server is missing, the agent reports "MCP tool unavailable" and continues gracefully. ## Runtime Execution and Error Handling When an agent invokes an MCP tool (such as `ado-search-work-items`), Copilot reads the corresponding entry from [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json), launches the configured command or HTTP endpoint, and streams results back to the agent. If the server is unreachable, the agent falls back to a user-friendly error message and optionally suggests configuration steps. This behavior is documented in the Troubleshooting section of [`docs/getting-started/mcp-configuration.md`](https://github.com/microsoft/hve-core/blob/main/docs/getting-started/mcp-configuration.md). ## Practical Configuration Examples ### Minimal GitHub-Only Setup For teams working exclusively with GitHub repositories, use this minimal configuration: ```json { "servers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" } } } ``` Place this file at your workspace root under [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json); the VS Code extension will detect it automatically. ### Azure DevOps Integration with User Inputs For Azure DevOps workflows, configure user prompts for organization and tenant details: ```json { "inputs": [ { "id": "ado_org", "type": "promptString", "description": "Azure DevOps organization name", "default": "contoso" } ], "servers": { "ado": { "type": "stdio", "command": "npx", "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "-d", "core"] }, "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" } } } ``` This configuration enables agents like `ado-prd-to-wit` to resolve work items through the ADO server. ### Agent Front-Matter Declaration Link your agents to specific MCP servers by declaring them in the agent's metadata: ```markdown --- name: github-backlog-manager description: Manage GitHub backlogs via Copilot tools: - github-issues - github-milestones mcp-servers: - github --- ``` The `mcp-servers` array tells Copilot to load the `github` configuration from [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json) when this agent executes. ## Summary - **Model Context Protocol (MCP) server configuration in HVE Core** is optional and only required for agents that integrate with external services like GitHub or Azure DevOps. - Configuration resides in [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json) at the workspace root, which VS Code reads automatically when the HVE Core extension is active. - HVE Core supports four curated servers: **context7**, **microsoft-docs**, **ado**, and **github**, using either `stdio` or `http` transport mechanisms. - Agents declare MCP dependencies in their front-matter using the `mcp-servers` field, validated against the JSON schema in [`scripts/linting/schemas/agent-frontmatter.schema.json`](https://github.com/microsoft/hve-core/blob/main/scripts/linting/schemas/agent-frontmatter.schema.json). - Runtime resolution is graceful; if a server is unavailable, agents report "MCP tool unavailable" and continue execution without crashing. ## Frequently Asked Questions ### Where does the MCP server configuration file live in HVE Core? The configuration file must be placed at [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json) in your workspace root. VS Code automatically detects and loads this file when the HVE Core extension activates, requiring no additional import statements or manual registration. ### Do all agents in HVE Core require MCP server configuration? No. MCP configuration is strictly optional. Only agents that declare tools requiring external platform access—such as Azure DevOps work items or GitHub issues—need a configured server. Agents operating solely within the core environment function without any MCP setup. ### How do I declare that an agent depends on a specific MCP server? Add the `mcp-servers` array to your agent's front-matter metadata. For example, include `mcp-servers: [github]` to bind an agent to the GitHub server defined in [`.vscode/mcp.json`](https://github.com/microsoft/hve-core/blob/main/.vscode/mcp.json). This field is validated against the schema located at [`scripts/linting/schemas/agent-frontmatter.schema.json`](https://github.com/microsoft/hve-core/blob/main/scripts/linting/schemas/agent-frontmatter.schema.json).