Weaviate MCP server

The Weaviate Model Context Protocol (MCP) server is an implementation of the open standard that enables Large Language Models (LLMs) to interact securely with your Weaviate instance.

Instead of pasting context manually, MCP allows compatible clients (like Claude Desktop or IDEs) to directly "see" and interact with your database. Weaviate implements this as a Streamable HTTP server that runs on the same port as the main Weaviate REST API. It exposes tools to inspect schemas, search data (vector/hybrid), and modify objects, governed by Weaviate's authentication and authorization.

The Weaviate MCP server runs at /v1/mcp on the REST API port if enabled (http://localhost:8080/v1/mcp on a default self-hosted instance, https://<your-cluster-host>/v1/mcp on Weaviate Cloud) and supports authentication via Bearer tokens (API Keys). To get started:

1. On a self-hosted instance, enable the MCP server (and optionally write access) with environment variables. On Weaviate Cloud it is already enabled (see Weaviate Cloud for the write-access switch).
2. Ensure your API key has the right permissions if using RBAC.
3. Connect your MCP client using the REST API host and port.

You can also optionally customize tool descriptions to tailor the LLM's understanding of your workflow.

claude mcp add-json weaviate-local '{"type":"http","url":"http://localhost:8080/v1/mcp","headers":{"Authorization":"Bearer YOUR_API_KEY"}}'

{
  "mcpServers": {
    "weaviate-local": {
      "command": "mcp-proxy",
      "args": [
        "http://localhost:8080/v1/mcp",
        "--headers",
        "Authorization",
        "Bearer YOUR_API_KEY",
        "--transport",
        "streamablehttp"
      ]
    }
  }
}

{
  "mcpServers": {
    "weaviate-local": {
      "type": "streamable-http",
      "url": "http://localhost:8080/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "servers": {
    "weaviate-local": {
      "type": "streamable-http",
      "url": "http://localhost:8080/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "weaviate-local": {
      "url": "http://localhost:8080/v1/mcp",
      "type": "streamable-http"
    }
  }
}

The MCP server is built into Weaviate. On a self-hosted instance it is disabled by default for security. On Weaviate Cloud it is always enabled (see Weaviate Cloud). It is served at the /v1/mcp endpoint on the same port as the REST API (default 8080).

On Weaviate Cloud, the MCP server is always enabled. There is no console setting to turn it off. What you control is write access, with a single switch in the cluster's advanced configuration: Enable MCP Read-Only. The switch is off by default on all Weaviate Cloud clusters, so weaviate-objects-upsert is available out of the box. Turning it on restricts the server to its read tools. No environment variables are involved and no restart is needed: a saved change applies after a short delay, from under a minute to a few minutes.

To change the switch on an existing cluster:

1. Open the cluster details page in the Weaviate Cloud console and click Show advanced options.
2. Under Advanced configuration, set Enable MCP Read-Only.
3. Click Save Configuration.

On Shared Cloud clusters, the switch is also available on the cluster creation form under Advanced configuration (see Create a cluster).

The switch is cluster-wide, while a viewer API key is per-credential: to keep one agent read-only without restricting the whole cluster, connect it with an API key that has the read-only viewer role (see Permissions).

On a self-hosted instance, set the following environment variables in your Weaviate configuration (e.g., docker-compose.yml):

If you use RBAC with fine-grained permissions instead of root access, the role assigned to your API key must include the appropriate MCP permissions. Without them, most tool calls are rejected.

For a read-only key, assign the predefined viewer role, the assignable read-only role for database users: it includes read_mcp together with read access to collections, data, and tenants. On Weaviate Cloud, the admin role includes all three MCP permissions. Pick the role when you create the API key.

Permissions are enforced when a tool is called, not when tools are listed. tools/list shows every tool to every authenticated key (only the write-access flag hides weaviate-objects-upsert). A call the key is not allowed to make returns HTTP 200 with a tool result whose isError is true and whose text contains insufficient permissions to read_mcp [] (or create_mcp, read_data, and so on). It is neither an HTTP 403 nor a JSON-RPC error.

You can override the default descriptions provided to the LLM by mounting a YAML or JSON file at MCP_SERVER_CONFIG_PATH.

# mcp-config.yaml
tools:
  weaviate-query-hybrid:
    description: "Perform a vector or keyword search on a collection."
    arguments:
      query: "The natural language search query to find relevant objects."
      alpha: "0.0 = pure keyword (BM25), 1.0 = pure vector. Defaults to 0.75."

{
  "tools": {
    "weaviate-query-hybrid": {
      "description": "Perform a vector or keyword search on a collection.",
      "arguments": {
        "query": "The natural language search query to find relevant objects.",
        "alpha": "0.0 = pure keyword (BM25), 1.0 = pure vector. Defaults to 0.75."
      }
    }
  }
}

The server exposes different tools depending on your configuration. These are all the available tools:

• weaviate-collections-get-config
• weaviate-tenants-list
• weaviate-query-hybrid
• weaviate-objects-upsert

For every tool, collection_name is matched after uppercasing only its first character: article resolves to the collection Article, but ARTICLE does not.

Retrieves the schema configuration for collections.

Arguments:

• collection_name (string, optional): Specific collection to retrieve. If omitted, returns all.

Returns: JSON object containing class names, properties, and vectorizer settings.

Lists tenants for multi-tenant collections.

Arguments:

• collection_name (string, required): The collection to inspect.

Returns: List of tenants with their activityStatus. The status is reported with the legacy names: HOT is ACTIVE, COLD is INACTIVE, and FROZEN is OFFLOADED (a tenant offloaded to cloud storage). FREEZING and UNFREEZING are the transitional OFFLOADING and ONLOADING states. Calling the tool on a collection without multi-tenancy returns an error.

Performs a hybrid search combining vector similarity and keyword matching (BM25).

Arguments:

• query (string, required): The natural language search text.
• collection_name (string, required): The collection to search.
• tenant_name (string, optional): Tenant to search within for multi-tenant collections.
• alpha (float, optional): Weighting between the two searches. 0.0 = pure keyword search, 1.0 = pure vector search. Defaults to 0.75.
• limit (int, optional): Maximum number of results. Defaults to 100. A value of 0 returns no results.
• target_vectors (array, optional): Named vectors to use for vector search.
• target_properties (array, optional): Properties to search with BM25. If omitted, searches all text properties.
• return_properties (array, optional): Properties to include in results. If omitted, every property is returned in full, long text included, so set this to keep responses small.
• return_metadata (array, optional): Metadata fields to return (e.g., id, vector, distance, score, creationTimeUnix, lastUpdateTimeUnix). Values are case-insensitive, and unknown values are ignored.
• filters (object, optional): A where filter applied before scoring.

A leaf filter is an object with path (an array of property names), operator, and a typed value field. The typed value field is one of valueText, valueInt, valueNumber, valueBoolean, valueDate, the corresponding value*Array field for a Contains* operator, or valueGeoRange for WithinGeoRange. Combine leaves with {"operator": "And" | "Or", "operands": [ ... ]}, nested to any depth. The supported operators are And, Or, Not, Equal, NotEqual, Like, GreaterThan, GreaterThanEqual, LessThan, LessThanEqual, ContainsAny, ContainsAll, ContainsNone, WithinGeoRange, and IsNull. See Concepts: Filtering for how filters interact with search.

Returns: Ranked objects. Each result carries the object's properties at the top level, its id, and an _additional object with the requested metadata.

Batch inserts or updates objects. An update replaces the stored object rather than merging into it: properties you leave out are dropped, and a property set to null is removed. If the update supplies no vectors, the object is re-vectorized on a collection with a vectorizer, and on a collection without one the stored vector is dropped. To change a single property, send the complete object.

Arguments:

• collection_name (string, required): The collection to upsert into.
• tenant_name (string, optional): Tenant for multi-tenant collections.
• objects (array, required): List of objects containing properties and optional uuid or vectors. vectors maps vector names to arrays, and there is no singular vector field. If uuid is omitted, one is generated. If any uuid is invalid, the whole call is rejected and nothing is written.

Returns: Array of results containing UUIDs or error messages per object, in input order. Partial success is normal: one object can fail while the rest are written.

• Authentication: when anonymous access is disabled, a missing or invalid API key is rejected by the REST layer with HTTP 401 and a JSON body before the request reaches the MCP server: for example, {"code": 401, "message": "unauthorized: invalid api key"} for an invalid key, or a message of anonymous access not enabled. Please authenticate through one of the available methods: [API-keys, OIDC] for a missing one. This applies to initialize and tools/list as well as to tool calls.
• Authorization: a permission failure is a tool result, not an HTTP error: HTTP 200 with isError: true and the RBAC message as text (see Permissions).
• Server or write access disabled: a request to /v1/mcp on an instance where the MCP server is disabled returns HTTP 503 with a JSON error body. Where only write access is disabled, weaviate-objects-upsert is absent from the tools/list response, and calling it returns a tool result with isError: true and the text MCP write access is disabled: ....
• Request duration: on Weaviate Cloud, a request that takes longer than about 60 seconds from its first byte to the response is cut off by the server's write timeout and surfaces as a plain-text HTTP 503 from the ingress (upstream connect error or disconnect/reset before headers ...), not as a JSON-RPC error. Nothing from a cut-off upsert is written. Weaviate does not enforce a request-size limit on /v1/mcp, so size weaviate-objects-upsert batches by how long they take to upload and process, not by bytes, and keep each call well under a minute.

From v1.38, the MCP server emits six Prometheus metrics under the weaviate_mcp_* prefix on the existing Prometheus endpoint. Use them to track tool traffic, latency, auth failures, and the live state of the write-access flag.

See Monitoring → MCP server for the full label catalogue and the rest of Weaviate's Prometheus surface.

• Vibe coding - Best practices
• Weaviate Docs MCP server

Have a question or feedback? Here's how to reach us.