@belal-elsabbagh-apex/copilot-mcp

MCP server exposing EHR Copilot operations over stdio. Built with Bun (bun build bundles src/ → a node-runnable dist/server.js), so it runs under either bunx or npx. Published on GitHub Packages.

Tools

33 tools, grouped below by domain. Args lists only the arguments relevant to auth/scope (env, profile, orchestrator) — see each tool's own schema for the rest. Every Copilot tool requires an explicit profile; most also require an explicit env (prod | pre_prod) — neither is ever defaulted. The one exception is list_clinics, which takes env but no profile: it's the discovery tool that produces the profile → clinicUid mapping, so requiring a profile would be circular. Orchestrator tools also take env but no profile (orchestrators auth globally, not per-account), plus an orchestrator (uipath | apex) that is required and never defaulted on every job- or queue-level tool. The carve-outs: find_order_queue_items and find_stuck_orders (omitted = every registered backend) and the Apex-only get_job_artifacts (no orchestrator arg).

Copilot orders

All read tools here are READ-ONLY. Writes (delete_preprod_order, create_preprod_order, submit_preprod_order) only ever target pre-prod; prod is never mutated. There's no single "clone" tool — the clone-and-verify-order prompt (see Prompts below) orchestrates find_clone_candidates → get_order → create_preprod_order (and the settings tools, if a reference doesn't resolve).

Orchestrator (UiPath + Apex) — reads

All READ-ONLY. Every tool takes env and orchestrator (uipath | apex); results come back as { orchestrator, env, … } with backend-neutral cores (JobCore, QueueItemCore, QueueCore, ProcessCore, TriggerCore) and backend-specific fields under details. Job state uses UiPath's vocabulary on both backends (Apex statuses are mapped; rawState keeps the original). One Apex transaction can have many jobs (a retry is a new job on the same queue item), so queue items carry jobs[], newest first.

Orchestrator (UiPath + Apex) — writes (pre-prod only)

env is a schema-enforced literal "pre_prod" on every tool below — "prod" is rejected before any HTTP call (UiPath: the dev-clone folder; Apex: the Authorization Test folder), and every posted payload passes a safety guard.

Settings sync (prod ↔ pre-prod)

diff_settings/get_settings/plan_settings_sync are READ-ONLY; apply_settings_sync is the only settings tool that writes, and it's additive-only against pre-prod (never overwrites/deletes).

Meta / diagnostics

Related MCP server: opencode-codex-mcp

Prompts

User-invokable workflow prompts chain the tools above for common ops tasks: diagnose-order, reconcile-settings, inspect-settings, clone-and-verify-order, triage-stuck-orders, and report-faulted-jobs.

reconcile-settings walks the full settings workflow: list_setting_sections → diff_settings → plan_settings_sync → review the planned action ids with the user → apply_settings_sync with exactly the approved ids. inspect-settings reads one env's settings via get_settings and summarizes them.

clone-and-verify-order picks a cloneable prod order (or uses a given uid), reads it via get_order, and mints an equivalent pre-prod order via create_preprod_order — there's no dedicated "clone" tool, since whether a clone succeeds is order-specific (it depends on pre-prod already having the referenced facility/speciality/order type/order names). If minting fails or the order doesn't reach forReview, the prompt diagnoses via list_setting_sections → diff_settings → plan_settings_sync, reporting a proposed fix rather than applying one. Submitting the resulting order is a separate, explicit submit_preprod_order call that only happens with the user's authorization.

report-faulted-jobs finds faulted jobs on the chosen orchestrator (uipath or apex; prod by default) and files each as a GitHub issue on Apex-Medical-AI-Inc/RPAPlaywright — creating one issue per distinct fault and commenting on the existing issue when the same fault recurs. Apex fault signatures are apex:-prefixed so they never collide with UiPath ones. This server holds no GitHub credentials: the prompt drives a GitHub MCP server connected in the host to do the actual search/create/comment, so that server must be connected with write access to the repo.

Configuration

The server reads one validated config holding the Copilot BE creds and the UiPath / Apex args. Two ways to provide it:

