[v1.38] Document MCP runtime config + Prometheus metrics

[g-despot]

Summary

Documents two MCP-related server changes landing in v1.38:

• weaviate/weaviate#11176 — MCP_SERVER_ENABLED and MCP_SERVER_WRITE_ACCESS_ENABLED are now runtime-configurable through the runtime overrides YAML. No cluster restart required to toggle MCP on/off or flip write access. MCP_SERVER_CONFIG_PATH stays startup-only by design (tool descriptions are baked into the tool schemas at registration). Disabled MCP now returns 503 Service Unavailable instead of 501 Not Implemented.
• weaviate/weaviate#11284 — Six new Prometheus metrics under weaviate_mcp_* covering tool traffic, latency, in-flight concurrency, auth failures, tools/list traffic, and the live state of the write-access flag.

Files

• docs/weaviate/configuration/mcp-server.mdx
  • Env-var table gains a "Runtime-configurable" column. The two togglable flags marked ✓ (from v1.38); MCP_SERVER_CONFIG_PATH marked Startup-only with the reason inline.
  • New ### Toggle without restart subsection: YAML keys, 2-minute pickup window, the exact 503 response body verbatim, the disappearing-write-tool-from-tools/list behavior, and a callout that v1.37.x clusters returned 501 so anyone monitoring /v1/mcp health knows the status code shifts on upgrade.
  • New ## Monitoring section after Tools — six-row metrics summary table + link to the full catalogue.
• docs/deploy/configuration/env-vars/runtime-config.md
  • New ### MCP subsection under "Available overrides" (sibling to Raft / Usage tracking / Authentication) with mcp_server_enabled and mcp_server_write_access_enabled. Notes that MCP_SERVER_CONFIG_PATH is intentionally not runtime-configurable, in the same place so anyone searching for it finds the explanation.
• docs/deploy/configuration/env-vars/index.md
  • The two MCP rows append [Runtime-configurable](./runtime-config.md#mcp) from v1.38. to their descriptions — preserves the v1.37.1 "Added in" provenance.
• docs/deploy/configuration/monitoring.md
  • New ### MCP server section at the end of "Obtainable Metrics" (sibling of Replication). Full six-metric table with descriptions, labels, and types, plus an explicit enumeration of every label-value: four status values, four reason values, two write_access values. The tool label is described inline (MCP tool name).

Decisions called out

• Badge vs new column for runtime-configurable flag. Went with a column on the MCP page's three-row table. Did not retrofit this column across other env-var tables in the docs — change scope kept tight.
• Where the metrics section sits. Its own section at the end of "Obtainable Metrics", not nested under "Modules & extensions" — MCP is a built-in server feature, not a module.
• Cross-linking direction. MCP page has a summary table + link out to monitoring.md; monitoring.md is the single source of truth for the label catalogue.
• 501 → 503 status code shift mentioned inline under "Toggle without restart" rather than as a separate :::note. Status code change is incidental to the runtime-config feature; readers monitoring /v1/mcp health will see it in context.

Test plan

• yarn build clean (only the pre-existing unrelated hnsw_startup_wait_for_vector_cache anchor warning).
• Bidirectional cross-links resolve (mcp-server#toggle-without-restart, mcp-server#monitoring, monitoring#mcp-server, runtime-config#mcp).
• Recommended before merge: spin up the v1.38 dev image with MCP_SERVER_ENABLED=true, RUNTIME_OVERRIDES_ENABLED=true, RUNTIME_OVERRIDES_PATH=/tmp/overrides.yaml, RUNTIME_OVERRIDES_LOAD_INTERVAL=1s. Flip mcp_server_enabled: false in the YAML, wait, confirm /v1/mcp returns 503 with the documented body. Re-enable, confirm 200. Same flow for mcp_server_write_access_enabled — confirm the write tool disappears from tools/list. Hit the Prometheus endpoint and confirm all six weaviate_mcp_* metrics are scraped. The server-side test TestMCPRuntimeConfigToggle in PR #11176 already exercises this contract, so the docs match a tested behavior.

Not in this PR

• No new metrics for the Weaviate Docs MCP server (Kapa-powered, separate product).
• No dashboards/alerts. The "Sample Dashboards" section of monitoring.md doesn't currently cover MCP either — could land as a follow-up once a reference Grafana dashboard exists for the new metrics.

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[Copilot]

Pull request overview

Documents two MCP-related v1.38 server changes: runtime-configurability of the MCP enable/write flags via the runtime overrides YAML, and six new Prometheus weaviate_mcp_* metrics. Also bumps the local weaviate_version to 1.38.0.

Changes:

• Adds a "Runtime-configurable" column to the MCP env-var table and a new ## Monitoring summary on mcp-server.mdx, plus runtime-configurable cross-links from env-vars/index.md.
• Adds a new ### MCP overrides subsection on runtime-config.md (with a note that MCP_SERVER_CONFIG_PATH stays startup-only).
• Adds a new ### MCP server metrics section on monitoring.md enumerating the six metrics, labels, and label values; bumps weaviate_version to 1.38.0.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
versions-config.json	Bumps local-build weaviate_version from 1.37.2 to 1.38.0.
docs/weaviate/configuration/mcp-server.mdx	Adds "Runtime-configurable" column to the env-var table and a new ## Monitoring section linking to monitoring.md; expected ### Toggle without restart subsection is missing.
docs/deploy/configuration/monitoring.md	New ### MCP server section listing six weaviate_mcp_* metrics with labels and value enumerations; minor table/whitespace cleanups in adjacent sections.
docs/deploy/configuration/env-vars/runtime-config.md	New ### MCP overrides subsection with mcp_server_enabled / mcp_server_write_access_enabled and a note that MCP_SERVER_CONFIG_PATH is intentionally not runtime-configurable; links to a not-yet-existing anchor on the MCP page.
docs/deploy/configuration/env-vars/index.md	Appends [Runtime-configurable](./runtime-config.md#mcp) from v1.38. to the two MCP env-var rows.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.