home / mcp / mcp context server

MCP Context Server

Provides a high-performance MCP server offering persistent multimodal context storage, flexible metadata, and advanced search across threads.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "alex-feel-mcp-context-server": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--with",
        "mcp-context-server[embeddings-ollama,reranking]",
        "mcp-context-server"
      ],
      "env": {
        "DB_PATH": "<DB_PATH>",
        "LOG_LEVEL": "<LOG_LEVEL>",
        "CHUNK_SIZE": "<CHUNK_SIZE>",
        "ENABLE_FTS": "<ENABLE_FTS>",
        "OLLAMA_HOST": "<OLLAMA_HOST>",
        "FTS_LANGUAGE": "<FTS_LANGUAGE>",
        "HYBRID_RRF_K": "<HYBRID_RRF_K>",
        "CHUNK_OVERLAP": "<CHUNK_OVERLAP>",
        "EMBEDDING_DIM": "<EMBEDDING_DIM>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "VOYAGE_API_KEY": "<VOYAGE_API_KEY>",
        "EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
        "ENABLE_CHUNKING": "<ENABLE_CHUNKING>",
        "POSTGRESQL_HOST": "<POSTGRESQL_HOST>",
        "POSTGRESQL_PORT": "<POSTGRESQL_PORT>",
        "POSTGRESQL_USER": "<POSTGRESQL_USER>",
        "RERANKING_MODEL": "<RERANKING_MODEL>",
        "STORAGE_BACKEND": "<STORAGE_BACKEND>",
        "ENABLE_RERANKING": "<ENABLE_RERANKING>",
        "CHUNK_AGGREGATION": "<CHUNK_AGGREGATION>",
        "LANGSMITH_API_KEY": "<LANGSMITH_API_KEY>",
        "LANGSMITH_PROJECT": "mcp-context-server",
        "LANGSMITH_TRACING": "<LANGSMITH_TRACING>",
        "MAX_IMAGE_SIZE_MB": "<MAX_IMAGE_SIZE_MB>",
        "MAX_TOTAL_SIZE_MB": "<MAX_TOTAL_SIZE_MB>",
        "EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>",
        "RERANKING_PROVIDER": "<RERANKING_PROVIDER>",
        "POSTGRESQL_DATABASE": "<POSTGRESQL_DATABASE>",
        "POSTGRESQL_PASSWORD": "<POSTGRESQL_PASSWORD>",
        "RERANKING_OVERFETCH": "<RERANKING_OVERFETCH>",
        "AZURE_OPENAI_API_KEY": "<AZURE_OPENAI_API_KEY>",
        "ENABLE_HYBRID_SEARCH": "<ENABLE_HYBRID_SEARCH>",
        "AZURE_OPENAI_ENDPOINT": "<AZURE_OPENAI_ENDPOINT>",
        "ENABLE_SEMANTIC_SEARCH": "<ENABLE_SEMANTIC_SEARCH>",
        "METADATA_INDEXED_FIELDS": "<METADATA_INDEXED_FIELDS>",
        "HUGGINGFACEHUB_API_TOKEN": "<HUGGINGFACEHUB_API_TOKEN>",
        "METADATA_INDEX_SYNC_MODE": "<METADATA_INDEX_SYNC_MODE>",
        "AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME": "<AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME>"
      }
    }
  }
}

The MCP Context Server provides a high-performance, persistent multimodal context store for multiple LLM agents, enabling seamless sharing of task context across agents using thread-based scoping and powerful search and filtering capabilities.

How to use

You will connect a compatible MCP client to the Context Server and start by configuring a context store in your application workflow. Use the server to store, retrieve, and filter multimodal context entries (text and images), organize data with tags, and perform fast searches—including full-text, semantic, and hybrid search—across your task threads. Leverage the server’s metadata filtering, date-based queries, and cross-encoder reranking to refine results and improve relevance.

How to install

Prerequisites: Install the uv package manager, ensure you have an MCP-compatible client, and prepare Ollama if you plan to use embedding generation.

Step 1. Install the uv tool chain and prerequisites.

Step 2. Set up the MCP Context Server using the provided stdio configuration. The following configuration starts the server locally with uvx and the MCP Context Server package, including embeddings and reranking features.

{
  "mcpServers": {
    "context_mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--python", "3.12", "--with", "mcp-context-server[embeddings-ollama,reranking]", "mcp-context-server"]
    }
  }
}

Configuration and usage notes

Configure environment variables to tailor storage, search, and resource limits. The server supports a wide range of options for storage backends (SQLite or PostgreSQL), full-text search, semantic search, hybrid search, chunking, and reranking. Set values via MCP configuration or environment expansion syntax as shown in the examples.

Typical options include selecting the storage backend, enabling and configuring full-text search (FTS), semantic search with embedding providers, and enabling cross-encoder reranking for improved result quality.

Usage patterns and best practices

- Use thread-based scoping to share context among agents working on the same task. Each thread ID represents an isolated context container for related prompts, images, and metadata.

- Store rich metadata with JSON-serializable fields to support advanced filtering and retrieval. Use the 16 operators to filter based on metadata values and nested paths.

- Combine full-text, semantic, and hybrid search to achieve fast, relevant results. Enable cross-encoder reranking to refine top results automatically.

Troubleshooting and tips

If you encounter connection issues, verify that the MCP server is running, the client is configured with a valid mcpServers entry, and environment variables are correctly expanded. Check logs for storage, indexing, and search pipeline warnings or errors.

Available tools

store_context

Store a single context entry with its associated data such as text, images, and metadata.

search_context

Search for context entries using full-text, semantic, or hybrid queries with various filters.

get_context_by_ids

Retrieve context entries by their identifiers.

delete_context

Delete a single context entry by identifier.

update_context

Update fields of an existing context entry.

list_threads

List all task threads that have context entries.

get_statistics

Retrieve statistics about stored contexts and usage.

semantic_search_context

Perform semantic similarity based searches over context entries.

fts_search_context

Perform full-text search with linguistic processing.

hybrid_search_context

Perform a hybrid of FTS and semantic search using RRF fusion.

store_context_batch

Store multiple context entries in a single operation.

update_context_batch

Update multiple entries in batch operations.

delete_context_batch

Delete multiple entries in batch operations.