diff --git a/docs/deploy/configuration/env-vars/index.md b/docs/deploy/configuration/env-vars/index.md
index 3db54c30..6146106c 100644
--- a/docs/deploy/configuration/env-vars/index.md
+++ b/docs/deploy/configuration/env-vars/index.md
@@ -67,8 +67,8 @@ import APITable from '@site/src/components/APITable';
| `MAXIMUM_CONCURRENT_BUCKET_LOADS` | Maximum number of buckets that can be loaded concurrently during startup. This is a safeguard to prevent overwhelming the operating system when loading large numbers of collections. Default: `100`
Added in `v1.31.22` | `string - number` | `50` |
| `MAXIMUM_CONCURRENT_SHARD_LOADS` | Maximum number of shards that can be loaded concurrently during startup. This is a safeguard to prevent overwhelming the operating system when loading large numbers of collections. Default: `100` | `string - number` | `50` |
| `MCP_SERVER_CONFIG_PATH` | Path to a YAML file for customizing MCP tool descriptions. Useful for prompt engineering the LLM's understanding of your specific data. If not provided or file malformed, the default descriptions will be used. Default: `""` (default tool descriptions from the [source code](https://github.com/weaviate/weaviate/tree/main/adapters/handlers/mcp) will be used)
Added in `v1.37.1` | `string` | `/etc/weaviate/mcp-config.yaml` |
-| `MCP_SERVER_ENABLED` | Enable the built-in MCP server. When enabled, the MCP endpoint is available at `/v1/mcp` on the REST API port. Default: `false`
Added in `v1.37.1` | `boolean` | `true` |
-| `MCP_SERVER_WRITE_ACCESS_ENABLED` | Enable write tools (`weaviate-objects-upsert`) on the MCP server. When `false`, only read and query tools are available. Default: `false`
Added in `v1.37.1` | `boolean` | `true` |
+| `MCP_SERVER_ENABLED` | Enable the built-in MCP server. When enabled, the MCP endpoint is available at `/v1/mcp` on the REST API port. Default: `false`
Added in `v1.37.1`. [Runtime-configurable](./runtime-config.md#mcp) from `v1.38`. | `boolean` | `true` |
+| `MCP_SERVER_WRITE_ACCESS_ENABLED` | Enable write tools (`weaviate-objects-upsert`) on the MCP server. When `false`, only read and query tools are available. Default: `false`
Added in `v1.37.1`. [Runtime-configurable](./runtime-config.md#mcp) from `v1.38`. | `boolean` | `true` |
| `MEMORY_READONLY_PERCENTAGE` | If memory usage is higher than the given percentage all shards on the affected node will be marked as `READONLY`, meaning all future write requests will fail. (Default: `0` - i.e. no limit) | `string - number` | `75` |
| `MEMORY_WARNING_PERCENTAGE` | If memory usage is higher than the given percentage a warning will be logged by all shards on the affected node's disk. (Default: `0` - i.e. no limit) | `string - number` | `85` |
| `MODULES_CLIENT_TIMEOUT` | Timeout for requests to Weaviate modules. Default: `50s` | `string - duration` | `5s`, `10m`, `1h` |
diff --git a/docs/deploy/configuration/env-vars/runtime-config.md b/docs/deploy/configuration/env-vars/runtime-config.md
index f0c294cd..cc50296e 100644
--- a/docs/deploy/configuration/env-vars/runtime-config.md
+++ b/docs/deploy/configuration/env-vars/runtime-config.md
@@ -114,6 +114,17 @@ The following overrides are currently supported:
| `authentication_oidc_skip_client_id_check` | `AUTHENTICATION_OIDC_SKIP_CLIENT_ID_CHECK` |
| `authentication_oidc_username_claim` | `AUTHENTICATION_OIDC_USERNAME_CLAIM` |
+### MCP
+
+Added in `v1.38`. Toggling these at runtime does not require a cluster restart — the HTTP handlers stay registered and per-request checks pick up the new value. See [MCP server — Toggle without restart](/weaviate/configuration/mcp-server.mdx#toggle-without-restart) for behavior details.
+
+| Runtime override name | Environment variable name |
+| :-------------------------------- | :---------------------------------- |
+| `mcp_server_enabled` | `MCP_SERVER_ENABLED` |
+| `mcp_server_write_access_enabled` | `MCP_SERVER_WRITE_ACCESS_ENABLED` |
+
+`MCP_SERVER_CONFIG_PATH` is intentionally **not** runtime-configurable — tool descriptions are baked into the tool schemas at registration.
+
Refer to the [Environment variables](./index.md) page for descriptions on each configuration option
## Operation and monitoring
diff --git a/docs/deploy/configuration/monitoring.md b/docs/deploy/configuration/monitoring.md
index a954c13f..281ce3c0 100644
--- a/docs/deploy/configuration/monitoring.md
+++ b/docs/deploy/configuration/monitoring.md
@@ -64,7 +64,8 @@ Be aware that metrics do not follow the semantic versioning guidelines of other
:::
-The list of metrics that are obtainable through Weaviate's metric system is constantly being expanded. The complete list of metrics can be found in the source code files:
+The list of metrics that are obtainable through Weaviate's metric system is constantly being expanded. The complete list of metrics can be found in the source code files:
+
- [`usecases/monitoring/prometheus.go`](https://github.com/weaviate/weaviate/blob/main/usecases/monitoring/prometheus.go)
- [`usecases/replica/metrics.go`](https://github.com/weaviate/weaviate/blob/main/usecases/replica/metrics.go)
- [`adapters/repos/db/metrics.go`](https://github.com/weaviate/weaviate/blob/main/adapters/repos/db/metrics.go)
@@ -270,7 +271,7 @@ These metrics track Write-Ahead Log (WAL) recovery operations during startup.
| `lsm_bucket_wal_recovery_failure_count` | Number of failed LSM bucket WAL recoveries | `strategy` | `Counter` |
| `lsm_bucket_wal_recovery_duration_seconds` | Duration of LSM bucket WAL recovery in seconds | `strategy` | `Histogram` |
-### Schema & cluster consensus
+### Schema & cluster consensus
#### Schema & RAFT consensus
@@ -356,17 +357,17 @@ These metrics track Write-Ahead Log (WAL) recovery operations during startup.
#### Backup & restore
-| Metric | Description | Labels | Type |
-| --------------------------------- | --------------------------------------------------------- | ---------------------------- | --------- |
-| `backup_restore_ms` | Duration of a backup restore | `backend_name`, `class_name` | `Summary` |
-| `backup_restore_class_ms` | Duration restoring class | `class_name` | `Summary` |
-| `backup_restore_init_ms` | Startup phase of a backup restore | `backend_name`, `class_name` | `Summary` |
-| `backup_restore_from_backend_ms` | File transfer stage of a backup restore | `backend_name`, `class_name` | `Summary` |
-| `backup_store_to_backend_ms` | File transfer stage of a backup store | `backend_name`, `class_name` | `Summary` |
-| `bucket_pause_durations_ms` | Bucket pause durations | `bucket_dir` | `Summary` |
-| `backup_restore_data_transferred` | Total number of bytes transferred during a backup restore | `backend_name`, `class_name` | `Counter` |
-| `backup_store_data_transferred` | Total number of bytes transferred during a backup store | `backend_name`, `class_name` | `Counter` |
-| `weaviate_restore_phase_duration_seconds` | Duration of restore phases (prepare, object_storage_download, schema_apply) | `phase` | `Histogram` |
+| Metric | Description | Labels | Type |
+| ----------------------------------------- | --------------------------------------------------------------------------- | ---------------------------- | ----------- |
+| `backup_restore_ms` | Duration of a backup restore | `backend_name`, `class_name` | `Summary` |
+| `backup_restore_class_ms` | Duration restoring class | `class_name` | `Summary` |
+| `backup_restore_init_ms` | Startup phase of a backup restore | `backend_name`, `class_name` | `Summary` |
+| `backup_restore_from_backend_ms` | File transfer stage of a backup restore | `backend_name`, `class_name` | `Summary` |
+| `backup_store_to_backend_ms` | File transfer stage of a backup store | `backend_name`, `class_name` | `Summary` |
+| `bucket_pause_durations_ms` | Bucket pause durations | `bucket_dir` | `Summary` |
+| `backup_restore_data_transferred` | Total number of bytes transferred during a backup restore | `backend_name`, `class_name` | `Counter` |
+| `backup_store_data_transferred` | Total number of bytes transferred during a backup store | `backend_name`, `class_name` | `Counter` |
+| `weaviate_restore_phase_duration_seconds` | Duration of restore phases (prepare, object_storage_download, schema_apply) | `phase` | `Histogram` |
#### Shard management
@@ -474,6 +475,26 @@ These metrics track the replication coordinator's read and write operations acro
| `replication_coordinator_reads_duration_seconds` | Duration in seconds of read operations from replicas | None | `Histogram` |
| `replication_read_repair_duration_seconds` | Duration in seconds of read repair operations | None | `Histogram` |
+### MCP server
+
+Added in `v1.38`. These metrics track tool traffic, latency, auth failures, and the live state of the runtime write-access flag for the built-in [Weaviate MCP server](/weaviate/configuration/mcp-server.mdx).
+
+| Metric | Description | Labels | Type |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------- | ----------- |
+| `weaviate_mcp_tool_calls_total` | Total MCP tool invocations. | `tool`, `status` | `Counter` |
+| `weaviate_mcp_tool_call_duration_seconds` | Latency of MCP tool calls (LatencyBuckets histogram). | `tool`, `status` | `Histogram` |
+| `weaviate_mcp_tool_calls_inflight` | In-flight MCP tool calls per tool. Catches one slow tool starving the rest. | `tool` | `Gauge` |
+| `weaviate_mcp_auth_failures_total` | MCP authentication and authorization failures. | `reason` | `Counter` |
+| `weaviate_mcp_tools_listed_total` | `tools/list` calls, labeled with whether the write tool was visible in the response. | `write_access` | `Counter` |
+| `weaviate_mcp_write_access_enabled` | Live state of `MCP_SERVER_WRITE_ACCESS_ENABLED`, polled at scrape time. Reflects runtime toggles. | None | `Gauge` |
+
+Label values:
+
+- **`tool`** — the MCP tool name (e.g. `weaviate-query-hybrid`, `weaviate-objects-upsert`).
+- **`status`** — `success` · `error` · `denied` · `write_disabled`. `denied` covers authorization failures classified via the `Forbidden` / `Unauthenticated` error families. `write_disabled` is emitted when a write call hits the runtime guard.
+- **`reason`** — `missing_token` · `invalid_token` · `forbidden` · `unauthenticated`. `missing_token` and `invalid_token` are detected at the principal-extraction step; `forbidden` and `unauthenticated` are detected at authorization time.
+- **`write_access`** — `enabled` / `disabled`, matching the live state of `MCP_SERVER_WRITE_ACCESS_ENABLED` at the time of the `tools/list` call.
+
---
diff --git a/docs/weaviate/configuration/mcp-server.mdx b/docs/weaviate/configuration/mcp-server.mdx
index 18a83ffe..d3b5bba9 100644
--- a/docs/weaviate/configuration/mcp-server.mdx
+++ b/docs/weaviate/configuration/mcp-server.mdx
@@ -15,6 +15,7 @@ faq:
- question: How do I request a new MCP tool or feature?
answer: >-
Open a feature request on the Weaviate GitHub repo at https://github.com/weaviate/weaviate/issues/new/choose. Pick the "Feature request" template and describe the tool, parameter, or capability you'd like the MCP server to expose, with a concrete use case.
+
# tags: ["mcp", "configuration"]
---
@@ -155,11 +156,11 @@ The MCP server is built into Weaviate but is **disabled by default** for securit
To enable and configure the server, set the following [environment variables](/docs/deploy/configuration/env-vars/index.md) in your Weaviate configuration (e.g., `docker-compose.yml`):
-| Environment Variable | Default | Description |
-| --------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`MCP_SERVER_ENABLED`](/deploy/configuration/env-vars#MCP_SERVER_ENABLED) | `false` | **Required.** Set to `true` to start the MCP server. |
-| [`MCP_SERVER_WRITE_ACCESS_ENABLED`](/deploy/configuration/env-vars#MCP_SERVER_WRITE_ACCESS_ENABLED) | `false` | When `true`, enables write tools (`weaviate-objects-upsert`). Default is read-only. |
-| [`MCP_SERVER_CONFIG_PATH`](/deploy/configuration/env-vars#MCP_SERVER_CONFIG_PATH) | `""` | Path to a YAML file for customizing tool descriptions (useful for prompt engineering the LLM's understanding of your specific data). If not provided or file malformed, the default descriptions from the [source code](https://github.com/weaviate/weaviate/tree/main/adapters/handlers/mcp) will be used. |
+| Environment Variable | Default | Runtime-configurable | Description |
+| --------------------------------------------------------------------------------------------------- | ------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`MCP_SERVER_ENABLED`](/deploy/configuration/env-vars#MCP_SERVER_ENABLED) | `false` | from `v1.38` | **Required.** Set to `true` to start the MCP server. |
+| [`MCP_SERVER_WRITE_ACCESS_ENABLED`](/deploy/configuration/env-vars#MCP_SERVER_WRITE_ACCESS_ENABLED) | `false` | from `v1.38` | When `true`, enables write tools (`weaviate-objects-upsert`). Default is read-only. |
+| [`MCP_SERVER_CONFIG_PATH`](/deploy/configuration/env-vars#MCP_SERVER_CONFIG_PATH) | `""` | No | Path to a YAML file for customizing tool descriptions (useful for prompt engineering the LLM's understanding of your specific data). If not provided or file malformed, the default descriptions from the [source code](https://github.com/weaviate/weaviate/tree/main/adapters/handlers/mcp) will be used. Tool descriptions are baked into the tool schemas at registration, so this flag remains startup-only. |
### Permissions
@@ -283,6 +284,14 @@ Batch inserts or updates objects.
---
+## Monitoring
+
+From `v1.38`, the MCP server emits six Prometheus metrics under the `weaviate_mcp_*` prefix on the existing [Prometheus endpoint](/deploy/configuration/monitoring.md). Use them to track tool traffic, latency, auth failures, and the live state of the write-access flag.
+
+See [Monitoring → MCP server](/deploy/configuration/monitoring.md#mcp-server) for the full label catalogue and the rest of Weaviate's Prometheus surface.
+
+---
+
## Further resources
- [Vibe coding - Best practices](../best-practices/code-generation.md)
diff --git a/versions-config.json b/versions-config.json
index 3afd0a68..ea089806 100644
--- a/versions-config.json
+++ b/versions-config.json
@@ -1,7 +1,7 @@
{
"COMMENT1": "These values are used for yarn local yarn builds",
"COMMENT2": "Build time values are set in _build_scripts/update-config-versions.js",
- "weaviate_version": "1.37.2",
+ "weaviate_version": "1.38.0",
"helm_version": "17.8.0",
"weaviate_cli_version": "3.2.2",
"weaviate_agents_version": "1.4.0",