mcp-catalog

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

Intended capability	Use this MCP
Microsoft 365 calendar (events, attendees, scheduling)	calendar or workiq
Microsoft 365 mail (Outlook, send/read)	mail or workiq
Microsoft Teams chats / channel messages / meeting transcripts	workiq
Microsoft 365 People / contact lookup / "about me"	me or workiq
Microsoft 365 Copilot capabilities	m365-copilot
Azure DevOps (PRs, work items, repositories, comments)	azdo
Azure resources (subscriptions, resource groups, ARM, etc.)	azure
Microsoft IcM — read-only (incident lookup, status)	icm-readonly
Microsoft IcM — read/write (acknowledge, mitigate, comment)	icm-full
PowerReview (PR review tooling — fetch threads, reply, vote, fix branches)	powerreview
MCP debugging / introspection harness	debug-mcp
Persistent state / memory across runs (key-value, lists, history)	zakira
Live web search / general research	recall
Library or framework documentation lookup	context7
Microsoft Learn / docs.microsoft.com / Azure / .NET docs	microsoft-learn
Browser automation, screenshots, scraping non-API web sources	playwright
Introspecting Orchestra runs / launching child orchestrations from MCP	orchestra
Listing or responding to human-in-the-loop pauses (Approval steps, request_user_input)	orchestra
Local filesystem read/write (sandboxed to a working directory)	filesystem

---

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, 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]

---

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:
      - "@playwright/mcp@latest"
      - "--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):

Tool	Purpose
list_orchestrations	Discover registered orchestrations and their inputs
invoke_orchestration	Start a run (sync or async). Sync mode accepts detail (summary / compact / full) controlling per-step content size. Sync stepResults now include errorMessage per step.
get_orchestration_status	Poll a run's status / fetch results. Accepts detail; per-step results include errorMessage, contentLength, truncated, hasRawContent.
get_orchestration_step	Fetch full or paginated content of one step. Works for BOTH active (in-flight) and persisted runs. Use when a step's content was truncated in get_orchestration_status, or to drill into a sibling step of an active run mid-flight. Supports part (content/rawContent/errorMessage/all) and offset/length paging. Response carries source (active / persisted) and runStatus (the overall run status, distinct from the step's status).
list_child_runs	List runs spawned within the caller's execution chain. Inside an orchestration, defaults to the caller's whole subtree via stamped headers; external callers must pass parentExecutionId or rootExecutionId. Supports status filter and limit/offset.
cancel_orchestration	Cancel a running execution
list_pending_inputs	List runs awaiting human input (Approval steps and orchestra_request_user_input tool calls). Optionally filter by orchestration name.
respond_to_input	Submit a choice and/or reply to unblock a waiting run. Validates against any declared choices and rejects responses for runs with no active wait (e.g., after host restart for engine-tool waits).

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
  orchestrationName: 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.
2. Inline-only MCPs MUST be defined in the top-level mcps: block with full configuration before any step references them.
3. 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.
4. Define each inline MCP at most once per orchestration in the top-level mcps: block. Multiple steps reference it by name.
5. If a step needs no MCP, omit mcps: on that step entirely. Don't include it as an empty list.
6. 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.
7. 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.