VS Code

VS Code's MCP support ships in GitHub Copilot agent mode (and other extensions that have adopted the spec). Configuration lives in .vscode/mcp.json (per workspace) or in your user settings (global). vTilt's MCP server speaks the same Streamable HTTP transport every other remote MCP server does, so configuration is one block of JSON.

#1. Add the workspace config

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "vtilt": {
      "type": "http",
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET"
      }
    }
  }
}

Reload VS Code (or run Developer: Reload Window from the command palette). The Copilot Chat side-panel should pick up the new server within a couple of seconds — open the MCP drop-down to see it listed.

#2. Pin a project (multi-project users only)

Add x-vtilt-project-id to the headers map:

{
  "servers": {
    "vtilt": {
      "type": "http",
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET",
        "x-vtilt-project-id": "YOUR_PROJECT_ID"
      }
    }
  }
}

Single-project accounts don't need to pin — the server auto-pins.

#Parallel chats with one key (x-vtilt-mcp-session-id)

When several agent sessions share the same bearer token, add a distinct UUID per server entry in headers so switch-project pins do not overwrite each other (see Cursor — section on parallel chats and x-vtilt-mcp-session-id):

"x-vtilt-mcp-session-id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"

#3. Use it from Copilot Chat

Switch Copilot to Agent mode (the dropdown next to the chat input) and ask:

What vTilt tools are available, and what does each do?

Copilot will call tools/list and summarise. Then try a real query:

Pull the most recent 30 events for my vTilt project and tell
me which event name appears most often, with counts.

Copilot calls events-recent and writes the summary. The agent picks the tools — you don't need to name them.

#4. Per-user (global) config

If you want vTilt available in every workspace, put the same mcp.json block in your user-level config. From the command palette: MCP: Open User Configuration File.

#5. Mixing with other MCP servers

VS Code merges every server in your config into a single tool list. To keep the agent focused, you can filter vTilt down to a feature subset:

{
  "servers": {
    "vtilt-analytics-only": {
      "type": "http",
      "url": "https://www.vtilt.com/api/mcp?features=analytics",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET",
        "x-vtilt-project-id": "YOUR_PROJECT_ID"
      }
    }
  }
}

Both ?features= and ?tools= apply with union semantics — a tool survives if it matches either.

#Troubleshooting

• vTilt doesn't appear in the MCP drop-down — the JSON file is malformed or VS Code didn't reload. Run Developer: Reload Window and check the Output panel → MCP.
• "Unauthorized" — bearer header is missing, malformed, revoked, or expired. See the error table.
• "Forbidden — project_not_accessible" — x-vtilt-project-id points at a project you can't access. Remove the header or pick a project from your dashboard.
• Tools work but agent never calls them — make sure Copilot is in Agent mode, not the regular chat mode (regular chat doesn't invoke MCP tools).

#Next steps

• Authentication — full key lifecycle and error reference.
• MCP server overview — the seven phase-1 tools and example prompts.
• Cursor / Claude Desktop / Codex — same key, different client.