Context Bridge

The Context Bridge is Ensemble's MCP server for editors and agents. An agent uses it to read Ensemble: a brief for its task (where the task came from, who asked, the people and their roles, related work), any record and what it links to (the context graph, 03 §5), ranked search, tasks, projects, repositories, skills, deliverables, calendar, people, Needs me, files and their contents, diagrams and plots, and through the read actions everything else the assistant reads. A key made with changes allowed also runs Ensemble's writes (tasks, pages, boards, diagrams, plots, new files, projects, people, deliverables, meeting notes, comments, skills, routines, reminders, desk lists, imports; §5.1), and a key made with apps allowed uses the apps the person connected to Ensemble (§5.2). A key works in its own space and in every other space its account owns (§4).

The server is apps/context-bridge. It calls hub-api's /api/bridge routes over HTTP. It never opens the database or holds model or app keys. The editor runs its own model; Ensemble supplies the records, runs the actions with the assistant's own tools, and calls the apps with the person's connections.

1. Three ways to reach it

All ways use the same Context Bridge and /api/bridge checks. Stdio and ordinary static keys use buildServer (apps/context-bridge/src/server.ts). Hosted OAuth uses buildCatalogServer (src/catalog.ts, exported as @ensemble/context-bridge/catalog): the core tools and resources plus named operations instead of catch-alls (§5.4). x-ensemble-tools: catalog selects that profile for a static key; legacy selects the existing tool names. This changes metadata, not grants.

Write tools require changes allowed and app tools require apps allowed. Hosted requests read the grants from the token; CLI and source builds ask GET /api/bridge/whoami at start (buildServerForKey). The hosted endpoint cannot see the editor's disk: ensemble_brief needs task or repo and branch, ensemble_upload_file takes dataBase64, and ensemble_get_file cannot use saveTo. Local bridges detect the repository, read a path and save into the working folder. Actions and connected apps run on Ensemble's server in either profile.

2. Architecture

Editor / MCP client
    → stdio bridge | loopback HTTP bridge | hosted /mcp
    → apps/context-bridge/src/server.ts (buildServer)
    → hub-api /api/bridge routes, scoped to the key's space or another its account owns
    → bridge/service.ts over saved workspace records

MCP server-info reports the release version from @ensemble/shared-types/version.

3. Run it from source

pnpm bridge:build          # tsc → apps/context-bridge/dist
pnpm bridge:start          # stdio (what editors launch)
pnpm bridge:http           # Streamable HTTP on 127.0.0.1:4010
pnpm bridge:verify         # hub-api bridge tests, then typecheck, MCP tests, build, smoke

hub-api has to be up (pnpm dev), or every tool returns: Ensemble is not running. Start it with `pnpm dev`.

The bridge calls HUB_API_URL, else the local desktop or CLI runtime from its api.json (DESKTOP §3.2), else http://$HUB_API_HOST:$HUB_API_PORT (default 127.0.0.1:4000). Found through api.json, it uses that file's launch token and reads the file again before each call, so a restarted app (new port and token) keeps working; tools then say The Ensemble app is not running on this computer when it is closed. This is how editors use a local-only desktop app without the CLI: Connect your apps there shows the command (GET /api/desktop/mcp, DESKTOP §1.2).

4. Token

The Hub's Connect your apps page (/connect) creates a key, fills in this computer's paths and offers one-click install for VS Code and Cursor.

1. Connect your apps → Create a key. The value starts with ens_ and is shown once. It can read /api/bridge (files included, §5), call /mcp, run the read actions and revoke itself at /api/cli/logout. Two grants, both ticked by default (POST /api/connect/token):

   • Let editors and agents make changes (canWrite, api_tokens.can_write): the task writes, file uploads and every write action on the allowlist (§5.1).
   • Let editors and agents use your connected apps (canUseApps, api_tokens.can_use_apps): the apps' tools through Ensemble (§5.2); changing something in an app also needs the first grant.

   The key list shows each key's grants. Keys made before 0.7.1 only read (their task-update grant was narrower and was reset): make a new key, or run ensemble login again (the /link page asks the same two questions). A key made under Settings → Connections → Editors & agents is a full key: it has both and can drive editor hooks.

2. Export it where the editor can see it:

export ENSEMBLE_BRIDGE_TOKEN=ens_...

ENSEMBLE_BRIDGE_TOKEN must start with ens_. With no token and no HUB_API_URL, the bridge uses a running desktop or CLI runtime's launch token from api.json. Otherwise every tool returns a configuration error; the bridge never falls back to the default internal token.