1. Single file (preferred): set COPILOT_MCP_CONFIG to a JSON file shaped like copilot-mcp.config.example.json. If COPILOT_MCP_CONFIG isn't set, the server looks for copilot-mcp.config.json in its working directory (falling back to the older config.local.json name if that's what you already have).

2. Split legacy files: set COPILOT_MCP_LOCAL_DIR to a directory containing order-copy-credentials.json + uipath-config.json.

Each copilot.profiles.<name> entry has a prod/pre_prod env pair, and each env is either:

• a support-account pointer, { "clinicUid": "..." } — the credentials that actually log in come from copilot.support.<env> (shared across every profile using this mode for that env); use the list_clinics tool to look up each clinic's clinicUid, or

• a direct login, { "be", "email", "password", "fe"? } — the original per-account shape, unchanged.

clinicUid wins if a profile entry somehow carries both, which is how an account is migrated to the support-account model one env at a time without deleting its old credentials. Today prod ships as support-account (copilot.support.prod required) and pre-prod stays on direct login, but nothing hard-codes that split — it's whatever each profile's env entries say.

Authenticated sessions (cookies + JWT) are cached in memory and, by default, on disk at ~/.cache/copilot-mcp/sessions.json (mode 0600; $XDG_CACHE_HOME is honored when set to an absolute path; COPILOT_MCP_CACHE overrides the path outright) so a server restart doesn't burn a login. Set "copilot.sessionCache": false to disable disk persistence (memory-only for the process lifetime). This is what keeps the support account's 10-logins-per-15-minutes budget from being exhausted by routine restarts — never commit or echo that cache file, it holds live tokens.

The uipath.queueUrl / addQueueItemPath / serverUrlByEnv fields are only required by build_queue_item. Editing the config file while the server is running takes effect on the next tool call — no restart needed — and the server sends an MCP logging notification when it reloads.

Apex orchestrator (optional)

Add an apex block to enable orchestrator: "apex":

"apex": {
  "apiUrl": "https://orchestrator.apexmedicalai.com",
  "username": "…", "password": "…",
  "folderByEnv": { "prod": "Authorization", "pre_prod": "Authorization Test" },
  "serverUrlByEnv": { "pre_prod": "https://pre-prod-be-batch.ehrcopilotbe.com" },
  "queueUrl": "https://sqs.…"
}

• apiUrl is the load-balancer host, never a CloudFront host (CloudFront caps request bodies at 8 KB).

• username/password are your own login — Apex audits writes per user.

• folderByEnv is optional (the values above are the defaults); folder names resolve to ids at runtime.

• serverUrlByEnv / queueUrl pin what a posted queue item may carry (the write guard fails closed when they are unset).

• Any of apiUrl / username / password the file leaves out is read from APEX_API_URL / APEX_USER_NAME / APEX_PASSWORD. This needs a host that passes its environment through (CLI hosts and bunx do); MCPB installs only pass COPILOT_MCP_CONFIG, so they must use the file.

• With neither source configured, every orchestrator: "apex" call fails with "Apex is not configured"; UiPath and Copilot tools are unaffected. doctor reports which source was used.

get_job_artifacts downloads Apex artifacts to ~/.cache/copilot-mcp/artifacts/<jobId>/ (directory mode 0700, never inside a repo). Treat them as PHI.

See the copilot://reference/config-guide MCP resource for a full field-by-field walkthrough (load order, an annotated JSON template, and the doctor/list_clinics verification steps) — it's what an agent reads to set this server up from scratch.

When a tool fails for a reason that looks like a bug in this server (an unexpected exception — not a bad profile, missing/invalid config, not-found, auth, or any HTTP error the upstream system returned), the error response includes a reportIssue block with a prefilled GitHub new-issue URL. This is on by default; the optional feedback block turns it off or repoints it:

"feedback": { "enabled": false, "repositoryUrl": "https://github.com/your-org/your-fork" }

Migrating from v1.x (v2.0.0 breaking changes)

v2.0.0 puts UiPath and Apex behind one tool surface, so argument names and output shapes became backend-neutral. Skills/prompts that call the old names must be updated.

