Module server 

MCP-compatible HTTP server.

Exposes Context Harness functionality via a JSON HTTP API suitable for integration with Cursor, Claude, and other MCP-compatible AI tools.

All tools — built-in (search, get, sources), Lua scripts, and custom Rust trait implementations — are registered in a unified ToolRegistry and dispatched through the same POST /tools/{name} handler.

Profiles (named personas with system prompts and tool scoping) are registered in a ProfileRegistry and discoverable/resolvable via dedicated endpoints.

Endpoints

Method	Path	Description
GET	/tools/list	List all registered tools with schemas
POST	/tools/{name}	Call any registered tool by name
GET	/profiles/list	List all registered profiles with metadata
POST	/profiles/{name}/prompt	Resolve a profile’s system prompt
GET	/agents/list	Deprecated compatibility alias
POST	/agents/{name}/prompt	Deprecated compatibility alias
GET	/health	Health check (returns version)

Error Contract

All error responses follow the schema defined in docs/SCHEMAS.md:

{ "error": { "code": "bad_request", "message": "query must not be empty" } }

Error codes: bad_request (400), not_found (404), embeddings_disabled (400), timeout (408), tool_error (500), internal (500).

CORS

All origins, methods, and headers are permitted to support browser-based clients and cross-origin MCP tool calls.

Cursor Integration

Start the server and point Cursor at the /mcp endpoint:

{
  "mcpServers": {
    "context-harness": {
      "url": "http://127.0.0.1:7331/mcp"
    }
  }
}

Structs

AgentListResponse 🔒

Historical response shape retained by GET /agents/list.

AppError 🔒

Internal error type that converts into an Axum HTTP response.

AppState 🔒

Shared application state passed to all route handlers via Axum’s State extractor.

ErrorBody 🔒

JSON error response body, matching docs/SCHEMAS.md error schema.

ErrorDetail 🔒

Inner error detail with a machine-readable code and human-readable message.

HealthResponse 🔒

JSON response body for GET /health.

ProfileListResponse 🔒

ToolListResponse 🔒

JSON response body for GET /tools/list.

Functions

bad_request 🔒

Constructs a 400 Bad Request error.

classify_tool_error 🔒

Inspects tool execution errors and maps them to the most appropriate HTTP status code. This allows built-in tools to signal client errors (e.g. empty query → 400, document not found → 404) without needing a custom error type in the Tool trait.

handle_health 🔒

Handler for GET /health.

handle_list_agents_compat 🔒

Deprecated prompt-agent discovery endpoint with its historical JSON key.

handle_list_profiles 🔒

Canonical profile discovery endpoint.

handle_list_tools 🔒

Handler for GET /tools/list.

handle_resolve_profile 🔒

Resolve a profile via the canonical route or its legacy agent alias.

handle_tool_call 🔒

Handler for POST /tools/{name}.

is_loopback_bind 🔒

Whether a host:port bind address targets the loopback interface.

not_found 🔒

Constructs a 404 Not Found error.

profile_info 🔒

register_resource_prompts

Register standalone prompt projections, rejecting collisions with all legacy sources (including registry Lua and caller-provided Rust profiles) atomically.

run_server

Starts the MCP-compatible HTTP server.

run_server_multi

Starts the multi-workspace MCP server (ctx serve mcp --workspaces).

run_server_with_extensions

Starts the MCP server with custom Rust tool and profile extensions.

run_server_with_resources

Start a single-workspace server with explicitly selected standalone resources. Resources project static prompts only; no runtime, credentials, or client processes are initialized. Existing library entry points do not discover cwd.

serve_router 🔒

Shared Axum wiring for both compatibility and multi-workspace modes.

timeout_error 🔒

Constructs a 408 Request Timeout error.

tool_error 🔒

Constructs a 500 error for tool execution failures.

Type Aliases

ExtState 🔒

Extra extensions (custom Rust tools and profiles) passed alongside the main AppState.