Document VS Code WorkIQ MCP OAuth configuration

plugins/workiq-preview/README.md

@@ -12,7 +12,12 @@ Full WorkIQ tool surface for GitHub Copilot CLI: agentic semantic queries via `a
 
 ### Via MCP Configuration
 
-Add to your `.mcp.json` or IDE MCP settings:
+The hosted WorkIQ endpoint can be configured in different MCP hosts with different JSON shapes. Use the schema supported by your client:
+
+- GitHub Copilot CLI: `.mcp.json` uses `mcpServers` / `oauthClientId` / `oauthPublicClient`
+- VS Code: `mcp.json` uses `servers` and an `oauth.clientId` object; `oauthPublicClient` and `auth.redirectPort` are not valid in the VS Code schema
+
+GitHub Copilot CLI example:
 
 ```json
 {
@@ -30,6 +35,24 @@ Add to your `.mcp.json` or IDE MCP settings:
 }
 ```
 
+VS Code example:
+
+```json
+{
+  "servers": {
+    "workiq-preview": {
+      "type": "http",
+      "url": "https://workiq.svc.cloud.microsoft/mcp",
+      "oauth": {
+        "clientId": "ba081686-5d24-4bc6-a0d6-d034ecffed87"
+      }
+    }
+  }
+}
+```
+
+> If VS Code shows a `platform_broker_error` loop or `401 InvalidAuthenticationToken` with an empty bearer token, remove any stale `oauthPublicClient` / `auth.redirectPort` entries and re-run the VS Code OAuth flow using the `servers` + `oauth.clientId` shape above.
+
 The plugin connects to the hosted WorkIQ MCP prod endpoint. It does **not** launch a local MCP server for tool calls.
 
 ## Updating

plugins/workiq-preview/skills/workiq-preview/SKILL.md

@@ -127,7 +127,9 @@ Common failure: fetching the entity and stopping, asking the user "did you want
 
 ## Prerequisites
 
-WorkIQ MCP tool calls use the hosted prod endpoint configured in `.mcp.json`:
+WorkIQ MCP tool calls use the hosted prod endpoint configured in your MCP host settings. The schema differs by host:
+
+GitHub Copilot CLI example:
 
 ```json
 {
@@ -145,6 +147,24 @@ WorkIQ MCP tool calls use the hosted prod endpoint configured in `.mcp.json`:
 }
 ```
 
+VS Code example:
+
+```json
+{
+  "servers": {
+    "workiq-preview": {
+      "type": "http",
+      "url": "https://workiq.svc.cloud.microsoft/mcp",
+      "oauth": {
+        "clientId": "ba081686-5d24-4bc6-a0d6-d034ecffed87"
+      }
+    }
+  }
+}
+```
+
+> In VS Code, do not include `oauthPublicClient` or `auth.redirectPort` in the server definition. Using the CLI shape in VS Code can trigger the platform broker flow to fail with `401 InvalidAuthenticationToken` and an empty bearer token.
+
 No local package or runtime install is required for MCP tool calls. Do not block MCP tool usage on local machine prerequisites.
 
 ## Configuration

plugins/workiq/README.md

@@ -12,7 +12,12 @@ Full WorkIQ tool surface for GitHub Copilot CLI: agentic semantic queries via `a
 
 ### Via MCP Configuration
 
-Add to your `.mcp.json` or IDE MCP settings:
+The hosted WorkIQ endpoint can be configured in different MCP hosts with different JSON shapes. Use the schema supported by your client:
+
+- GitHub Copilot CLI: `.mcp.json` uses `mcpServers` / `oauthClientId` / `oauthPublicClient`
+- VS Code: `mcp.json` uses `servers` and an `oauth.clientId` object; `oauthPublicClient` and `auth.redirectPort` are not valid in the VS Code schema
+
+GitHub Copilot CLI example:
 
 ```json
 {
@@ -30,6 +35,24 @@ Add to your `.mcp.json` or IDE MCP settings:
 }
 ```
 
+VS Code example:
+
+```json
+{
+  "servers": {
+    "workiq": {
+      "type": "http",
+      "url": "https://workiq.svc.cloud.microsoft/mcp",
+      "oauth": {
+        "clientId": "ba081686-5d24-4bc6-a0d6-d034ecffed87"
+      }
+    }
+  }
+}
+```
+
+> If VS Code shows a `platform_broker_error` loop or `401 InvalidAuthenticationToken` with an empty bearer token, remove any stale `oauthPublicClient` / `auth.redirectPort` entries and re-run the VS Code OAuth flow using the `servers` + `oauth.clientId` shape above.
+
 The plugin connects to the hosted WorkIQ MCP prod endpoint. It does **not** launch a local MCP server for tool calls.
 
 ## Updating

plugins/workiq/skills/workiq/SKILL.md

@@ -172,7 +172,9 @@ Common failure: fetching the entity and stopping, asking the user "did you want
 
 ## Prerequisites
 
-WorkIQ MCP tool calls use the hosted prod endpoint configured in `.mcp.json`:
+WorkIQ MCP tool calls use the hosted prod endpoint configured in your MCP host settings. The schema differs by host:
+
+GitHub Copilot CLI example:
 
 ```json
 {
@@ -190,6 +192,24 @@ WorkIQ MCP tool calls use the hosted prod endpoint configured in `.mcp.json`:
 }
 ```
 
+VS Code example:
+
+```json
+{
+  "servers": {
+    "workiq": {
+      "type": "http",
+      "url": "https://workiq.svc.cloud.microsoft/mcp",
+      "oauth": {
+        "clientId": "ba081686-5d24-4bc6-a0d6-d034ecffed87"
+      }
+    }
+  }
+}
+```
+
+> In VS Code, do not include `oauthPublicClient` or `auth.redirectPort` in the server definition. Using the CLI shape in VS Code can trigger the platform broker flow to fail with `401 InvalidAuthenticationToken` and an empty bearer token.
+
 No local package or runtime install is required for MCP tool calls. Do not block MCP tool usage on local machine prerequisites.
 
 ## Configuration

tests/test_mcp_host_config_docs.py

@@ -0,0 +1,29 @@
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def assert_contains(path: str, *expected: str) -> None:
+    text = (ROOT / path).read_text(encoding="utf-8")
+    for item in expected:
+        assert item in text, f"Missing {item!r} in {path}"
+
+
+# The docs and skill guidance should clearly call out the VS Code MCP host schema.
+assert_contains("plugins/workiq/README.md", '"servers": {', '"oauth": {', 'VS Code')
+assert_contains("plugins/workiq-preview/README.md", '"servers": {', '"oauth": {', 'VS Code')
+assert_contains("plugins/workiq/skills/workiq/SKILL.md", '"servers": {', '"oauth": {', 'VS Code')
+assert_contains("plugins/workiq-preview/skills/workiq-preview/SKILL.md", '"servers": {', '"oauth": {', 'VS Code')
+
+# The shipped sample plugin config remains valid for the GitHub Copilot CLI host.
+for relpath in [
+    "plugins/workiq/.mcp.json",
+    "plugins/workiq-preview/.mcp.json",
+]:
+    with (ROOT / relpath).open("r", encoding="utf-8") as fh:
+        config = json.load(fh)
+    assert "mcpServers" in config, f"Missing mcpServers in {relpath}"
+    assert "oauthClientId" in config["mcpServers"][relpath.split("/")[-2]], f"Missing oauthClientId in {relpath}"
+
+print("mcp host config docs passed")