hub-api's ENSEMBLE_INTERNAL_TOKEN is the agent-runtime service credential and defaults to dev-internal-token, which hub-api warns about at startup. The bridge uses it only with ENSEMBLE_BRIDGE_USE_INTERNAL_TOKEN=true, and refuses the default value unless ENSEMBLE_BRIDGE_ALLOW_DEFAULT_INTERNAL_TOKEN=true is also set (local demos only, never on a shared network). Set a private one (openssl rand -hex 32) if anything besides this machine can reach port 4000. ENSEMBLE_DEV_AUTH_BYPASS is refused on /api/bridge/*.

Spaces. A bridge or full key acts in the space it was made in (its default). A request that names another space with x-ensemble-space: <space id> acts there when the key's account owns it (keyIdentity in apps/hub-api/src/lib/auth.ts, checked with openedSpace() on every request): the account's own space and the spaces it created (28). The account is api_tokens.account_id, set when Connect your apps, Settings or ensemble login makes the key (migration 20261126100000_api_token_account; ensemble login keeps the approving account on cli_auth_requests.account_id until the exchange). A key with no account_id acts for its own row's account when it was made in an account's own space, and stays in its space when it was made inside another. Refusals are one sentence and nothing falls back to another space:

The MCP tools take the space as space (§5), GET /api/bridge/spaces lists the spaces, and GET /api/bridge/whoami says whether the key may name one. Device, hook and transfer keys and signed-in pages ignore the header; Ensemble Node's delegated requests use it with their own checks (29 §2).

Creating and revoking keys is a signed-in account action; a bridge key cannot mint another key.

4.1 OAuth for AI apps

An app adds the same /mcp URL and discovers /.well-known/oauth-protected-resource/mcp (also served at /.well-known/oauth-protected-resource) and /.well-known/oauth-authorization-server. Unauthenticated MCP gets a 401 Bearer challenge with resource_metadata. HUB_API_PUBLIC_URL is the issuer's HTTPS origin; HTTP loopback is allowed only in development. Metadata and OAuth endpoints (/.well-known/…, /oauth/…) never take a cookie, key or space header as the person's identity, so a key sent there unlocks nothing and is not refused; /oauth/token and /oauth/revoke read Authorization only as the app's client authentication.

POST /oauth/register supports public clients (none) and confidential client_secret_basic or client_secret_post clients. HTTPS client IDs can use CIMD; the public document must match its URL, include its name and redirects, and support none. Fetches are public-only, DNS-pinned, without user credentials or redirects, bounded to 5 seconds and 32 KB. Registered redirects match exactly; an HTTP loopback callback may vary only its port.

GET /oauth/authorize requires authorization-code flow and PKCE S256. The standalone web /oauth page is public, but its consent API requires the signed-in browser session. It preserves the request rather than detouring through onboarding. The person checks the app's name and domains, and approves its requested read/write/app grants and default owned space. Consent is bound to that browser session and expires after 10 minutes. Email signup and Google/GitHub/Microsoft sign-in retain the consent return. All the account's owned spaces remain reachable; shared spaces do not.

POST /oauth/token exchanges a single-use code or refresh token. Explicit resource values must equal this server's /mcp URL; clients omitting it get that sole resource. Access tokens are hashed ens_ bridge keys expiring in one hour. Refresh tokens expire after 30 days and rotate on use; narrowing persists, and replay revokes the entire connection. Issuer identification is returned on success and error callbacks. There is no client_credentials, implicit grant, no-auth or mixed-auth mode.

Confidential registrations may explicitly request ensemble_refresh_token_mode: "persistent" for clients such as Google's Connected Apps persistent-linking flow. Every refresh must authenticate with the client secret; the same refresh credential is returned and its 30-day expiry extends. Narrowed permissions stay narrowed. Public and CIMD clients cannot select this mode and keep rotation/replay detection. Client publishing requirements are vendor-specific; standard public-client security is not weakened.

GET /.well-known/openai-apps-challenge serves the exact plaintext OPENAI_APPS_CHALLENGE value for OpenAI plugin domain verification. It returns 404 when unset, has no identity or workspace context, and is not cached. The operator supplies the portal-generated token for this API hostname; no challenge value or vendor approval is bundled with the code.

POST /oauth/revoke, Connect your apps → Disconnect, and self-logout revoke the whole token family. GET /api/mcp-oauth/connections lists only the signed-in account's connections; consent and disconnect mutations require the browser's origin and CSRF proof. Ephemeral access keys are excluded from manual key lists. Grant metadata is exported with the account; secrets are not. Account or default-space deletion cascades through grants and tokens (07).

