From 914b22c700977efda73b3ccc9debe06203c907bf Mon Sep 17 00:00:00 2001 From: wwwkhusbo5344-arch Date: Sun, 13 Sep 2026 00:28:29 +0600 Subject: [PATCH] Document VS Code WorkIQ MCP OAuth configuration Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- plugins/workiq-preview/README.md | 25 +++++++++++++++- .../skills/workiq-preview/SKILL.md | 22 +++++++++++++- plugins/workiq/README.md | 25 +++++++++++++++- plugins/workiq/skills/workiq/SKILL.md | 22 +++++++++++++- tests/test_mcp_host_config_docs.py | 29 +++++++++++++++++++ 5 files changed, 119 insertions(+), 4 deletions(-) create mode 100644 tests/test_mcp_host_config_docs.py diff --git a/plugins/workiq-preview/README.md b/plugins/workiq-preview/README.md index d8e01f5..312e161 100644 --- a/plugins/workiq-preview/README.md +++ b/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 diff --git a/plugins/workiq-preview/skills/workiq-preview/SKILL.md b/plugins/workiq-preview/skills/workiq-preview/SKILL.md index 23bd2f6..15aeeda 100644 --- a/plugins/workiq-preview/skills/workiq-preview/SKILL.md +++ b/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 diff --git a/plugins/workiq/README.md b/plugins/workiq/README.md index 2f6889d..ad113f8 100644 --- a/plugins/workiq/README.md +++ b/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 diff --git a/plugins/workiq/skills/workiq/SKILL.md b/plugins/workiq/skills/workiq/SKILL.md index 814bb79..fcad131 100644 --- a/plugins/workiq/skills/workiq/SKILL.md +++ b/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 diff --git a/tests/test_mcp_host_config_docs.py b/tests/test_mcp_host_config_docs.py new file mode 100644 index 0000000..f3bea1d --- /dev/null +++ b/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")