Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
g-despot wants to merge 3 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fe4b6dc
Add 1.38 docs
g-despot May 25, 2026
6af1e75
Merge branch 'main' into v1-38/main
g-despot May 26, 2026
cb116dc
Add MCP docs changes
g-despot May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/deploy/configuration/env-vars/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`<br/>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)<br/>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`<br/>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`<br/>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`<br/>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`<br/>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` |
Expand Down
11 changes: 11 additions & 0 deletions docs/deploy/configuration/env-vars/runtime-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
47 changes: 34 additions & 13 deletions docs/deploy/configuration/monitoring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

---

<!-- TODO[g-despot] First we need to create this guide for adding metrics - Extending Weaviate with new metrics is very easy. To suggest a new metric, see the [contributor guide](/contributor-guide).-->
Expand Down
19 changes: 14 additions & 5 deletions docs/weaviate/configuration/mcp-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
---

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion versions-config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
Loading