mcp-context-server

mcp-context-server exposes a deterministic context resolution engine to AI agents via the Model Context Protocol (MCP). It enables agents to retrieve reproducible, auditably-selected context from local documentation without network dependencies.

mcp-context-server is the primary integration surface for agents on the Context platform.

Architecture

The MCP server is a thin protocol adapter over the deterministic context engine.

Agent → MCP client → mcp-context-server → context-core → context cache

• context-core performs deterministic selection
• The server provides a stable JSON-RPC interface
• No network calls or external services are required
• Designed for on-premise and air-gapped environments

Creating caches

Caches are created using the context CLI:

context build --sources ./docs --cache ./caches/my-cache

See the context-cli repository for details.

Tools

Tool	Description
context.resolve	Resolve context from a cache using a query and token budget
context.list_caches	List available context caches under the server's cache root
context.inspect_cache	Inspect cache metadata and validity

Configuration

The server is configured via environment variables:

Variable	Required	Default	Description
CONTEXT_CACHE_ROOT	yes	—	Root directory containing context caches
CONTEXT_TOOL_TIMEOUT_SECS	no	30	Maximum seconds per tool call

Running

CONTEXT_CACHE_ROOT=./caches ./dist/mcp-context-server

The server reads JSON-RPC requests from stdin and writes responses to stdout. It is designed to be launched by an MCP client (e.g., Claude Desktop, an agent framework).

MCP client configuration

For Claude Desktop, add to your MCP config:

{
  "mcpServers": {
    "context": {
      "command": "/path/to/mcp-context-server",
      "env": {
        "CONTEXT_CACHE_ROOT": "/path/to/your/caches"
      }
    }
  }
}

Protocol

• Transport: stdio (JSON-RPC 2.0, newline-delimited)
• Protocol version: 2024-11-05
• All responses are deterministic
• Error codes: cache_missing, cache_invalid, invalid_query, invalid_budget, io_error, internal_error

Determinism Guarantees

For identical inputs (cache contents, query, and budget), the server guarantees:

• Byte-identical responses
• Stable document ordering
• Stable floating-point representations
• No hidden state across requests

Determinism is enforced by a compatibility test harness across versions and platforms.

Failure Semantics

• Tool errors return structured MCP error responses
• The server never panics for user-input errors
• IO failures are reported as io_error
• Invalid caches are reported as cache_invalid

Build

make build     # debug build
make test      # run all tests (31 tests including 11 golden snapshot tests)
make check     # cargo check + clippy
make release   # optimized build, binary copied to dist/
make clean     # remove artifacts

The release binary is named mcp-context-server and placed in dist/.

Spec references

See spec_refs.md for links to the governing specifications.

---

"Context Engine" is a trademark of Context Engine Contributors. The software is open source under the Apache License 2.0. The trademark is not licensed for use by third parties to market competing products or services without prior written permission.