UiPath state values and UiPath fault signatures are unchanged. Apex job statuses are mapped onto the same state vocabulary (completed→Successful, failed→Faulted, cancelled→Stopped, …); the raw value is always in rawState.

Local development

bun install          # also installs the lefthook pre-commit hook (via `prepare`)
bun run typecheck
bun run lint         # biome check
bun test             # bun's built-in test runner (src/*.test.ts)
bun run build        # bundle src -> dist/server.js (node-runnable, what npx/bunx execute)
bun run start        # run from source via bun (no build needed)
bun run dev          # watch mode

Exercising the tools

bun run inspect launches the MCP Inspector against the server from source — a UI to list and call the tools without a host. Point it at a config first (e.g. COPILOT_MCP_CONFIG=… bun run inspect).

Logging is silent by default so it never corrupts the stdio JSON-RPC stream. Set LOG_LEVEL=debug (or COPILOT_MCP_DEBUG=1) to route progress logs to stderr.

A pre-commit hook (lefthook) runs biome check + typecheck on commit; CI (.github/workflows/ci.yml) runs typecheck/lint/build/test on every PR and push to main.

Installing — run directly from the release asset

Every release attaches a self-contained tarball as a GitHub Release asset, and the repo is public, so npx/bunx can run it straight from the download URL — no registry, no .npmrc, no auth token. The releases/latest/download/copilot-mcp.tgz URL always points at the newest release; swap in a download/vX.Y.Z/… URL to pin a version.

Wire into .mcp.json

{
  "mcpServers": {
    "copilot": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/belal-elsabbagh-apex/copilot-mcp/releases/latest/download/copilot-mcp.tgz"
      ],
      "env": {
        "COPILOT_MCP_CONFIG": "/abs/path/to/copilot-mcp.config.json"
      }
    }
  }
}

npx and bunx are interchangeable here (the published bin, dist/server.js, is a plain node ESM entry). To pin a specific version, use the version-stamped asset instead of latest, e.g. .../releases/download/v1.14.0/belal-elsabbagh-apex-copilot-mcp-1.14.0.tgz. Use COPILOT_MCP_LOCAL_DIR instead of COPILOT_MCP_CONFIG for the split legacy files.

The package is also published to this repo's GitHub Packages registry (see below), but that path needs a read:packages token; the release-asset URL above is the zero-auth default.

Installing — as an MCP Bundle (.mcpb)

Every release also attaches a copilot-mcp.mcpb — a self-contained MCP Bundle (dist/server.js + manifest.json + copilot-mcp.config.example.json) for one-click install in MCPB-supporting hosts (e.g. Claude for macOS/Windows). Download copilot-mcp.mcpb from the latest release, open it with the host, and when prompted for the Config file option point it at your own copilot-mcp.config.json (see copilot-mcp.config.example.json for the shape) — the host launches node dist/server.js with COPILOT_MCP_CONFIG set to that path. Rebuild it locally with bun run mcpb:pack (stages manifest.json + the built dist/ into .mcpb-stage/ and packs it via @anthropic-ai/mcpb); bunx mcpb validate manifest.json / bunx mcpb info copilot-mcp.mcpb are useful for checking it without a host.

Publishing

Publishing is tag-driven. Bump version in package.json, commit, then push a matching vX.Y.Z tag:

git tag v1.2.0
git push origin v1.2.0

That one tag push fans out to two workflows (both keyed off the tag, because a GITHUB_TOKEN-created release does not trigger other workflows):

• Release on tag (release.yml) — builds the bundle, npm packs it, and creates a GitHub Release with auto-generated notes. It attaches two tarball assets: the version-stamped belal-elsabbagh-apex-copilot-mcp-X.Y.Z.tgz (for pinning) and a stable-named copilot-mcp.tgz that backs the releases/latest/download/copilot-mcp.tgz URL used above.

• Publish (publish.yml) — typechecks, builds, and runs bun publish to GitHub Packages using the repo's GITHUB_TOKEN (packages: write); the package inherits the repository's public visibility. Also runnable manually via workflow_dispatch.