From a6a0a6db5f4a483fcb8c49820822ba999c71f0d2 Mon Sep 17 00:00:00 2001 From: "G. H. Chinoy" Date: Mon, 28 Sep 2026 18:58:42 -0600 Subject: [PATCH] docs(mcp): troubleshooting row covers the MCP enum validation error Since #23 each MCP tool's backend property is an enum of the configured backends, so the MCP SDK rejects an unknown backend before the handler runs with 'validating /properties/backend: enum: does not equal any of: [...]', not the allow-list's 'backend ... is not enabled' text. The troubleshooting row now lists both messages and where each appears (HTTP API, and locate_bounding_boxes on a local-only server, still return the allow-list text). Verified with v0.1.2-4-gd1a3246: stdio dgem mcp --local and dgem serve --local /mcp both return the enum error; /api/decide and locate_bounding_boxes return the allow-list error. --- docs-site/src/content/docs/reference/studio-mcp-api.md | 2 +- docs/reference/studio-mcp-api.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-site/src/content/docs/reference/studio-mcp-api.md b/docs-site/src/content/docs/reference/studio-mcp-api.md index 6742782..531d9ff 100644 --- a/docs-site/src/content/docs/reference/studio-mcp-api.md +++ b/docs-site/src/content/docs/reference/studio-mcp-api.md @@ -235,7 +235,7 @@ response. | `max_entropy` or `gpu_forward_ms` is always `0` | The binary or hosted gateway predates issue #14. Rebuild or redeploy. | | Calls fail with `HTTP 429` or take minutes | A Cloud Run or Vertex backend is waking from zero. Call `get_health_and_gpu_status`, and `warmup_gpu` with `wait_for_ready: false` before a batch. | | Plain `dgem mcp` calls go to `127.0.0.1:8080` | No endpoints were configured; see Option B, or use `--remote` (Option A). | -| `backend "vertex" is not enabled on this gateway (available: local)` | The `backend` argument names a backend that isn't configured. It's no longer rerouted silently. Omit `backend` to use the default, pick one from the list, or configure it: `DGEM_VERTEX_URL` / `--vertex-url` for `vertex` and `vertex_first`, `-u` for `cloudrun`. On a hosted gateway the operator may also restrict backends with `DGEM_BACKENDS`. | +| `validating /properties/backend: enum: vertex does not equal any of: [local]` (MCP), or `backend "vertex" is not enabled on this gateway (available: local)` (HTTP API, and MCP `locate_bounding_boxes` on a local-only server) | The `backend` argument names a backend that isn't configured. It's no longer rerouted silently. Each MCP tool's schema lists the configured backends as an `enum`, so the MCP server rejects any other value before the call runs; the list in brackets is what this server offers. Omit `backend` to use the default, pick one from the list, or configure it: `DGEM_VERTEX_URL` / `--vertex-url` for `vertex` and `vertex_first`, `-u` for `cloudrun`. On a hosted gateway the operator may also restrict backends with `DGEM_BACKENDS`. | | `vertex_url "..." is not allowed on this gateway` | `vertex_url` may only name the configured endpoint, or one listed in `--allowed-vertex-endpoints` (`DGEM_ALLOWED_VERTEX_ENDPOINTS`) on `dgem serve`. Drop the argument to use the configured endpoint. | To check what a `dgem` binary advertises without an agent, pipe `initialize` and `tools/list` into it (the diff --git a/docs/reference/studio-mcp-api.md b/docs/reference/studio-mcp-api.md index cd6bb10..0015494 100644 --- a/docs/reference/studio-mcp-api.md +++ b/docs/reference/studio-mcp-api.md @@ -237,7 +237,7 @@ response. | `max_entropy` or `gpu_forward_ms` is always `0` | The binary or hosted gateway predates issue #14. Rebuild or redeploy. | | Calls fail with `HTTP 429` or take minutes | A Cloud Run or Vertex backend is waking from zero. Call `get_health_and_gpu_status`, and `warmup_gpu` with `wait_for_ready: false` before a batch. | | Plain `dgem mcp` calls go to `127.0.0.1:8080` | No endpoints were configured; see Option B, or use `--remote` (Option A). | -| `backend "vertex" is not enabled on this gateway (available: local)` | The `backend` argument names a backend that isn't configured. It's no longer rerouted silently. Omit `backend` to use the default, pick one from the list, or configure it: `DGEM_VERTEX_URL` / `--vertex-url` for `vertex` and `vertex_first`, `-u` for `cloudrun`. On a hosted gateway the operator may also restrict backends with `DGEM_BACKENDS`. | +| `validating /properties/backend: enum: vertex does not equal any of: [local]` (MCP), or `backend "vertex" is not enabled on this gateway (available: local)` (HTTP API, and MCP `locate_bounding_boxes` on a local-only server) | The `backend` argument names a backend that isn't configured. It's no longer rerouted silently. Each MCP tool's schema lists the configured backends as an `enum`, so the MCP server rejects any other value before the call runs; the list in brackets is what this server offers. Omit `backend` to use the default, pick one from the list, or configure it: `DGEM_VERTEX_URL` / `--vertex-url` for `vertex` and `vertex_first`, `-u` for `cloudrun`. On a hosted gateway the operator may also restrict backends with `DGEM_BACKENDS`. | | `vertex_url "..." is not allowed on this gateway` | `vertex_url` may only name the configured endpoint, or one listed in `--allowed-vertex-endpoints` (`DGEM_ALLOWED_VERTEX_ENDPOINTS`) on `dgem serve`. Drop the argument to use the configured endpoint. | To check what a `dgem` binary advertises without an agent, pipe `initialize` and `tools/list` into it (the