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:

• 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.

Prerequisites

• 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).

Installation

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

Global install

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

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

Using npx (no global install)

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.

CLI overview

The main entrypoint is:

ctxce <command> [...args]

Supported commands:

• ctxce index <path>... – upload and index one or more folders once (no watcher).
• ctxce connect <api-key> – authenticate, index, and watch a workspace (the main entry point).
• ctxce stop – stop a running daemon.
• ctxce status – show the logged-in backend and user, plus daemon status.
• 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).
• ctxce --diagnose – check auth, backend reachability, collection, and LSP.

Run ctxce --help for an overview, or ctxce help <command> (e.g. ctxce help index) for a command's options and examples.

Environment variables

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).
• CTXCE_API_KEY – API key for ctxce index (used for that run only; never stored). Sent only to --backend-url / CTXCE_AUTH_BACKEND_URL, or to the default SaaS backend when you have no stored login for another backend.

The CLI also stores auth sessions in ~/.ctxce/auth.json, keyed by backend URL. The file is readable only by you (mode 0600, in a 0700 directory).

Indexing one or many folders (ctxce index)

ctxce index uploads and indexes one or more local folders once and exits — no file watcher, no daemon. Each folder can be a git repository or a plain folder; each one gets its own collection, resolved the same way ctxce connect resolves it. The same upload rules as connect apply: only recognized source/config/docs file types are sent, built-in ignores (.git, node_modules, virtualenvs, build output, binaries, ...) and the folder's .gitignore are honored, and empty files or files of 10 MB or more are skipped.

# Log in once (stores a session in ~/.ctxce/auth.json) ...
ctxce auth login --token <your-api-key>

# ... then index as many folders as you like
ctxce index ~/code/api ~/code/web ~/notes

