Weaviate Connection & Auth
Relevant source files
The following files were used as context for generating this wiki page:
The Weaviate Connection & Auth system provides the foundational infrastructure for the weaviate-mcp package to interact with Weaviate vector databases. It handles client initialization, environment-based configuration, and authentication via API keys, specifically supporting OpenAI for vectorization services. This system ensures that AI models can securely perform vector operations without direct exposure of database credentials.
Sources: packages/weaviate-mcp/README.md, packages/weaviate-mcp/src/weaviate_mcp/services/weaviate_service.py:19-25
Connection Architecture
The connection logic is encapsulated within the WeaviateService class, which manages a WeaviateAsyncClient. The service follows a "connect-on-demand" pattern, using an internal _ensure_connected method to verify and establish connectivity before any database operation.
The diagram above illustrates the lazy connection logic used to maintain database availability.
Sources: packages/weaviate-mcp/src/weaviate_mcp/services/weaviate_service.py:27-65
Connection Parameters
The system utilizes ConnectionParams to define the target Weaviate instance. By default, it supports both HTTP and gRPC protocols, with gRPC being preferred for high-performance operations.
| Parameter | Source | Description |
|---|---|---|
http_host | WEAVIATE_URL | The hostname for REST API calls (e.g., localhost). |
http_port | WEAVIATE_HTTP_PORT | The port for HTTP traffic (default: 8080). |
grpc_host | WEAVIATE_URL | The hostname for gRPC calls. |
grpc_port | WEAVIATE_GRPC_PORT | The port for gRPC traffic (default: 50051). |
X-OpenAI-Api-Key | WEAVIATE_OPENAI_API_KEY | Header used for text-to-vector transformations. |
Sources: packages/weaviate-mcp/src/weaviate_mcp/services/weaviate_service.py:38-48, packages/weaviate-mcp/README.md
Authentication & Security
Authentication is managed through environment variables and passed to the Weaviate client via additional headers. This implementation primarily focuses on OpenAI integration for vectorization, but it also provides hooks for standard Weaviate API key authentication.
Authentication Flow
When the service initializes, it retrieves the OpenAI API key through a utility function and injects it into the additional_headers of the WeaviateAsyncClient.
The sequence diagram shows the credential retrieval and injection process during client setup.
Sources: packages/weaviate-mcp/src/weaviate_mcp/services/weaviate_service.py:34-52
Environment Variables
The server relies on the following environment variables for secure operation:
WEAVIATE_URL: Target host (without protocol prefix).WEAVIATE_HTTP_PORT: Port for standard requests.WEAVIATE_GRPC_PORT: Port for high-speed vector data transfer.WEAVIATE_OPENAI_API_KEY: Required fortext2vec-openaimodules.WEAVIATE_API_KEY: (Optional) For Weaviate instances with authentication enabled.
Sources: packages/weaviate-mcp/README.md, docker-compose.weaviate.yml:25-30
Service Configuration
The WeaviateService includes specific timeout configurations to handle different types of database operations, ensuring stability during long-running tasks like batch insertions or complex schema updates.
Timeout Settings
# packages/weaviate-mcp/src/weaviate_mcp/services/weaviate_service.py:51-55
additional_config=AdditionalConfig(
timeout=Timeout(
init=30,
query=60,
insert=120,
),
)
These settings prioritize resource availability by allowing longer durations for data-intensive insert operations compared to initial connection init checks.
Local Development Setup
For local development, a docker-compose.weaviate.yml file defines a Weaviate instance with specific environment flags to facilitate testing:
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true': Disables internal Weaviate auth for dev environments.ENABLE_MODULES: 'text2vec-openai,generative-openai': Activates required AI transformation modules.DEFAULT_VECTORIZER_MODULE: 'text2vec-openai': Sets the default provider for embeddings.
Sources: docker-compose.weaviate.yml:19-35, packages/weaviate-mcp/src/weaviate_mcp/services/weaviate_service.py:51-55
Error Handling & Lifecycle
The connection logic includes a robust error handling wrapper. If a connection fails, the client is reset to None and _connected is set to False, preventing subsequent operations from attempting to use a dead client.
Connection Lifecycle Management
The service provides a close() method to gracefully terminate the connection, which is critical for resource management in asynchronous environments.
# packages/weaviate-mcp/src/weaviate_mcp/services/weaviate_service.py:68-78
async def close(self):
"""Close the Weaviate connection."""
if self._client and self._connected:
try:
await self._client.close()
logger.info("WeaviateService connection closed")
except Exception as e:
logger.error(f"Error closing WeaviateService: {e}")
finally:
self._client = None
self._connected = False
Sources: packages/weaviate-mcp/src/weaviate_mcp/services/weaviate_service.py:68-78, tests/weaviate-mcp/conftest.py:168-175
Summary
The Weaviate Connection & Auth system establishes a secure, asynchronous bridge to Weaviate vector databases. By utilizing environment-driven configuration and lazy initialization, it provides a resilient interface for the MCP server to manage collections and perform semantic searches while maintaining strict isolation of sensitive API credentials.