5. Tools and resources

Every tool but ensemble_spaces takes an optional space: a space's id or exact name (compared as the space switcher compares names). apps/context-bridge/src/spaces.ts resolves it from GET /api/bridge/spaces (kept 30 seconds) and sends it as x-ensemble-space with each request of that call; hub-api checks it again (§4). A space shared with the account is refused before any call. Resources read the key's default space.

5.1 Changes in Ensemble

ensemble_actions and ensemble_act are offered to every key; the other write tools only to a key that may make changes (§4). read-only.ts refuses to start with a write-named tool outside ensemble_create_task, ensemble_update_task and ensemble_upload_file.

The allowlist (each name is the assistant's tool, 34). Reads run for every key; changes need changes allowed, and those marked apps also need apps allowed:

An action runs in the request's space (the key's own, or one it named, §4) as the person (route-backed tools call the API with the internal credential and x-ensemble-user), with the space's modules. What changes how Ensemble behaves or starts work stays with the person in Ensemble: a name the assistant has but the list does not answers 404 saying so (hub_update_settings, hub_choose_model, hub_edit_layout, hub_stop_activity, hub_assign_to_agent, hub_run_workflow, hub_create_watcher, hub_cancel_watcher, hub_edit_file; hub_view_file points to ensemble_get_file, and hub_web_search and hub_read_web_page are the assistant's own). Guards refuse deleting a file (hub_delete_entity kind document: "Files cannot be deleted from editors and agents; delete it in Ensemble."), deleting a routine and replacing a file's original (403). No action stops or deletes a run or starts the assistant.

A coding agent Ensemble started keeps the everyday part of the list (runActionCaller in workspace/context-tools.ts): the entries not marked keyOnly in BRIDGE_ACTIONS, without deleting a dataset or restoring a skill or reminder; anything else answers "Agent runs cannot use ‹name›…" (30 §9).

