VS Code Copilot agent mode: MCP tools not showing, or the server won't start

Check which harness the session uses

VS Code shows the active harness as a prefix in the chat title, and in the Agents window as the watermark in the chat input. The Copilot harness runs on the Copilot SDK in the Agent Host, and VS Code's docs suggest it for day-to-day work. Local is VS Code's built-in agent in the extension host. You choose one under Session Target before the first prompt, and the session keeps it.

• VS Code format: .vscode/mcp.json in the workspace, or the mcp.json in your user profile (MCP: Open User Configuration), with a top-level servers object. It supports ${env:NAME}, envFile, input variables and per-server sandboxing. The guided flow labels these destinations deprecated.
• Portable Copilot format: .mcp.json at the workspace root, or $COPILOT_HOME/mcp-config.json for your user, falling back to ~/.copilot/mcp-config.json. It uses a top-level mcpServers object and ${NAME} or ${NAME:-default} references.
• Copilot harness sessions read the portable files directly. VS Code forwards eligible servers from the VS Code format, but not servers that need interactive input such as ${input:...}. Entering the secret in a Local session first doesn't change that.
• The two formats aren't interchangeable: servers in one, mcpServers in the other, and different variable syntax. Check each field before you copy an entry across.

{
  "mcpServers": {
    "my-remote": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${MY_SERVICE_TOKEN}" }
    }
  }
}

The server won't start

Run MCP: List Servers, pick the server and choose Show Output, or use Show Output from the server's ... menu under Chat: Open Customizations > MCP Servers. The output channel shows why it failed. The same menu has Start, Stop, Restart, Enable and Disable.

• A stdio command has to be on the PATH of the machine that runs it, or written as a full path. In a remote window or dev container it runs on the remote side, so install its runtime there.
• Workspace .vscode/mcp.json and .mcp.json servers follow Workspace Trust, so they don't start in Restricted Mode. Servers from other sources can ask for their own trust; MCP: Reset Trust clears those decisions.
• A Docker server has to stay in the foreground. Remove -d from its args.
• A disabled server doesn't start and its tools stay unavailable. Disabled is a separate state from stopped, and it can apply globally, to the workspace or to the session.
• An enterprise or organization can turn off MCP servers for Copilot or allow only listed ones. Local configuration can't override that, so ask your admin.

Running, but the agent has no tools

• VS Code caches each server's tool list. After a server adds tools, run MCP: Reset Cached Tools and start a new chat.
• Tools are switched on and off per session. In a Copilot session, open Chat: Open Customizations > Tools; in a Local session, use Configure Tools in the chat input. Type # in the chat box to browse what's available.
• A request can have at most 128 tools. Past that, VS Code shows "Cannot have more than 128 tools per request." Deselect tools or whole servers, or turn on virtual tools with github.copilot.chat.virtualTools.threshold.
• In the Copilot harness, the Ask agent uses read-only tools only. Pick Agent for work that changes things.
• Tools listed but never called? Name the server in your prompt, then expand the tool call in the chat to check which server answered and what it returned.

Sign-in and credentials

• A server that signs in with OAuth prompts you when it starts: complete the browser sign-in and review what it asks for. In the VS Code format, an oauth object with clientId covers servers that need a registered client, and the Set Client Secret CodeLens above it stores a secret.
• The Copilot harness can't pass an ${input:...} secret or a value from VS Code's secret storage into an HTTP header. For a fixed API key there, reference an environment variable in the portable file.
• Portable files don't read envFile. Set the variable in the environment VS Code runs in, or on the remote host for a remote session.

Taskhold-specific checks

Taskhold is a remote server at https://taskhold.com/api/mcp. When the taskhold tools don't show up in VS Code, check these in order:

1. The config matches the harness. The VS Code page now uses the ~/.copilot/mcp-config.json entry below, which Copilot harness sessions read. An older .vscode/mcp.json entry that asks for the key with ${input:taskhold-key} only works in Local sessions, because servers that need input aren't forwarded to the Copilot harness.
2. The header is Authorization: Bearer followed by a key that starts with atd_sk_. Show Output on the server shows the error, and Taskhold's 401 names the cause: missing_key, bad_header, not_a_taskhold_key or unknown_key.
3. Sign-in without a key (OAuth) is set up for Claude Code, Cursor, Codex, claude.ai and ChatGPT. In VS Code, send the key in the header. With no header, the taskhold tools can still list, but every call comes back 401 missing_key.
4. A 402 means the key works but the trial ended or the plan was canceled. Restart the plan and the same config works again.
5. Connected a while ago? Run MCP: Reset Cached Tools so newer tools such as taskhold_begin and taskhold_updates appear. Settings in Taskhold shows Connected after the first call.

{
  "mcpServers": {
    "taskhold": {
      "type": "http",
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer ${TASKHOLD_API_KEY}" }
    }
  }
}

With the tools loaded and the workflow snippet from the VS Code page in AGENTS.md or .github/copilot-instructions.md, every task agent mode starts, its steps and its questions show on the live board. The same checks for other clients: Cursor, Windsurf and Claude Code.