# Every repo under ~/code, four at a time
ctxce index ~/code/*/ --concurrency 4

# Read the list from a file (one path per line; blank lines and # comments are ignored)
ctxce index --from repos.txt

# CI / scripts: API key from the environment, JSON summary on stdout
CTXCE_API_KEY=<your-api-key> ctxce index . --json

# Fire and forget: return once the uploads are accepted
ctxce index ~/code/api ~/code/web --no-wait

By default the command waits for evidence that the server indexed each upload, polling the upload service's indexing status. Progress goes to stderr, one line per step. Long steps keep reporting (upload percentage, seconds spent waiting for the server, elapsed indexing time), so a slow server never looks like a hung client:

[ctxce] Indexing 2 folders on https://dev.context-engine.ai as ada, org acme (concurrency 2)
[ctxce] [1/2] api: scanning and uploading...
[ctxce] [2/2] web: scanning and uploading...
[ctxce] [1/2] api: git history: 764 commits in 0.2s
[ctxce] [1/2] api: sent 588KB; waiting for server response...
[ctxce] [2/2] web: git history: 120 commits in 0.1s
[ctxce] [2/2] web: sent 210KB; waiting for server response...
[ctxce] [1/2] api: uploaded 1204 files; waiting for indexing...
[ctxce] [1/2] api: initializing, 2.1s elapsed
[ctxce] [2/2] web: uploaded 310 files; waiting for indexing...
[ctxce] [1/2] api: indexed in 48.9s (acme_api-1a2b3c4d)
[ctxce] [2/2] web: uploaded (acme_web-5e6f7a8b); accepted; the server still reports 'watching', so completion isn't confirmed (indexing continues server-side)

followed by a summary table on stdout. The collection column shows the server's name for each collection (SaaS prefixes it with your organization):

STATUS    FILES   TIME  COLLECTION          PATH
indexed    1204  48.9s  acme_api-1a2b3c4d   /Users/ada/code/api
uploaded    310  31.4s  acme_web-5e6f7a8b   /Users/ada/code/web

2 folders: 1 indexed, 1 uploaded
'uploaded' means the server accepted the upload; indexing continues server-side.

A folder is reported indexed only when the status shows this upload being processed and then finishing: a new collection goes from initializing through idle (while its points arrive) to watching, or the state changes after the upload and then settles. idle never counts as finished, and neither does a point count that stops changing. When you re-index an existing collection the server keeps reporting its previous state while it works, so the CLI can't observe completion: it keeps waiting while the point count changes, then reports uploaded (accepted, indexing may continue on the server) once the count has held steady for about 30 seconds, or after about 30 seconds if it never changed. It also reports uploaded if the indexing status can't be read at all.

Git repositories also upload their commit history (messages, changed files, and a truncated diff per commit). The first upload of a repository sends its most recent 5,000 commits, and later runs send only new commits. To send the older commits too, run again with REMOTE_UPLOAD_GIT_MAX_COMMITS=0, or with REMOTE_UPLOAD_GIT_FORCE=1, which re-sends the full history as a snapshot. Setting REMOTE_UPLOAD_GIT_MAX_COMMITS to a different limit (0 = all) than the history was sent with collects it again under the new limit; REMOTE_UPLOAD_GIT_SINCE limits by date. For partial clones (git clone --filter=blob:none and similar) diffs are skipped and nothing is fetched from the remote, since reading them would download every missing blob one commit at a time. If an upload fails, or the server skips it as unchanged, its history is sent again on the next run.

Index flags

| Flag | Alias | Description | |------|-------|-------------| | <path>... | | Folders to index (relative paths resolve against the current directory; duplicates are indexed once). Different folders with the same name are refused, because a collection is named after its folder and they would share one | | --from <file> | --from-file | Read folder paths from a file, one per line (- reads stdin) | | --api-key <key> | -k | API key for this run only (or set CTXCE_API_KEY). Never printed or stored. Default: your ctxce auth login session | | --backend-url <url> | --auth-url | Backend to use. Default: CTXCE_AUTH_BACKEND_URL, then your stored login, then https://dev.context-engine.ai. Required with an API key when you're logged in to a different backend (see below) | | --concurrency <n> | -c | Folders processed in parallel (default: 2, max: 16) | | --no-wait | | Don't wait for server-side indexing; report uploaded once each upload is accepted | | --timeout <seconds> | | Max time to wait for indexing per folder (default: 1800). Indexing continues server-side after a timeout | | --json | -j | Print a JSON summary on stdout (progress stays on stderr) | | --verbose | -V | Show detailed uploader logs |

Per-folder statuses:

• indexed: the server showed this upload being indexed and finishing.
• uploaded: accepted; indexing continues server-side but its completion wasn't observable. This is typical when re-indexing an existing collection or when the indexing status can't be read, and is always the case with --no-wait.
• unchanged: the server already had this content.
• empty: nothing to index (no code files or git history).
• degraded: indexed with low coverage; the server retries automatically.
• failed, timeout, skipped (not attempted because the server rejected the session earlier in the run).

The --json summary looks like this:

{
  "ok": false,
  "backend": "https://dev.context-engine.ai",
  "results": [
    { "path": "/Users/ada/code/api", "collection": "acme_api-1a2b3c4d", "files": 1204,
      "status": "indexed", "durationMs": 48912, "error": null },
    { "path": "/Users/ada/code/old", "collection": null, "files": null,
      "status": "failed", "durationMs": 0, "error": "path not found" }
  ]
}

Exit codes:

• 0 – every folder is indexed, uploaded, unchanged, or empty.
• 1 – a folder failed, was degraded, timed out, or was skipped, or the backend was unreachable or returned a server error (worth retrying).
• 2 – usage or credentials problem: bad arguments, different folders with the same name, not logged in, key or session rejected, or an API key with an ambiguous backend. Nothing was uploaded.

Auth and safety:

• With a stored login, the session is checked once (GET /auth/me) before any folder is scanned. An expired or revoked session fails fast with a pointer to ctxce auth login. If you used ctxce connect <api-key> and its session has expired, ctxce index renews it in memory with the key connect saved, the same way the background sync daemon does.
• Without a key or stored login, ctxce index checks GET /auth/me once without credentials: a backend with auth disabled answers 404, and the folders are then uploaded without a session. Otherwise it stops with "Not logged in".
• An API key (--api-key / CTXCE_API_KEY) is sent only to --backend-url / CTXCE_AUTH_BACKEND_URL, or to the default SaaS backend when you have no stored login for a different backend. If you're logged in elsewhere (for example a local backend whose key the VS Code extension exported), the command refuses and asks for --backend-url instead of guessing. The target backend is printed before the key is sent. The key itself is never printed or stored, and a folder argument that looks like a key is rejected without being echoed.
• Ctrl+C, SIGTERM, or a closed terminal (SIGHUP) removes the temporary bundles ($TMPDIR/ctxce-*) before exiting with 130, 143, or 129.

Connect and daemon mode

The connect command is the primary entry point for CLI users. It authenticates with the Context Engine SaaS, indexes your workspace, and optionally watches for file changes.

Basic usage

# Authenticate and index the current directory
ctxce connect <your-api-key>

# Specify a workspace
ctxce connect <your-api-key> --workspace /path/to/repo

Running as a daemon

Use --daemon (or -d / --bg) to fork the process into the background:

ctxce connect <your-api-key> --workspace /path/to/repo --daemon

The daemon:

• Detaches from your terminal and runs in the background.
• Writes logs to ~/.context-engine/daemon.log.
• Stores its PID in ~/.context-engine/daemon.pid.
• Watches for file changes every 30 seconds (configurable with --interval).

Daemon management

# Show the logged-in backend/user and whether the daemon is running
ctxce status

# Stop a running daemon
ctxce stop

Connect flags

| Flag | Alias | Description | |------|-------|-------------| | <api-key> | --api-key, -k | Your Context Engine API key (positional or flag) | | --workspace <path> | --path, -w | Workspace root (default: current directory) | | --daemon | --bg, -d | Run as a background daemon | | --interval <seconds> | | File watch interval (default: 30) | | --no-watch | --once | Index once without watching for changes | | --skip-index | --auth-only | Authenticate only, skip initial index |

Running the MCP bridge (stdio)

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).

Running the MCP bridge (HTTP)

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

Auth helper commands (ctxce auth ...)

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

Login (token)

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.

Login (username/password)

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.

Status

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".

Logout

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

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

Relationship to the VS Code extension

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.

Related

• Context-Engine — main MCP server
• Context-Engine-Extension — VS Code extension
• Context-Engine-IaC — deployment infrastructure
• Context-Engine-FrontEnd — web UI & admin dashboard