GET /api/bridge/whoami answers {canWrite, canUseApps, apps (connected app names), spaceId, spaceName (the request's space), defaultSpace {id, name} (the key's own), crossSpace, crossSpaceNote?, keyName}. Writes are refused (403) for a key without changes allowed, device and hook keys, and every other route; a signed-in page and a full key may use them. Each write refreshes open pages (task, page, documents or assistant.acted events). POST /api/bridge/act/* and /api/bridge/write/* share the hosted MCP rate limit (mcp, 240 a minute per space).

5.2 Connected apps

Both tools exist only for a key with apps allowed. App tools are offered and checked as for the assistant (assistant/apps.ts): the suite connected, the product switched on, the scopes granted; app writes are left out when Settings → Assistant turns connected-app writes off. A change in an app also needs changes allowed, runs at once through runOutsideWrite (ledgered as apps.<tool>), and cannot be undone from Ensemble. Calls run on Ensemble's server, so the hosted URL and the CLI reach the same apps and the editor needs no app keys.

5.3 What each way in can do

A coding agent that Ensemble starts on a paired computer has ensemble_actions and ensemble_act in its run's own MCP server, under the job's lease, with the everyday part of the list (§5.1), and ensemble_apps and ensemble_app_call with the connected apps as above (§5.2; the person's own agent in Chat has the apps too), only in its owner's own space (30 §9). So every way an agent reaches Ensemble (a key in an editor, a run Ensemble starts, the assistant, a node) reaches the person's connected apps through it.

A resource URI is an MCP identifier, not permission to open local files. Reads are scoped to the request's space: the key's own, or another its account owns (§4, 28); module checks still apply.

5.4 Named catalog profile

The hosted catalog keeps the existing core reads, resources and dedicated task/file writes. ensemble_actions, ensemble_act, ensemble_apps and ensemble_app_call are replaced by ensemble_action_<name> and ensemble_app_<name> tools built from the same allowed action and connected-app schemas. Names stay within 64 characters; changed or shortened names get a deterministic hash suffix. Enum-based action, operation or method choices become separate fixed-operation tools. No call can select a different underlying action.

Each tool has a title and explicit read-only, destructive, idempotent and open-world hints, plus its required OAuth scopes. Only allowed tools are listed; original API validation, module checks, ownership, grants, Undo and app-write policy still apply. Every tool takes optional space; a provider tool whose own schema has space keeps its arguments under input. Inputs are validated against the published schema before dispatch. Tool errors are MCP errors, not empty results.

• Files. ensemble_read of a document gives a file's name, format, size, page count, summary and link in Ensemble, and search matches a file's name and summary. ensemble_get_file gives Ensemble's text of it when asked and the file itself (§5); the extracted text stays out of search, briefs and ensemble_read (32, files/extracted-text-policy.ts). A task or page also lists its files. A key adds files (ensemble_upload_file, hub_save_file, page exports) and never edits an original or deletes a file.
• Pages. apps/hub-api/src/pages/agent-context.ts adds the source of diagrams embedded in task and standalone pages, with space ownership checks. For the bridge, page bodies are bounded at 15,000 characters and diagram source at 20,000, then paginated. Converted source documents appear in the page's file citations (files/attached.ts).
• Skills. Only the current body is returned. Older SkillVersion bodies are not exposed (hub_read_skill lists recent versions without them), and disabled or deleted skills are left out of briefs (04).
• Trust labels. Mail, chat, GitHub text, calendar invites, approval previews and editor tool inputs are labelled trust: "untrusted"; skills are trusted. The brief repeats that retrieved text is reference material, not instructions.
• Resolution. A branch that matches no task, or several, is reported as such; the bridge never picks a similarly named task.

6. Limits

• Search is ranked word matching plus graph links, not semantic: Artifact.searchVector and ArtifactChunk.embedding exist in the schema but nothing fills or queries them; enabling an embedding provider does not change this.
• Not given: older skill bodies; reminders and layouts only through the read actions. Not changed: anything off §5.1's list, and Needs-me answers.
• Files: one answer carries an original up to 20 MB (FILE_ANSWER_MAX_BYTES in bridge/files.ts); a larger one comes through saveTo in the CLI or a source build, or GET /api/bridge/files/:id/original. Ensemble's text of a file is its extracted text: no OCR, audio or video.
• Spaces: a key reaches the spaces its account owns. Spaces shared with the account are refused, and a key with no account_id made inside a space stays in that space (§4).
• Connected-app copies can be stale until refreshed; bridge reads do not call vendor search.
• The bridge returns stored text without a new redaction pass; ingest and file paths have their own redaction.
• OAuth is authorization-code/PKCE only. A static key or stdio remains available; anonymous access to workspace tools is not offered.

The task-scoped scripts/ensemble-ask-mcp.mjs server used inside managed engine runs asks questions for its run and runs the everyday actions under the job's lease. It is not the Context Bridge and does not widen an editor's ens_ key (30).

7. What ensemble_gaps says

apps/hub-api/src/bridge/gaps.ts lists what the bridge does not have or will not give, so a model does not invent it: no embedding search (retrieval is ranked words plus graph links), no redaction pass on bridge reads (ingest and file paths redact), mail, chats and transcripts only when the person saved or imported them, layouts and reminders only through the read actions, no older skill bodies, files (the 20 MB answer and saveTo), other spaces (§4), which changes a key may make (§5.1) and how the connected apps are reached (§5.2). It is not the connector inventory (31).

8. Transports

• stdio (default). No port. Editors launch node apps/context-bridge/dist/index.js, or ensemble mcp from the CLI.
• Hosted Streamable HTTP at https://api.ensemblework.com/mcp. An OAuth access token or static Bearer ens_ key is required; cookies and device keys are refused. Unauthenticated requests receive discovery challenges. Authenticated GET and DELETE return 405. x-ensemble-space goes with every call unless a tool names its own space (§4).
• Local Streamable HTTP (--http) at http://127.0.0.1:4010/mcp. CONTEXT_BRIDGE_PORT changes the port; CONTEXT_BRIDGE_HOST must be 127.0.0.1, localhost or ::1, or the bridge refuses to start. Optional CONTEXT_BRIDGE_HTTP_TOKEN requires Authorization: Bearer on that endpoint; without it, ensemble_upload_file does not read a path (any process on the computer can reach a loopback port). The Hub token stays in the bridge process.

hub-api listens on HUB_API_HOST (default 127.0.0.1). infra/docker-compose.yml publishes Postgres (5432) and Redis (6379) on 127.0.0.1 only, so use 127.0.0.1, not localhost, in DATABASE_URL and REDIS_URL.

9. Client setup

Prefer Connect your apps in the Hub or ensemble mcp setup. Connect your apps has CLI, hosted-URL and from-source guides for VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, Codex, Gemini CLI, GitHub Copilot CLI, Zed, Visual Studio, JetBrains, Cline, Continue, opencode, Qwen Code, Kimi Code and Mistral Vibe (through vibe mcp add) on macOS, Windows and Linux (apps/hub-web/lib/connect/configs.ts).

ensemble mcp setup grok uses Grok Build's own grok mcp add command for stdio or a bearer URL. AI apps and native MCP automation clients use the hosted URL with OAuth or their documented bearer-header option. Claude/Duet, ChatGPT/dots, Cursor, Grok/Grok Bot, Gemini, Muse, Copilot Studio, n8n, Zapier and Make share that server; each vendor controls client availability and approvals. Open-source plugin packages, client helpers and automation templates live in ensemblework/ensemble-integrations. A package or registry entry is not vendor approval or curated placement. The from-source samples are in apps/context-bridge/clients/. Build first (pnpm bridge:build), use absolute paths and never commit a real token. Committed project files use ${env:ENSEMBLE_BRIDGE_TOKEN} or ${ENSEMBLE_BRIDGE_TOKEN}. ${input:…} is avoided because it drops the server from VS Code's Agent Host. One-click links (vscode:mcp/install, cursor://anysphere.cursor-deeplink/mcp/install) keep the key in the environment, not the URL.

claude mcp add --transport stdio \
  --env ENSEMBLE_BRIDGE_TOKEN="$ENSEMBLE_BRIDGE_TOKEN" \
  --env HUB_API_URL=http://127.0.0.1:4000 \
  ensemble -- node "$PWD/apps/context-bridge/dist/index.js"

The repo also ships .github/agents/ensemble.md (a custom agent that calls ensemble_brief and cites sources) and .github/skills/ensemble-context/SKILL.md (copy the folder to ~/.copilot/skills/ensemble-context/ to load it in Copilot CLI everywhere).

10. Failure behaviour

11. Tests

pnpm --filter @ensemble/hub-api test:mcp-oauth exercises the hosted OAuth routes and an MCP SDK client against in-memory PGlite: metadata, DCR/CIMD, consent, PKCE, ownership, client/resource binding, single-use codes, rotating refresh/replay, confidential persistent refresh, disconnect, domain proof and legacy keys. test/catalog.test.ts checks named dispatch and schema/space isolation; web mcp-consent.test.tsx and provider sign-in tests cover grants and returns. These are protocol/component tests, not a claim of live approval by a vendor directory.

pnpm --filter @ensemble/hub-api test:bridge    # resolution, auth, write gating; context, brief by task, ranked search, task writes, actions, uploads, files, spaces and apps on PGlite
pnpm --filter @ensemble/context-bridge test    # in-memory MCP client, stdio, Streamable HTTP, mocked hub-api, file content, saveTo rules, space
pnpm bridge:verify                             # both, plus typecheck, build and dist smoke
pnpm bridge:e2e                                # live Postgres, hub-api, both transports, security

The smoke script (apps/context-bridge/scripts/smoke.ts) speaks MCP to the built server against a mocked hub-api and checks tools/list, a tool call and resources.

pnpm bridge:e2e (scripts/live-e2e.ts) creates the ensemble_pg volume if needed, starts infra/docker-compose.yml, writes a gitignored .env when missing, runs db:generate, db:push and db:seed, builds the bridge, starts hub-api on 127.0.0.1:4000 with ENSEMBLE_DEV_AUTH_BYPASS=true, and mints a real ens_ key through POST /api/connect/token. The seed covers every status, a task linked to encode/httpx on branch docs/default-timeout, two tasks on retry-helper, deliverables, calendar events in the next 14 days, meeting notes, a file and a document, and a pending editor decision; the script also uploads latency-readout.md and opens a Needs-me prompt.

It then connects with the MCP SDK over stdio (as the editor configs do) and over Streamable HTTP at http://127.0.0.1:4010/mcp, calls every tool, reads every resource and item template, and compares payloads with the database (counts, ids, titles, trust labels). Security checks cover bridge-key writes (403 elsewhere in hub-api, 405 on /api/bridge), key minting, refusal of ENSEMBLE_DEV_AUTH_BYPASS and dev-internal-token on bridge routes, loopback binds, refusal of a non-loopback host, missing and invalid tokens, hub-api down, and Postgres/Redis refusing non-loopback connections.

The script leaves hub-api and the HTTP bridge running, writes logs under /tmp/ensemble-bridge-e2e/ and a JSON summary to bridge-e2e-report.json in the repo root, and never prints the token.

A passing handshake does not show that an editor picks the right tool or that a remote client supports bearer headers.