Context Engine MCP bridge (http/stdio proxy combining indexer + memory servers)
npm install @context-engine-bridge/context-engine-mcp-bridge@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:
-
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.
``bash`
npm install -g @context-engine-bridge/context-engine-mcp-bridge
This installs the ctxce (and ctxce-bridge) CLI in your PATH.
`bash`
npx @context-engine-bridge/context-engine-mcp-bridge ctxce --help
The examples below assume ctxce is available on your PATH; if you use npx,npx @context-engine-bridge/context-engine-mcp-bridge
just prefix commands with .
The main entrypoint is:
`bash`
ctxce
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
- – 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 memoryhttp://localhost:8002/mcp
(default: ).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).
`bash`
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 orhttp://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 itshttp transport mode.
`bash`
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_PORT30810
or ).
Once running, you can point an MCP client at:
`text`
http://127.0.0.1:
)These commands are used both by the VS Code extension and standalone flows to
log in and manage auth sessions for the backend.
`bash`
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.
`bash`
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:
`bash`
ctxce auth status --backend-url http://localhost:8004
Machine-readable status (used by the VS Code extension):
`bash`
ctxce auth status --backend-url http://localhost:8004 --json
The --json variant prints a single JSON object to stdout, for example:
`json`
{
"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".
`bash`
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 activeautoStartMcpBridge
workspace when is enabled.ctxce auth status --json
- Uses 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`.