MCP Tools Reference
The catalog below was checked against the registered tools in mctl-api at b8203cf. The deployed version and your permissions determine the tools you can discover and call. Use MCP tools/list for the current input schemas and annotations; a catalog entry is not a grant of access. See Authorization.
Workflow-backed tools return submission information; poll the returned workflow name and inspect service health separately. Registry, identity, incident and commerce operations use their own stores and do not all produce Git commits.
Registered tools
| Tool | Purpose | Annotations |
|---|---|---|
mctl_whoami | Check your current authentication status on the mctl platform. Schema source | Read |
mctl_list_tenants | List all team workspaces on the platform with their resource quotas and member counts. Requires admin access. Schema source | Read |
mctl_get_tenant | Get details of a specific team workspace: members, quotas, and services (same rows as mctl_list_services). If servicesComplete is false, ArgoCD could not be read and services deployed outside the catalogue are missing from the list. Schema source | Read |
mctl_list_services | List the services of a team: catalogue services and every ArgoCD application deployed into the team's namespace. Schema source | Read |
mctl_get_service_status | Get detailed status of a service including ArgoCD sync state, health status, and service configuration. Use this to check if a service is healthy and up-to-date. Schema source | Read |
mctl_get_service_config | Get full configuration of a service from the GitOps repo: image tag, host, port, component type, and database status. Use this when you need full details beyond what list_services provides. Secrets are not returned as plaintext; inspect the response visibility rules before sharing configuration. Schema source | Read |
mctl_list_workflows | List recent Argo Workflow runs for a team. Schema source | Read |
mctl_get_workflow_status | Get status and logs of an Argo Workflow run. Use this after triggering an operation (deploy, create tenant, etc.) to check if it completed successfully. Also works for cron-driven runs (mctl-agents-issue-poll, -implement, -run, -shepherd, ...) that never appear in the audit log — admins get a live Kubernetes lookup as a fallback. Schema source | Read |
mctl_get_resource_usage | Get resource quota usage for a team workspace: CPU, memory, pods used vs allocated. Use this to check if a team is running low on resources. Schema source | Read |
mctl_list_recent_operations | List the most recent platform operations from the audit log (up to 50 entries). Shows who ran what operation, when, and what workflow was triggered. Useful for reviewing recent activity before making changes. Schema source | Read |
mctl_list_operations | List all available platform operations with their parameters, risk levels, and descriptions. Use this to discover what actions are available on the platform. Schema source | Read |
mctl_get_operation | Get detailed schema of a specific platform operation: all parameters with types, defaults, validation patterns, and risk level. Use this to understand exactly what an operation requires before executing it. Schema source | Read |
mctl_list_repos | List GitHub repositories available to a team for deployment. Schema source | Read |
mctl_grant_repo_access | Generate a GitHub App installation URL to grant the platform access to a repository. Schema source | Write |
mctl_get_service_logs | Fetch recent log lines for a service from Loki. Schema source | Read |
mctl_get_workflow_logs | Fetch Argo Workflow step logs from the workflow log archive. Schema source | Read |
mctl_list_previews | List active preview environments for a team. Schema source | Read |
mctl_scale_service | Scale a service by updating its autoscaling configuration. Schema source | Write |
mctl_deploy_service | Deploy a service to the platform. Schema source | Write |
mctl_list_platform_skills | List platform-wide skills available to the current user after visibility, status, and tenant binding filters. Schema source | Read |
mctl_read_platform_skill | Read a platform-wide skill from the GitOps catalog if the current user has access. Schema source | Read |
mctl_list_tenant_skill_bindings | List platform skill bindings for tenants. Admins see all bindings; tenant members see their own. Schema source | Read |
mctl_enable_tenant_skill | Admin-only. Enable an active tenant-visible platform skill for a tenant through a GitOps workflow. Schema source | Write |
mctl_disable_tenant_skill | Admin-only. Disable a platform skill for a tenant through a GitOps workflow. Schema source | Destructive |
mctl_publish_platform_skill | Admin-only. Publish or update a platform-wide skill through a GitOps workflow. Schema source | Write |
mctl_deprecate_platform_skill | Admin-only. Mark a platform-wide skill deprecated through a GitOps workflow. Schema source | Destructive |
mctl_create_tenant | Create a new team workspace on the platform. Schema source | Write |
mctl_provision_database | Provision a PostgreSQL database on the shared CNPG cluster. Schema source | Write |
mctl_retire_service | DESTRUCTIVE: Remove a service from the platform permanently. Schema source | Destructive |
mctl_delete_tenant | DESTRUCTIVE: Delete a team workspace and all its platform resources permanently. Schema source | Destructive |
mctl_sync_repos | Discover and register GitHub repositories for a team. Schema source | Write |
mctl_rollback_service | Roll back a service to a previously deployed image tag. Schema source | Destructive |
mctl_create_preview | Deploy an ephemeral preview environment for a service. Schema source | Write |
mctl_delete_preview | Remove a preview environment and all its Kubernetes resources immediately. Schema source | Destructive |
mctl_add_custom_domain | Register a custom domain for a service. This step ONLY registers — it does NOT touch ingress or DNS yet, and does NOT trigger the add-custom-domain workflow. Schema source | Write |
mctl_remove_custom_domain | Remove a custom domain from a service. If the domain is registered in mctl-api's domain registry (added via mctl_add_custom_domain), this deletes that registry row — DELETE /api/v1/domains/{id} — which itself triggers the remove-custom-domain workflow to clean up the ingress host and TLS certificate entry before the row disappears. If the hostname is not found in the registry (e.g. a legacy domain added before the registry existed), this falls back to triggering the remove-custom-domain workflow directly, same as before. The auto-generated {team}-{service}.{platform_domain} domain is not affected either way. Schema source | Destructive |
mctl_list_domains | List custom domains for a team or specific service. Shows domain, auto-generated domain ({team}-{service}.{platform_domain}), status (pending/verified/active), and verification timestamp. Schema source | Read |
mctl_verify_domain | Check if a custom domain's DNS is correctly configured, and — on success — trigger the add-custom-domain workflow (ingress update + TLS certificate). Verifies the TXT ownership challenge (_mctl-challenge.<domain>) that mctl_add_custom_domain returned; also accepts an unproxied CNAME straight to {team}-{service}.{platform_domain} as a fast path. TXT is checked first because Cloudflare and similar proxies rewrite A/CNAME answers but never the TXT record. This is the step that starts the workflow — mctl_add_custom_domain itself only registers and does not trigger it, since the challenge this call verifies cannot exist before that registration returns. Schema source | Write |
mctl_erpact_list_sites | ERPact-specific and provisional (mctl-api#486): list tenant erpact's sites, with each one's lifecycle status (creating, active). Visible to and callable by tenant erpact's owners and platform admins only. A failed read of the deployer is reported as an error, never as an empty list. Schema source | Read |
mctl_erpact_create_site | ERPact-specific and provisional (mctl-api#486): create a new site for tenant erpact. Requires the owner role on tenant erpact; only works for tenant erpact. Schema source | Write |
mctl_erpact_site_status | ERPact-specific and provisional (mctl-api#486): the lifecycle status of one tenant-erpact site (creating, active), for following up on mctl_erpact_create_site. Visible to and callable by tenant erpact's owners and platform admins only. Schema source | Read |
mctl_list_incidents | List platform incidents (alerts from AlertManager, GitHub Actions failures, polling). Schema source | Read |
mctl_get_incident | Get full details of an incident including evidence, analysis, and PR information. Schema source | Read |
mctl_incident_summary | Get aggregate counts of active incidents by status, severity, and type. Schema source | Read |
mctl_acknowledge_incident | Mark an incident as acknowledged/reviewed. Schema source | Write |
mctl_resolve_incident | Mark an incident as resolved. Schema source | Write |
mctl_trigger_agents_run | Trigger a full mctl-agents run — every service-agent (researcher → analyst → spec-writer in parallel) followed by the mentor weekly digest. Same as the weekly Saturday 00:00 UTC cron, on demand. Schema source | Write |
mctl_trigger_mentor_only | Trigger mentor only — re-aggregates the existing per-service proposals into a fresh weekly digest. Skips the expensive service-agent runs. Useful after manually triaging proposals when you want the digest to reflect updated state. Schema source | Write |
mctl_trigger_single_service | Trigger one service-agent only (no mentor). Useful after a large change in a specific repo when you want fresh proposals for that service without paying for a full pipeline run. Schema source | Write |
mctl_trigger_incident_responder | Trigger the incident responder: diagnose TypeGeneric incidents stuck in status=analyzing (older than 30 minutes) and write auto-accepted proposals for the Tier 2 implementer, then resolve the incident. Same as the every-30-minute cron (15,45 * * * * UTC), on demand. Schema source | Write |
mctl_trigger_implementer | Trigger Tier 2 implementer for at most one accepted proposal. Before any model call it queries GitHub for the deterministic feat/agents-<slug> branch and canonical PR. Existing open/merged/closed results are reconciled without spending model quota. Only when no prior result exists does it run the sub-agent, push the branch, and open a PR. Schema source | Destructive |
mctl_trigger_shepherd | Trigger Tier 3 PR shepherd to drive an existing implementer-PR through codex review fix loops to merge. Schema source | Destructive |
mctl_trigger_reconcile | Reconcile pass: read canonical GitHub PR state for every non-terminal proposal and project it onto platform-gitops/agents-state/<service>/proposals/<slug>/.status.yaml (merged PR -> merged, closed-unmerged -> rejected, conflicted open PR -> needs-triage). Schema source | Destructive |
mctl_trigger_approve | Approve one proposal: flip platform-gitops/agents-state/<service>/proposals/<slug>/.status.yaml from proposed to accepted via a gitops commit, recording the approver identity. Schema source | Destructive |
mctl_trigger_issue | Trigger the mctl-agents issue-investigator to turn a GitHub issue into a spec-driven proposal. Schema source | Write |
mctl_approve_dev_loop | Send the durable Temporal "approve" signal to an EXISTING DevLoopWorkflow execution. Schema source | Write |
mctl_abandon_dev_loop | Gracefully end an EXISTING DevLoopWorkflow execution by sending its durable Temporal "abandon" signal (mctl-agents#420). Schema source | Destructive |
mctl_get_dev_loop | Read-only liveness check for a DevLoopWorkflow: is there a live loop for this issue, and is it still running? Schema source | Read |
mctl_get_lifecycle_ownership | Read the lifecycle ownership store (ADR-010): who is responsible for an entity phase, whether that owner is still alive, and whether the store agrees with the old DevLoopWorkflow liveness check. Schema source | Read |
mctl_inspect_lifecycle_conflict | Read-only evidence for a lifecycle ownership recovery decision: the stored row, the derived view (status, held, dead/stuck/handoff-stalled with the liveness/progress bounds the status was measured against), the legacy DevLoopWorkflow answer, the divergence class between the two, recent transitions, and the EXACT precondition values (expected_owner_type/id, expected_epoch, expected_version, expected_last_seen_at) a follow-up recovery call must send verbatim. Schema source | Read |
mctl_request_lifecycle_reconcile | Mutates the lifecycle ownership store. Performs exactly one transition: appends a reconcile-requested event for one entity phase. It changes NO ownership column -- owner, epoch and state are untouched -- so it never takes a claim from anybody and confers no GitHub merge or approval authority. Schema source | Write |
mctl_fence_lifecycle_claim | DESTRUCTIVE: mutates the lifecycle ownership store. Performs exactly one transition: releases (fences) a claim whose owner the server re-derives as DEAD -- re-checked server-side under the store's own advisory lock, so a caller may not assert death, only ask for the question to be re-asked; refused with a 409 if the owner is still alive. Installs NO successor: the row moves to "released" with its fencing epoch incremented by the database (never by a caller-supplied value), and the fenced owner stays named on the row for forensics. Schema source | Destructive |
mctl_request_lifecycle_handoff | DESTRUCTIVE: mutates the lifecycle ownership store. Performs exactly one transition: starts a handoff off an owner the server re-derives as STUCK -- alive, but has effected no progress within its phase's bound -- toward the named to_owner. Refused with a 409 on a healthy owner (not licensed), a dead one (use mctl_fence_lifecycle_claim instead -- handing off a dead claim just produces a second stuck machine), or one already handing off (use mctl_retry_lifecycle_handoff instead of layering a second handoff on top). Schema source | Destructive |
mctl_retry_lifecycle_handoff | Mutates the lifecycle ownership store. Performs exactly one transition: re-arms the clocks (handoff_started_at AND last_seen_at) of a handoff the server re-derives as STALLED -- started, and never completed within the phase's liveness bound -- for the SAME target. Refused if the row is not handing off at all, or if the handoff is still within its bound (not yet stalled). Schema source | Write |
mctl_list_recent_agent_runs | List the most recent mctl-agents triggers (up to 10): scheduled cron runs and operator-initiated submissions, merged and sorted newest-first. Each item includes operation, mode, service (for single-service runs), status, who triggered it (user id or "cron"), timestamp, and a "source" field of "cron" or "operator" so the caller can distinguish autonomous schedule firings from manual triggers. Admin-only. Schema source | Read |
mctl_get_epic_status | Status of one roadmap epic (an EpicDefinition in mctlhq/.github), from the published RoadmapPublication: the epic's lifecycle, title and goal, its manifest path and digest, the RoadmapReadySet (every work item's state — complete, ready, blocked or unknown — with typed blockers and the issue it is bound to) and the RoadmapHealth (allRequired completion and drift diagnostics), both exactly as published. Schema source | Read |
mctl_get_ready_work_items | Roadmap work items that are ready to start now, from the published RoadmapPublication: for one epic, or for every epic whose lifecycle is "active" when no epic is given. Each item is the published ready-set entry (id, required, repository/issue, phase, dependsOn), grouped under its epic with the manifest it came from. Schema source | Read |
mctl_plan_epic_wave | Plan "start the next wave for this epic" without starting anything: the exact ready work items of one roadmap epic that a wave would start, from the published RoadmapPublication. Each selected item carries its issue and the exact DevLoop workflow id it would get; ready items that cannot be started (not bound to an exact issue) are listed as refused, never dropped. Schema source | Read |
mctl_start_epic_wave | Start a wave planned with mctl_plan_epic_wave: one DevLoopWorkflow per selected work item, with the exact workflow ids the plan named. Admin-only. Schema source | Write |
mctl_get_work_item | One canonical WorkItem: state, state_version, tenant, origin surface, latest_execution and latest_snapshot. state_version is the value mctl_request_work_item_execution expects. Schema source | Read |
mctl_list_work_item_executions | Every execution attached to one WorkItem, oldest first, with the engine and engine_ref the platform recorded and the surface that requested it. Schema source | Read |
mctl_list_work_item_snapshots | The immutable ContextSnapshots sealed for one WorkItem, or one of them in full when snapshot_id is given. A resumed execution seals a NEW snapshot that names the one it resumed from; a sealed snapshot never changes. Schema source | Read |
mctl_list_work_item_execution_requests | Execution requests made for one WorkItem, or one of them when request_id is given: kind, state (pending, claimed, fulfilled, rejected), requested_by, surface and, once fulfilled, the execution_id the platform created. Schema source | Read |
mctl_request_work_item_execution | Asks the platform to start or resume one WorkItem. It records an execution REQUEST and nothing else: the execution platform claims it, runs it and attaches the new execution and its ContextSnapshot to the SAME WorkItem. The request names no engine, run or execution id; those are the platform's. Schema source | Write |
mctl_get_commerce_budget | The commerce budget balance of one tenant: available_minor, reserved_minor, committed_minor, pending_liability_minor, currency and funds_mode. Schema source | Read |
mctl_list_commerce_invocations | Lists one tenant's commerce invocations, optionally filtered by capability, phase and period. Never returns arguments, results or payment proofs. Schema source | Read |
mctl_get_commerce_receipt | The receipt of one commerce invocation: terms, quote digest, price, the five facts (execution outcome, usage, charge, payment, settlement), phase, timestamps and the approval/policy decision reference. Never returns arguments, results, payment proofs or idempotency keys. Schema source | Read |
mctl_trigger_portal_server_auth_apply | Dispatch mctl-gitops' cloudflare-apply.yml on infrastructure/cloudflare/portal: apply the committed OAuth registration of the Cloudflare MCP portal's upstream servers (issuer/authorization/token/revocation endpoints, client registration, and the scope the portal requests). Schema source | Write |
mctl_create_agent | Register a new agent definition in the agent registry (e.g. issue-investigator, implementer, shepherd). Required once per agent before any version can be published for it. Idempotent to call again with the same name is not guaranteed — check mctl_list_agent_versions first if unsure whether it already exists. Admin-only. Schema source | Write |
mctl_publish_agent_version | Publish an immutable version of an agent to the registry. The agent must already have a definition (mctl_create_agent). A published version can then be promoted to an environment with mctl_promote_agent. Admin-only. Schema source | Write |
mctl_list_agent_versions | List every published version of an mctl-agents agent (e.g. issue-investigator, implementer, shepherd), newest first. Schema source | Read |
mctl_resolve_agent | Resolve which version of an agent is currently released to an environment. Schema source | Read |
mctl_promote_agent | Promote a published agent version to an environment (production or shadow). Schema source | Destructive |
mctl_rollback_agent | Roll an agent's release in an environment back to the version it had immediately before the current one. Schema source | Destructive |
mctl_list_agent_executions | List durable execution records from DevLoopWorkflow runs (dev-workflow control plane, plan phase 4): which agent version actually ran, on which Argo workflow, with what result. Unlike mctl_list_recent_agent_runs (which reflects live/recently-completed Argo state and expires with the workflow object's TTL), these records persist independent of Argo. Admin-only. Schema source | Read |
mctl_publish_agent_definition_version | Publish an immutable v1alpha2 AgentDefinition version: the full definition spec, its source manifest provenance (repo/path/gitSha/contentHash), and the ExecutionProfile compatibility range it declares. The agent must already have a definition (mctl_create_agent). (agent_name, version) is a once-only key — republishing the same pair is rejected with a conflict. Admin-only. Schema source | Write |
mctl_publish_agent_profile_version | Publish an immutable ExecutionProfile version: its full policy spec, provenance, and required policy-ceiling fields. Profile names are a global key space, not namespaced per agent. (profile_name, version) is a once-only key. Admin-only. Schema source | Write |
mctl_set_agent_version_lifecycle | Transition a published AgentDefinition or ExecutionProfile version to deprecated or disabled. Only published -> deprecated, published -> disabled and deprecated -> disabled are valid; any other transition is rejected. The immutable spec is left untouched — only the lifecycle state, actor and reason change. A disabled version can no longer be bound (or restored by rollback). Admin-only. Schema source | Destructive |
mctl_bind_agent_release | Append a new ReleaseBinding revision binding a compatible AgentDefinition version and ExecutionProfile version to (agent, environment). Append-only: this never overwrites, it always adds a new revision, and the active binding for a pair is always the highest revision. Rejected with 422 if the profile version does not satisfy the definition's declared compatibility range, if either version is deprecated/disabled, or if binding_source is compatibility-fixture (non-promotable — use registry). Admin-only. Schema source | Destructive |
mctl_rollback_agent_binding | Roll (agent, environment) back to an exact prior ReleaseBinding revision. Appends a new revision that copies the target revision's definition/profile pair and sets rollbackOf to the revision it restored — never a guess at "one step back". Rejected with 422 if the target revision's definition or profile version has since become disabled. Admin-only. Schema source | Destructive |
mctl_list_agents | List every registered agent in the registry: owner, v1 version count, v1alpha2 definition-version count, and the active v1alpha2 binding revision per environment. Admin-only. Schema source | Read |
mctl_get_agent | Get one agent's full catalog entry: owner, every v1 version and v1alpha2 definition version (with per-version lifecycle), and the active v1alpha2 binding per environment. Admin-only. Schema source | Read |
Deployment parameters
mctl_deploy_service
Deploys or reconfigures a service. The action parameter selects the mode:
| Action | Purpose |
|---|---|
onboard | First-time deploy — creates the GitOps manifests and submits the initial build + deploy workflow |
deploy | Update an already-onboarded service to a new image tag |
update-config | Change environment variables or secrets without a new image build |
Parameters (not all apply to every action; see Deploy your first app for the full onboard walkthrough):
| Name | Applies to | Description |
|---|---|---|
team_name | all | Tenant name |
component_name | all | Service name — used in the generated URL |
dockerfile_repo | onboard, deploy | GitHub repository in <owner>/<repo> format |
dockerfile_path | onboard | Path to the Dockerfile if not at the repo root. Defaults to "Dockerfile" |
git_tag | onboard, deploy | Git tag to build/deploy |
port | onboard | Container port the app listens on |
service_template | onboard | Use "default" unless a custom template applies |
health_check_path | onboard | Overrides both liveness and readiness probe paths. When omitted, the chart uses /healthz for liveness and /readyz for readiness. Only applied at onboard time; not currently supported on update-config |
secret_env_vars | update-config | String of newline-separated KEY=value entries to store in Vault (see below) |
env_vars | update-config | String of newline-separated KEY=value entries for plain, non-secret env vars |
Pass env_vars and secret_env_vars as strings, not JSON objects. Omit a parameter to leave it unchanged. An explicitly empty string clears the corresponding configuration; do not use it as a placeholder.
How update-config with secret_env_vars actually works:
This is not instant — it's a three-step chain, and each step has its own propagation delay:
- The value is written to Vault under the tenant's secret path.
- An
ExternalSecretis created/updated in the tenant namespace. The External Secrets Operator syncs it into a KubernetesSecret— this sync is not immediate; check theExternalSecret's status if the value hasn't landed yet. - The Kubernetes
Secretis wired into the pod viaenvFrom.update-configtriggers a rollout for you, but a running pod will not see the new value until it restarts.
If a secret isn't reaching your app, check in order: the ExternalSecret synced (the Secret exists in-namespace) → the Deployment's envFrom references that Secret → the pod actually restarted after the update.
Example:
mctl_deploy_service(
action="update-config",
team_name="my-team",
component_name="my-service",
secret_env_vars="API_KEY=example-secret"
)Tool annotations
readOnlyHint, destructiveHint and idempotentHint describe tool behavior. They are hints to clients, not authorization checks or a guarantee that a client will request confirmation. The API enforces membership, roles and operation policy. Platform pipeline tools are admin-only. Tenant and owner restrictions still apply even when a client exposes a tool in its interface.
Agent pipelines
Use each tool's current schema for service filters and execution bounds. Proposals and PRs follow the platform review/approval gates; approval belongs to the current proposal or commit and must not be assumed from an earlier run. Pipeline duration and model cost depend on the work and configured runner.