Model Context Protocol (MCP) Server Configuration in HVE Core: A Complete Guide

HVE Core uses a .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 Workspace File

Configuration lives in a .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 contains:

{
  "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 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 (lines 90-129) into your .vscode/mcp.json. Remove unused servers and supply required inputs via the inputs section.

The full template structure:

{
  "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 (lines 63-70) defines this field.

Example agent front-matter:

---
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. 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, 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.

Practical Configuration Examples

Minimal GitHub-Only Setup

For teams working exclusively with GitHub repositories, use this minimal configuration:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Place this file at your workspace root under .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:

{
  "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:

---
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 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 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.
• 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 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. This field is validated against the schema located at scripts/linting/schemas/agent-frontmatter.schema.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}