@context-engine-bridge/context-engine-mcp-bridge provides the ctxce CLI, a Model Context Protocol (MCP) bridge that speaks to the Context Engine indexer and memory servers and exposes them as a single MCP server.

It is primarily used by the VS Code Context Engine Uploader extension, available on the Marketplace:

• https://marketplace.visualstudio.com/items?itemName=context-engine.context-engine-uploader

The bridge can also be run standalone (e.g. from a terminal, or wired into other MCP clients) as long as the Context Engine stack is running.

• Node.js >= 18 (see engines in package.json).
• A running Context Engine stack (e.g. via docker-compose.yml) with:
  • MCP indexer HTTP endpoint (default: http://localhost:8003/mcp).
  • MCP memory HTTP endpoint (optional, default: http://localhost:8002/mcp).
• For optional auth:
  • The upload/auth services must be configured with CTXCE_AUTH_ENABLED=1 and a reachable auth backend URL (e.g. http://localhost:8004).

You can install the package globally, or run it via npx.

npm install -g @context-engine-bridge/context-engine-mcp-bridge

This installs the ctxce (and ctxce-bridge) CLI in your PATH.

npx @context-engine-bridge/context-engine-mcp-bridge ctxce --help

The examples below assume ctxce is available on your PATH; if you use npx, just prefix commands with npx @context-engine-bridge/context-engine-mcp-bridge.

The main entrypoint is:

ctxce <command> [...args]

Supported commands (from src/cli.js):

• ctxce mcp-serve – stdio MCP bridge (for stdio-based MCP clients).
• ctxce mcp-http-serve – HTTP MCP bridge (for HTTP-based MCP clients).
• ctxce auth <subcmd> – auth helper commands (login, status, logout).

These environment variables are respected by the bridge:

• CTXCE_INDEXER_URL – MCP indexer URL (default: http://localhost:8003/mcp).
• CTXCE_MEMORY_URL – MCP memory URL, or empty/omitted to disable memory (default: http://localhost:8002/mcp).
• CTXCE_HTTP_PORT – port for mcp-http-serve (default: 30810).

For auth (optional, shared with the upload/auth backend):

• CTXCE_AUTH_ENABLED – whether auth is enabled in the backend.
• CTXCE_AUTH_BACKEND_URL – auth backend URL (e.g. http://localhost:8004).
• CTXCE_AUTH_TOKEN – dev/shared token for ctxce auth login.
• CTXCE_AUTH_SESSION_TTL_SECONDS – session TTL / sliding expiry (seconds).

The CLI also stores auth sessions in ~/.ctxce/auth.json, keyed by backend URL.

The stdio bridge is suitable for MCP clients that speak stdio directly (for example, certain editors or tools that expect an MCP server on stdin/stdout).

ctxce mcp-serve \
  --workspace /path/to/your/workspace \
  --indexer-url http://localhost:8003/mcp \
  --memory-url http://localhost:8002/mcp

Flags:

• --workspace / --path – workspace root (default: current working directory).
• --indexer-url – override indexer URL (default: CTXCE_INDEXER_URL or http://localhost:8003/mcp).
• --memory-url – override memory URL (default: CTXCE_MEMORY_URL or disabled when empty).

The HTTP bridge exposes the MCP server via an HTTP endpoint (default http://127.0.0.1:30810/mcp) and is what the VS Code extension uses in its http transport mode.

ctxce mcp-http-serve \
  --workspace /path/to/your/workspace \
  --indexer-url http://localhost:8003/mcp \
  --memory-url http://localhost:8002/mcp \
  --port 30810

Flags:

• --workspace / --path – workspace root (default: current working directory).
• --indexer-url – MCP indexer URL.
• --memory-url – MCP memory URL (or omit/empty to disable memory).
• --port – HTTP port for the bridge (default: CTXCE_HTTP_PORT or 30810).

Once running, you can point an MCP client at:

http://127.0.0.1:<port>/mcp

These commands are used both by the VS Code extension and standalone flows to log in and manage auth sessions for the backend.

ctxce auth login \
  --backend-url http://localhost:8004 \
  --token $CTXCE_AUTH_SHARED_TOKEN

This hits the backend /auth/login endpoint and stores a session entry in ~/.ctxce/auth.json under the given backend URL.

ctxce auth login \
  --backend-url http://localhost:8004 \
  --username your-user \
  --password your-password

This calls /auth/login/password and persists the returned session the same way as the token flow.

Human-readable status:

ctxce auth status --backend-url http://localhost:8004

Machine-readable status (used by the VS Code extension):

ctxce auth status --backend-url http://localhost:8004 --json

The --json variant prints a single JSON object to stdout, for example:

{
  "backendUrl": "http://localhost:8004",
  "state": "ok",           // "ok" | "missing" | "expired" | "missing_backend"
  "sessionId": "...",
  "userId": "user-123",
  "expiresAt": 0           // 0 or a Unix timestamp
}

Exit codes:

• 0 – state: "ok" (valid session present).
• 1 – state: "missing" or "missing_backend".
• 2 – state: "expired".

ctxce auth logout --backend-url http://localhost:8004

Removes the stored auth entry for the given backend URL from ~/.ctxce/auth.json.

The VS Code Context Engine Uploader extension is the recommended way to use this bridge for day-to-day development. It:

• Launches the standalone upload client to push code into the remote stack.
• Starts/stops the MCP HTTP bridge (ctxce mcp-http-serve) for the active workspace when autoStartMcpBridge is enabled.
• Uses ctxce auth status --json and ctxce auth login under the hood to manage user sessions via UI prompts.

This package README is aimed at advanced users who want to:

• Run the MCP bridge outside of VS Code.
• Integrate the Context Engine MCP servers with other MCP-compatible clients.

You can safely mix both approaches: the extension and the standalone bridge share the same auth/session storage in ~/.ctxce/auth.json.