version: "1.0.2" name: mcp-catalog description: Authoritative catalog of MCP servers actually configured and working in this Orchestra workspace. Use this skill whenever you author or generate an orchestration so every mcps: entry references a real MCP. Distinguishes pre-registered MCPs (in orchestra.mcp.json, no top-level declaration needed) from inline-only MCPs (must be declared in the orchestration's top-level mcps: block).

MCP Catalog (workspace-authoritative)

This is the canonical list of MCP servers wired up in this Orchestra workspace. Two classes exist:

1. Pre-registered MCPs — declared globally in

config/Orchestra/orchestra.mcp.json and automatically available to every orchestration. Reference them by name only in a step's mcps: array. Do NOT add a top-level mcps: entry for them in your orchestration — re-declaring them is redundant noise that bloats the YAML.

1. Inline-only MCPs — not in the global registry. **Must be declared in

the orchestration's top-level mcps: block** with full configuration (type, command+arguments for local, or endpoint for remote), then referenced by name in each step's mcps: array.

If a name is not in this catalog, it is not registered — do not fabricate.

Canonical example of mixed usage:

Debug/debug-general-validation.yaml declares only orchestra at the

top-level (inline-only) and references seven pre-registered MCPs via a

single step `mcps: [icm-readonly, icm-full, orchestra, azdo, azure,

powerreview, debug-mcp]`. Match this idiom.

Quick Selector — pick the right MCP by intent

Pre-registered MCPs (orchestra.mcp.json)

These are declared globally. Do NOT add a top-level `mcps:` entry for any of these — Orchestra resolves them automatically. Just list the name in a step's mcps: array.

The pre-registered set in this workspace: calendar, mail, me, m365-copilot, teams, azdo, azure, icm-full, icm-readonly, powerreview, debug-mcp.

Each entry below describes purpose, when-to-use, when-NOT-to-use, and a copy-paste step-level reference snippet.

Microsoft 365 HTTP proxy MCPs (calendar, mail, me, m365-copilot)

These four are served over HTTP by the m365-remote-mcps background service (see orchestra.services.json) on port 5113, fronting config/Orchestra/m365.proxy.json with routing.mode: perServer and basePath: /mcp — endpoints land at http://localhost:5113/mcp/<name>.

`workiq` vs proxy MCPs — when to choose which:

• Prefer `workiq` when an orchestration touches multiple M365 concerns

(e.g. calendar + mail) or when consistency with existing workspace orchestrations matters. workiq is local stdio with a broad toolset.

• Prefer a proxy MCP (calendar / mail / me / m365-copilot) when

you want a smaller, focused toolset for a single concern, or when you specifically need M365 Copilot (m365-copilot) which is not part of workiq.

Auth note: all four use InteractiveBrowser auth with deferConnection: true. The first time an orchestration step touches one of these in a new session, the proxy will prompt for browser auth via ${VSCODE_CLIENT_ID} and ${CORP_TENANT_ID}.

calendar

Use for: listing and inspecting calendar events, attendees, organizers, free/busy, scheduling helpers, time-window searches. Do not use for: mail or Teams operations — pick the matching focused MCP, or workiq. Step-level reference:

steps:
  - name: list-meetings
    type: Prompt
    mcps: [calendar]

mail

Use for: reading, searching, composing, and managing Outlook messages; thread/conversation lookup. Do not use for: calendar or Teams operations. Step-level reference:

steps:
  - name: triage-inbox
    type: Prompt
    mcps: [mail]

me

Use for: the signed-in user's profile and personal information; "me / my org / my manager"-type queries. Do not use for: other people's profiles in bulk — workiq has broader People tooling. Step-level reference:

steps:
  - name: load-my-profile
    type: Prompt
    mcps: [me]

m365-copilot

Use for: Microsoft 365 Copilot tools (search M365 content, generate from M365 data, Copilot-side tooling not in workiq). Do not use for: generic LLM completions — use a Prompt step with model: directly. Step-level reference:

steps:
  - name: search-m365-content
    type: Prompt
    mcps: [m365-copilot]

teams — Microsoft Teams (local stdio)

Pre-registered, but NOT served by the HTTP proxy. Unlike calendar / mail / me / m365-copilot (which are HTTP endpoints on port 5113), teams is a local stdio MCP (McpProxy.Samples.Teams.Mcp via dnx) registered in orchestra.mcp.json. It uses user-auth against ${CORP_TENANT_ID} / ${VSCODE_CLIENT_ID} with a deferred connection, so the first step that touches it in a new session triggers auth. Reference it by name only — do NOT add a top-level mcps: entry.

Use for: dedicated Microsoft Teams tooling — chat messages, channel posts, meeting transcripts, Teams search. Do not use for: calendar / mail / profile work — pick the matching focused proxy MCP, or workiq.

`teams` vs `workiq` for Teams: prefer `teams` for a focused, Teams-only toolset when the step needs nothing else. Prefer `workiq` when the same step also needs calendar / mail / people / AzDO, so one MCP covers every concern. Step-level reference:

steps:
  - name: read-team-channel
    type: Prompt
    mcps: [teams]

azdo — Azure DevOps (full)

Use for: Azure DevOps via the official @azure-devops/mcp package — PRs, work items, repos, builds, releases, comments, threads. Configured for the msazure organization. Do not use for: anything outside AzDO. Microsoft 365 needs go to workiq / proxy MCPs. Note workiq also has some AzDO tools but azdo is the dedicated, broader option. Step-level reference:

steps:
  - name: fetch-pr-details
    type: Prompt
    mcps: [azdo]

azure — Azure resources

Use for: Azure subscriptions, resource groups, ARM operations, deployments, KQL/Log Analytics, RBAC — anything served by Azure.Mcp (azmcp server start). Do not use for: Azure DevOps (use azdo); Microsoft Learn docs (use microsoft-learn). Step-level reference:

steps:
  - name: list-subscriptions
    type: Prompt
    mcps: [azure]

icm-readonly and icm-full — Microsoft IcM (incident management)

Two flavors of the same IcM.Mcp package, sourced from the msazure/One/_packaging/ZTS Azure DevOps feed:

• `icm-readonly` — read-only mode (-- --read-only). Use this by

default. Cannot acknowledge, mitigate, comment, or otherwise change incident state.

• `icm-full` — full read/write. Use only when the orchestration must

change incident state (acknowledge, transfer, mitigate, post comments).

Use for: querying incidents, fetching IcM history, change-management data, RP/SAR investigations. Do not use for: non-IcM tickets (Jira, AzDO work items) — those go to azdo. Step-level reference:

steps:
  - name: investigate-incident
    type: Prompt
    mcps: [icm-readonly]   # or [icm-full] when state changes are required

powerreview — PR review tooling

Use for: authoritative PR review workflow — sync threads from the remote provider, draft replies, vote (approve / wait-for-author), submit reviews, create fix branches (powerreview/fix/thread-{threadId}), and apply other automated PR actions. Do not use for: generic AzDO operations not specific to review state — prefer azdo. Step-level reference:

steps:
  - name: respond-to-comment
    type: Prompt
    mcps: [powerreview]

debug-mcp — MCP debugging harness

Use for: smoke-testing the engine's MCP plumbing during diagnostics (used by Debug/debug-general-validation.yaml). Do not use for: production work — this is a developer harness, not a real capability surface. Step-level reference:

steps:
  - name: smoke-test-mcp
    type: Prompt
    mcps: [debug-mcp]

Inline-only MCPs (declare in top-level mcps:)

These are NOT in the global registry. You MUST declare each one your orchestration uses in its top-level mcps: block before referencing it from a step.

The inline-only set in this workspace: workiq, zakira, recall, context7, microsoft-learn, playwright, orchestra, filesystem.

workiq — Microsoft 365 + Azure DevOps super-MCP

Use for:

• Calendar: list/find/inspect upcoming meetings, attendees, organizers,

acceptance status, recurrence, free/busy.

• Mail: search and read Outlook mail; thread/conversation lookup.
• Teams: chat messages, channel posts, meeting transcripts.
• People / contacts: resolve a name to an attendee record, look up

organizational hierarchy, find teammates.

• Azure DevOps: pull requests (metadata, comments, diffs, threads),

work items, repositories, iterations.

Do not use for: anything outside Microsoft 365 / AzDO.

Top-level definition:

mcps:
  - name: workiq
    type: local
    command: npx
    arguments:
      - "-y"
      - "@microsoft/workiq"
      - mcp

Step-level reference:

steps:
  - name: find-next-meeting
    type: Prompt
    mcps: [workiq]

zakira — persistent state / memory (Zakira.Exchange)

Use for: persisting structured state across orchestration runs (category + key with arbitrary JSON-ish data plus free-form reason); "have I already processed this PR / meeting / item?" patterns; append-only history logs scoped to an orchestration.

Do not use for: live data fetch — it's a memory store, not a query layer.

Shared database path: every orchestration must point Zakira at {{env.XDG_CONFIG_HOME}}/orchestra/zakira.db via the --db flag so that state is shared across all orchestrations on the host. Without --db, Zakira falls back to a path relative to the host process cwd (which is unpredictable and won't be shared with other orchestrations).

PowerShell Script steps that shell out to dnx zakira.exchange must use the same path: declare it once as an orchestration variable (e.g. vars.zakiraDb: "{{env.XDG_CONFIG_HOME}}/orchestra/zakira.db") and pass it as --db <path> to the CLI.

Top-level definition:

mcps:
  - name: zakira
    type: local
    command: dnx
    arguments:
      - Zakira.Exchange
      - "--yes"
      - "--"
      - "--db"
      - "{{env.XDG_CONFIG_HOME}}/orchestra/zakira.db"
      - mcp
      - "--category"
      - "{{vars.zakiraCategory}}"

recall — live web research (Zakira.Recall)

Use for: open-web search, broad fact-finding, fresh research where the agent determines its own search/follow-up strategy.

Do not use for: documentation of specific named libraries (prefer context7); Microsoft documentation (prefer microsoft-learn).

Top-level definition:

mcps:
  - name: recall
    type: local
    command: dnx
    arguments:
      - Zakira.Recall
      - "--yes"
      - --
      - "mcp"

context7 — library / framework documentation (REMOTE)

Use for: looking up usage docs and code snippets for a specific named library or framework; pre-flight research before generating code that depends on a third-party library.

Do not use for: general web search (prefer recall); Microsoft- specific docs (prefer microsoft-learn).

Top-level definition:

mcps:
  - name: context7
    type: remote
    endpoint: "https://mcp.context7.com/mcp"

Note: context7 is a remote MCP — do not use a npx-based local

command. The endpoint above is the canonical Context7 MCP service.

microsoft-learn — Microsoft documentation

Use for: anything documented on learn.microsoft.com — Azure, .NET, Windows, PowerShell, M365 admin, Power Platform, etc.

Do not use for: non-Microsoft third-party libraries (prefer context7).

Top-level definition:

mcps:
  - name: microsoft-learn
    type: remote
    endpoint: "https://learn.microsoft.com/api/mcp"

playwright — browser automation

Use for: scraping or automating a site that has no API; reproducing a bug that requires browser interaction; headless screenshot / DOM- state capture.

Do not use for: anything that has a documented API or MCP — those are cheaper and more reliable.

Top-level definition:

mcps:
  - name: playwright
    type: local
    command: npx
    arguments:
      # Pin an explicit version. npmjs.org is blocked here, and the internal proxy's `@latest`
      # mis-resolves to an abandoned higher-semver prerelease (1.52.0-alpha-*) that lacks --browser
      # and crashes at startup. The proxy carries the current 0.0.x line, so pin it and do NOT
      # force --registry. --yes = non-interactive.
      - "--yes"
      - "@playwright/mcp@0.0.77"
      - "--headless"

orchestra — Orchestra control/data plane introspection

Use for: querying status of past orchestration runs; saving small files via the engine's helpers; working with Orchestra's own state from inside an orchestration; listing pending human-in-the-loop waits and submitting responses to them (so an LLM agent can drive its own approval flows or feed answers back into a paused run).

Do not use for: anything other than Orchestra introspection. The endpoint {{server.url}}/mcp/data is not a Microsoft Graph endpoint, not a generic data API, and not a passthrough to anything else.

Tools exposed (data plane):

Response detail levels (for `invoke_orchestration` sync and `get_orchestration_status`):

• summary — Per-step content is omitted; metadata (contentLength, truncated, hasRawContent, errorMessage, savedFiles) is preserved. Best when you only need failure diagnostics.
• compact (default) — Per-step content truncated to ~8000 chars with ... (truncated) marker + structured metadata. Top-level summary truncated to ~16000 chars.
• full — No truncation. Use sparingly; responses can exceed 100 KB.

When a step's content is truncated and you need the full body, call get_orchestration_step(executionId, stepName, part: "content", length: -1) (or offset/length for paging).

Active-run drill-in. get_orchestration_step now serves data from in-flight runs too, via the host's active execution table. The response shape distinguishes live vs. terminal data:

• source: "active" + runStatus: "running" — the overall run is still going. The targeted step has completed and its content is served from in-memory partial records.
• source: "persisted" + runStatus: "succeeded"|"failed"|"cancelled" — the run terminated; data is from run.json.
• error: "step-in-flight" — the targeted step is currently executing OR hasn't started yet. The response includes:
• runStatus (overall run status)
• stepStatus (running if it's the current step, pending otherwise)
• currentStep (what's running right now)
• completedStepNames (siblings you CAN drill into right now)
• totalSteps / completedSteps

The companion signal: get_orchestration_status for active runs now returns completedStepNames, telling you which sibling steps you can drill into via get_orchestration_step without trial-and-error.

Self-healing pattern (in-process): When a parent orchestration uses a type: Orchestration step, the parent's later steps can drill into the child via template bindings without ANY MCP call:

- name: attempt-1
  type: Orchestration
  orchestration: build-and-test
  mode: sync
 
- name: repair
  type: Prompt
  dependsOn: [attempt-1]
  systemPrompt: |
    Previous attempt {{attempt-1.executionId}} failed with status {{attempt-1.status}}.
    Errors per step:
    {{attempt-1.steps}}
 
    Build step output (for context):
    {{attempt-1.steps.build.output}}
 
    Test step error:
    {{attempt-1.steps.test.error}}

These bindings access untruncated, in-memory data and work for failed/cancelled child runs.

Top-level definition:

mcps:
  - name: orchestra
    type: remote
    endpoint: "{{server.url}}/mcp/data"

Step-level reference for HITL flows:

steps:
  - name: triage-pending-runs
    type: Prompt
    systemPrompt: |
      You are the on-call orchestrator. Use list_pending_inputs to find runs
      awaiting human input, decide whether each one can be auto-resolved,
      and use respond_to_input to unblock the ones you can answer.
    userPrompt: "Triage all pending orchestration approvals."
    mcps: [orchestra]

filesystem — sandboxed local file I/O

Use for: reading or writing files inside a known working directory; creating sub-directories, listing, deleting, moving files.

Do not use for: reaching outside the sandboxed working directory (the MCP refuses paths outside its argument root); filesystem operations on a remote machine (this is local-only).

Top-level definition:

mcps:
  - name: filesystem
    type: local
    command: npx
    arguments:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "{{param.workingDirectory}}"

The last argument is the sandbox root — every path the MCP touches must be a descendant of that directory. Pass it via an orchestration input (workingDirectory) so the caller controls the sandbox.

Hard rules of usage

1. Pre-registered MCPs need NO top-level definition. If you list a

pre-registered name in a step's mcps: array, do not also add it to the orchestration's top-level mcps: block. Re-declaring it is redundant noise.

1. Inline-only MCPs MUST be defined in the top-level `mcps:` block

with full configuration before any step references them.

1. Step `mcps:` is always a list of names (strings) referencing

either pre-registered names or names defined in the top-level mcps: block. Never inline a definition at step scope.

1. Define each inline MCP at most once per orchestration in the

top-level mcps: block. Multiple steps reference it by name.

1. If a step needs no MCP, omit `mcps:` on that step entirely.

Don't include it as an empty list.

1. Never invent an MCP name or endpoint. If the task seems to need

a capability not in this catalog, write a # TODO: note in the orchestration's description: rather than fabricating an MCP.

1. Endpoints are not interchangeable.

• {{server.url}}/mcp/data belongs to orchestra only.
• http://localhost:5113/mcp/<name> belongs to the M365 HTTP proxy

MCPs (calendar, mail, me, m365-copilot); the path segment must match the MCP name exactly. (And these are pre-registered, so you should not be writing endpoints for them at all — just reference the name from a step.)

• https://mcp.context7.com/mcp belongs to context7 only.
• https://learn.microsoft.com/api/mcp belongs to

microsoft-learn only.