mctl-api MCP server
Commit Nov 15, 2026Provides a dual-protocol gateway to manage services, workspaces, databases, and platform operations via REST and MCP.
Also known as mctlhq/mctl-api
- Stars
- 0
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is mctl-api MCP?
mctl-api provides a dual-protocol gateway to manage services, workspaces, databases, and platform operations via REST and MCP. It exposes 12 tools, such as mctl_list_tenants, mctl_list_services, mctl_get_tenant.
Summary generated from the project's README
About mctl-api MCP server
mctl-api serves as the central control plane gateway for the mctl.ai Internal Developer Platform. It provides a dual-protocol interface that allows developers to manage services, workspaces, databases, and custom domains through both REST endpoints and MCP tools. While Backstage and CLI tools utilize the REST API, AI coding assistants like Claude, Cursor, and Copilot connect via the MCP protocol to perform platform operations.
All write operations are processed through Argo Workflows and reconciled via ArgoCD using a GitOps repository. The system integrates with Kubernetes for resource quota monitoring and Loki for service log queries. Authentication is handled via OAuth 2.1 and PKCE through ZITADEL, supporting federated OIDC JWTs. The server implements rate limiting to protect resources, allowing 300 authenticated requests per minute and 20 write requests per minute.
What you can do with it
- 1Deploying platform servicesAn AI assistant can trigger service deployments or rollbacks through the platform gateway.
- 2Managing infrastructure resourcesDevelopers can use the API to provision new databases or manage custom domains for their applications.
- 3Automating GitOps workflowsThe API manages service configurations by interacting directly with a GitOps repository.
Written from the project's README. Every use case is checked against a quote from it.
mctl-api MCP tools 12
Detected from the READMEmctl_list_tenantsmctl_list_servicesmctl_get_tenantmctl_get_service_statusmctl_get_service_configmctl_get_resource_usagemctl_get_service_logsmctl_deploy_servicemctl_create_tenantmctl_provision_databasemctl_rollback_servicemctl_retire_service
| mctl_list_tenants | — | |
| mctl_list_services | — | |
| mctl_get_tenant | — | |
| mctl_get_service_status | — | |
| mctl_get_service_config | — | |
| mctl_get_resource_usage | — | |
| mctl_get_service_logs | — | |
| mctl_deploy_service | — | |
| mctl_create_tenant | — | |
| mctl_provision_database | — | |
| mctl_rollback_service | — | |
| mctl_retire_service | — |
Configuration
MCTL_API_TOKENMCTL_API_URL
| Name | Description | |
|---|---|---|
| MCTL_API_TOKEN | — | |
| MCTL_API_URL | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemctlhq/mctl-api is public and reachablegithub.com/mctlhq/mctl-api ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/mctlhq/mctl-api ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmctl-api
Control plane API for the mctl.ai Internal Developer Platform — dual-protocol (REST + MCP) access to manage services, workspaces, databases, previews, and platform operations.
What It Does
mctl-api is the central gateway for the mctl.ai platform. It exposes every platform operation — deploying services, creating team workspaces, provisioning databases, managing custom domains — as both REST endpoints and MCP tools. AI coding assistants (Claude, Copilot, Cursor, Gemini, and others) connect via the MCP protocol, while Backstage and CLI tools use the REST API. All write operations are executed through Argo Workflows and reconciled by ArgoCD through a GitOps repository.
Architecture
AI Clients (Copilot CLI / Claude / Cursor / VS Code / Windsurf / Gemini / Continue.dev)
│
▼
MCP Server (/mcp endpoint, Streamable HTTP)
│
▼
REST API (/api/v1/*) ◄── Backstage / CLI / HTTP clients
│
├──► Argo Workflows (submits deploy/provision/rollback jobs)
├──► GitOps Repo (reads service configs, commits changes)
├──► ArgoCD (sync status, health checks)
├──► Kubernetes (resource quota usage)
├──► Loki (service log queries)
└──► PostgreSQL (audit log)
Tech Stack
| Category | Details |
|---|---|
| Language | Go 1.25 |
| HTTP Router | chi v5.2 |
| MCP Server | mcp-go v0.31 (Streamable HTTP transport) |
| Auth | OAuth 2.1 + PKCE (sign-in through ZITADEL), federated OIDC JWTs, static service tokens |
| Database | PostgreSQL via pgx v5.9 (audit logs) |
| Kubernetes | client-go v0.32 (quota reader) |
| Rate Limiting | httprate v0.15 (300 req/min authenticated including POST /mcp, loopback MCP-internal REST excluded from that cap, 20 req/min write) |
| Container Registry | ghcr.io/mctlhq/mctl-api |
| Linting | golangci-lint (errcheck, govet, staticcheck, gosec, bodyclose) |
Project Structure
mctl-api/
├── cmd/api/main.go # Entry point, server bootstrap
├── internal/
│ ├── api/ # REST handlers & router
│ │ ├── handlers_read.go # Read operations (list, status, config)
│ │ ├── handlers_write.go # Write operations (deploy, create, retire)
│ │ ├── handlers_domains.go # Custom domain management
│ │ ├── handlers_repos.go # Repository access management
│ │ ├── oauth_handlers.go # OAuth 2.0 Authorization Code + PKCE
│ │ └── router.go # Route definitions & middleware
│ ├── auth/ # GitHub + OIDC + OAuth authentication
│ ├── mcp/ # MCP server implementation (tool registry)
│ ├── operations/ # Platform operation registry & executor
│ ├── argocd/ # ArgoCD API client
│ ├── gitops/ # GitOps repo reader (clone, parse values)
│ ├── audit/ # Audit logging (PostgreSQL-backed)
│ ├── k8s/ # Kubernetes quota reader
│ ├── loki/ # Loki log query client
│ └── openapi/ # Embedded OpenAPI spec
├── e2e/ # End-to-end tests (build tag: e2e)
├── helm/ # Kubernetes Helm chart
├── Dockerfile # Multi-stage Alpine build
├── Makefile # Dev commands (run, test, lint, build)
├── .golangci.yml # Linter configuration
├── .env.example # Environment variable template
├── mcp-config.example.json # MCP client config examples
└── .github/workflows/build.yml # CI/CD pipeline
Getting Started
Prerequisites
- Go 1.25+
- GitHub CLI (
gh) — for obtaining auth tokens - Access to the
mctlhqGitHub organization
Local Development
# Run API against local gitops clone
make run
# Run MCP stdio server pointing at local API
make run-mcp
# Both together
make run &
make run-mcp
Auth is bypassed locally (AUTH_REQUIRED defaults to false when unset). Set AUTH_REQUIRED=true to test authentication.
Docker
docker build -t mctl-api .
docker run -p 8080:8080 mctl-api
Configuration
Environment Variables
| Variable | Description | Default | Required |
|---|---|---|---|
PORT |
HTTP server port | 8080 |
No |
SHUTDOWN_DRAIN_DELAY |
Go duration the pod keeps serving after SIGTERM with /readyz at 503 (checks.shutdown=draining) before the listener closes. Keep it plus the 10s shutdown timeout below the pod's terminationGracePeriodSeconds. Invalid or non-positive values use the default. |
5s |
No |
AUTH_REQUIRED |
Enable authentication | true |
No |
ADMIN_USERS |
Admin GitHub usernames (comma-separated) | — | No |
GITOPS_REPO_URL |
GitOps repository URL | https://github.com/mctlhq/mctl-gitops.git |
No |
GITOPS_BRANCH |
GitOps branch | main |
No |
GITOPS_LOCAL_PATH |
Local cache path for gitops clone | /tmp/mctl-gitops |
No |
GITHUB_APP_TOKEN_FILE |
Path to a mounted GitHub App installation token. Takes precedence over GITOPS_REPO_TOKEN and GITOPS_ACTIONS_TOKEN, and is re-read per use so a rotation is picked up without a restart. |
— | No |
GITOPS_REPO_TOKEN |
GitHub token for HTTPS clone. Fallback when GITHUB_APP_TOKEN_FILE is unset; read once at startup, so only for credentials that do not rotate. |
— | No |
GITOPS_ACTIONS_TOKEN |
GitHub token that starts workflow_dispatch runs in mctl-gitops. Fallback when GITHUB_APP_TOKEN_FILE is unset; read once at startup. |
— | No |
GITHUB_TOKEN |
Last-resort fallback for the clone, after GITHUB_APP_TOKEN_FILE and GITOPS_REPO_TOKEN. |
— | No |
GITOPS_SSH_KEY_PATH |
SSH key path for git clone. Takes precedence over every token above. | — | No |
ARGOCD_URL |
ArgoCD API endpoint | https://ops.mctl.ai |
No |
ARGOCD_TOKEN |
ArgoCD auth token (from Vault) | — | Yes |
ARGO_WORKFLOWS_NAMESPACE |
Kubernetes namespace for workflows | argo-workflows |
No |
GITHUB_ORG |
Required GitHub organization | mctlhq |
No |
DEX_ISSUER_URL |
Legacy, unset in production since Dex was removed (mctl-gitops#1741). Dex OIDC issuer URL; still read by the legacy dex federation shim. Unset turns Dex off: no Dex JWTs, no dex federation shim, no Dex check in /readyz. |
— | No |
DEX_CLIENT_ID |
Legacy, unset in production (see DEX_ISSUER_URL). JWT audience for Dex. Empty skips the audience check (compatibility) and counts federation_audience_check_skipped_total{provider="dex"} on every verification. |
— | No |
MCTL_OIDC_PROVIDERS |
JSON array of federation identity providers (mctl-api#374, see docs/federation.md): [{"name":"dex","issuer":"https://…","audiences":["mctl-api"],"audience_enforcement":"audit"}]. An entry named dex replaces the legacy shim built from DEX_ISSUER_URL/DEX_CLIENT_ID above, whatever its issuer; an entry under any other name on the DEX_ISSUER_URL issuer collides with the shim and refuses startup. audiences is required, audience_enforcement is audit or enforce (default enforce). A malformed value, a missing audiences, an invalid audience_enforcement or kind, a reserved or surface-colliding name, or a duplicate name/issuer refuses startup — unless MCTL_FEDERATION_DISABLED is on. |
— | No |
MCTL_FEDERATION_DISABLED |
Kill switch (mctl-api#374): any value except false/f/0/no/off restores the pre-registry authentication chain unchanged, including its plain (non-constant-time) service-token compare. While it is on, MCTL_OIDC_PROVIDERS is neither validated nor built, so it also recovers a value that would otherwise refuse startup. Same shape as PRINCIPALS_DISABLED. |
unset | No |
MCTL_GITHUB_ACTIONS_OIDC |
JSON object enabling GitHub Actions OIDC for CI deploys (mctl-api#530, see docs/federation.md): {"repository_owners":["mctlhq"],"audience":"https://api.mctl.ai","branches":["refs/heads/main"]}. The principal ci:<owner>/<repo> may only call POST /api/v1/operations/deploy-service/execute with action=deploy for a component whose gitops github.com/source-repo is that repository. repository_owners is required; a malformed value refuses startup. Unset: the provider is off and such tokens get 401. |
unset | No |
SELF_URL |
Public base URL | https://api.mctl.ai |
No |
ALLOWED_ORIGINS |
CORS allowed origins | — | No |
OAUTH_GITHUB_CLIENT_ID |
GitHub OAuth app client ID | — | No |
OAUTH_GITHUB_CLIENT_SECRET |
GitHub OAuth app client secret | — | No |
OAUTH_JWT_SECRET |
JWT signing secret for OAuth tokens | — | No |
OAUTH_UPSTREAM |
Where /oauth/authorize signs people in (mctl-api#467, see docs/principals.md): github, zitadel (as the linked principal's GitHub login; under TENANT_AUTHZ_MODE=principal an identity with no GitHub login signs in as its own principal), or both (a chooser, ZITADEL first). With customers_org_id and ZITADEL_HOOK_GITHUB_IDP_ID set, zitadel and both also offer customers "Sign in with GitHub" (mctl-web#158). zitadel/both refuse startup without OAUTH_JWT_SECRET, both OAUTH_ZITADEL_CLIENT_* and the provider entry, and both also without both OAUTH_GITHUB_CLIENT_*. An unknown value refuses startup |
github |
No |
OAUTH_ZITADEL_CLIENT_ID / OAUTH_ZITADEL_CLIENT_SECRET |
Confidential ZITADEL client of the ZITADEL upstream (redirect <SELF_URL>/oauth/zitadel/callback); not the link client. Helm: oauthZitadelSecret |
— | No |
OAUTH_ZITADEL_PROVIDER |
MCTL_OIDC_PROVIDERS entry whose issuer the ZITADEL upstream verifies against; must be the one linking writes (ZITADEL_LINK_PROVIDER) |
zitadel |
No |
OAUTH_ZITADEL_REDIRECT_BASE_URL |
Development only, never set in a deployment: origin that replaces SELF_URL in the ZITADEL redirect_uri, e.g. http://localhost:8080 for a local run behind a quick tunnel (https, or http on loopback) |
— | No |
OAUTH_ALLOWED_REDIRECT_URIS |
Comma-separated redirect URIs accepted at /oauth/authorize and by Dynamic Client Registration (POST /oauth/register). An entry is an exact string compare unless it ends in /*, which makes it a prefix match; prefer exact entries (the Cloudflare MCP portal's https://mcp.mctl.ai/servers-callback and its dashboard …/mcp-server/oauth-callback/api callback are listed exactly, never as a dash.cloudflare.com/* prefix). Loopback http:// callbacks are always accepted (RFC 8252). A registration naming any other URI gets 400 invalid_redirect_uri |
glama, smithery, chatgpt.com/connector/oauth/* |
No |
OAUTH_DB_URL |
PostgreSQL for OAuth refresh tokens, dynamic client registrations, and the pending authorizations and authorization codes of sign-ins in flight (table oauth_flow_entries, shared by every replica) (falls back to AUDIT_DB_URL). With a database, a client registered through POST /oauth/register survives restarts, and registration is idempotent: the same client_name and redirect-URI set get the same client_id back. Registrations that have never completed a token exchange are capped at 1000 (least recently seen evicted); a client that has completed one is never evicted by the cap. Any row is dropped after 90 days unseen, where a registration, token exchange or refresh counts as seen. Without one, registrations are in-memory and lost on restart. Every registration is granted scope mctl, the only scope |
AUDIT_DB_URL |
No |
OAUTH_PREREGISTERED_CLIENTS |
JSON array of static public OAuth clients for counterparts that cannot register dynamically (the Cloudflare MCP portal): [{"client_id":"…","client_name":"…","redirect_uris":["https://…"]}]. Exact redirect match, no secret field, never evicted; a malformed value or an unknown key refuses startup |
— | No |
OAUTH_CIMD_ACCEPT |
true makes the server accept OAuth Client ID Metadata Documents: an https:// client_id URL is resolved from the JSON document at that URL (its redirect_uris alone decide the callback and must be https or loopback IP-literal http; RFC 8252 loopback IP-literal entries match on any port), and the human sees a consent page on every authorization. It does not announce CIMD in discovery; that is OAUTH_CIMD_ADVERTISE. A document is cached for its Cache-Control: max-age (default 1 h, at least 30 s, at most 24 h; no-store, no-cache or max-age=0 give the 30 s floor; an invalid max-age is ignored), so a change to it takes effect within that lifetime. DCR and pre-registered clients are unchanged. Turning it on is a breaking change for any existing client whose client_id is an https:// URL and is not pre-registered: such a client_id is then resolved as a metadata document ahead of OAUTH_ALLOWED_REDIRECT_URIS and the loopback rule, including when its host is not on OAUTH_CIMD_ALLOWED_HOSTS, in which case the authorization is refused outright with 400 and never falls back. Before turning it on, confirm no live client uses a URL-shaped client_id, or add its host to the allowlist. See docs/federation.md. Strict true/false: any other value refuses startup. Replaces the retired OAUTH_CIMD_ENABLED, which now refuses startup whenever it is set |
false |
No |
OAUTH_CIMD_ADVERTISE |
true makes /.well-known/oauth-authorization-server advertise client_id_metadata_document_supported. Clients that prefer CIMD (ChatGPT, for one) then switch to it, and a CIMD client whose host is off OAUTH_CIMD_ALLOWED_HOSTS or whose document is refused gets 400 with no DCR fallback, so turn it on only when the allowlist covers every CIMD client in use (mctl-api#693). Requires OAUTH_CIMD_ACCEPT=true, otherwise startup is refused. Strict true/false |
false |
No |
OAUTH_CIMD_ALLOWED_HOSTS |
Comma-separated hosts a CIMD client_id may be fetched from (exact host, or .example.com for subdomains). Mandatory when OAUTH_CIMD_ACCEPT=true: an empty or malformed list refuses startup, and so does an empty entry, including the one a trailing comma makes (app.example.com,). In production, list the exact host of a known client rather than a .suffix |
— | When CIMD is on |
OAUTH_GROUPS_MAX_STALENESS |
Strict mode for tenant-group resolution (mctl-api#411, see "Authorization group freshness" below): a Go duration beyond which a gitops checkout that has not synced recently is treated as a failed resolution instead of merely a logged warning. Unset (or malformed) disables strict mode. | unset | No |
OAUTH_GROUPS_CACHE_TTL |
How long a successful tenant-group resolution is memoized per login, bounding the added cost of re-resolving on every JWT validation. Unset or malformed falls back to the default. | 30s |
No |
AUDIT_DB_URL |
PostgreSQL connection string (falls back to in-memory). sslmode=disable is upgraded to require, or verify-full when a CNPG CA is mounted. |
— | No |
DB_POOL_MAX_CONNS |
Size of the connection pool each distinct *_DB_URL gets. Stores whose URLs are identical (every one that falls back to AUDIT_DB_URL) share one pool, so this caps the connections per database per replica; pool_max_conns in a URL overrides it for that URL. A value that is not a positive integer refuses boot. Keep pods (replicas plus the surge pod of a rolling update) x (distinct URLs x this value + 3 unpooled connections) at or under the database role's connection limit. Startup logs the resulting pools (pgshared: pools), and /metrics exports their use as mctl_api_db_pool_* by host and database; a full pool shows as mctl_api_db_pool_empty_acquires_total rising while acquired_conns sits at max_conns. |
8 |
No |
HUMAN_INPUT_DB_URL |
PostgreSQL for the human-input delivery ledger (POST /api/v1/human-input/{request_id}/response). Falls back to AUDIT_DB_URL; with neither, that endpoint answers 503 (there is no in-memory fallback). The raw answer is kept only until its delivery resolves, or until the request expires. |
— | No |
WORK_ITEMS_DB_URL |
PostgreSQL for the workitem/v1 store (/api/v1/work-items*). Falls back to AUDIT_DB_URL; with neither, every work-items route answers 503. |
— | No |
COMMERCE_DB_URL |
PostgreSQL for the commerce ledger of ADR 020 (mctl-api#547 and #548, see docs/commerce-ledger.md): terms, quotes, invocation receipts and history, tenant budgets, holds and the simulated payment operations. Falls back to AUDIT_DB_URL; with neither, /api/v1/commerce* answers 503. Deploying it enables no payment behaviour: no terms exist until an admin publishes them, no budget exists until an admin grants one, a budget is a limit and never a balance, and funds_mode: live is refused everywhere. |
— | No |
COMMERCE_DISABLED |
Kill switch for the commerce ledger: routes answer 503 without touching AUDIT_DB_URL for other stores. Same values as the other kill switches. |
unset | No |
COMMERCE_ACCEPT_DISABLED |
Accept-only kill switch (mctl-api#570): new quotes and accepts answer 422 unsupported-execution, while reads, budgets, reserve, dispatch, finalize, release and the reconciler stay live so outstanding liability can drain. COMMERCE_DISABLED takes precedence. Same values as the other kill switches. See docs/commerce-ledger.md. |
unset | No |
COMMERCE_DISPATCH_KEY_ID |
Identifier of the Ed25519 key that signs dispatch authorizations for paid capabilities (ADR 020 sec. 9, mctl-agents#619). Set together with COMMERCE_DISPATCH_SIGNING_KEY; one without the other, or an unusable seed, refuses startup unless COMMERCE_DISABLED is on. |
unset | No |
COMMERCE_DISPATCH_SIGNING_KEY |
Base64 Ed25519 seed (32 bytes) for dispatch authorizations. Without both values, …/invocations/{id}/dispatch and /api/v1/commerce/dispatch-keys answer 503 dispatch-unavailable, and no paid call can be dispatched. Enables no payment behaviour by itself. |
unset | No |
WORK_ITEMS_DISABLED |
Kill switch: any value except false/f/0/no/off leaves the work-items store off (routes answer 503) without touching AUDIT_DB_URL for other stores. |
unset | No |
MCTL_AGENTS_APPROVE_LEGACY_APPROVER |
Whether the mctl-agent service principal may relay a free-text approver on mctl-agents-approve (mctl-api#571). true/empty keeps the relay and audits every use as approver.legacy_relay; false refuses it (400 legacy_approver_disabled, audited), and a DevLoop approve with no pending mctl-agents-approve action approval for the workflow's we_ answers 409 approval_grant_missing instead of signalling the legacy {approver} payload. Every use is also counted in `mctl_agents_approve_legacy_relay_total{outcome="relayed" |
"refused"}, since an audit write is best-effort. Turned off only after mctl-agents approves through action-approval grants (flow and error codes: [docs/principals.md](docs/principals.md#devloop-approval-by-grant-571)). A relay carries no content digest, so since mctl-api#722 it is refused with 400 approval_content_unboundeven when the flag is on, and counted asrefused`. Any other value refuses startup |
true |
MCTL_SUBMIT_CREATES_EXECUTION |
on or off. Kill switch for the submitter-creates-the-execution behaviour (mctlhq/mctl-agents#717 S3): with on, a mctl-agents-investigate submit without an execution_id first opens or joins the issue's work item, attaches a Pending argo execution named after the workflow, and passes work_item_id + execution_id; it never falls back to a submit without one, and Executor.Submit refuses the operation without an execution_id. With off (default) behaviour is exactly as before: no execution is created and nothing is refused. Stays off until the mctl-agents DevLoop human-input continuation carries its own execution (it deliberately submits without ids and would get 409 execution_active); flipping it on is a separate gitops step. Parsed once at startup; any other value refuses startup |
off |
No |
ISSUE_WORK_ITEM_TENANT |
Only read when MCTL_SUBMIT_CREATES_EXECUTION=on. Tenant that owns the work item of an mctl-agents-investigate run submitted without an execution_id (REST, mctl_trigger_issue, the issue poller): mctl-api opens or joins the issue's item there and attaches the run's execution before submitting (mctlhq/mctl-agents#717 S3). Must be the tenant mctl-agents opens DevLoop items in, or one issue gets two items |
mctl |
No |
MCTL_AGENT_RECEIPT_GATE |
Server-side receipt gate for governed MCP tool calls from the mctl-agent service principal (mctl-api#723). Governed are the tools mctl-agents' checkpoint marks REQUIRE_APPROVAL (policy mctl-api/agent-receipt-gate/v2: every mctl_* tool except the mctl_get_/list_/read_/search_/describe_ reads, whoami, incident_summary, resolve_agent, resolve_incident and acknowledge_incident). A receipt is the reserved tool arguments action_approval_ref (an aar_ request the caller itself requested and consumed (for an agent run token, for the execution the token is bound to), with action_kind mcp.tool.call:mcp__mctl__<tool> and target mctl) and action_approval_artifact_hash; both are removed from every call before a handler sees them. off: no check. observe: every governed call runs and is audited as agent-receipt-gate (status succeeded or observed with a code); a presented receipt is checked read-only. enforce: a governed call without a valid receipt is refused with a tool error naming the code (agent_receipt_missing, _malformed, _not_found, _operation_mismatch, _target_mismatch, _not_consumed, _already_executed, _artifact_mismatch, _unverifiable, _in_flight, _stale), and a valid one is reserved before the handler runs (consumed → in_flight, so two concurrent calls cannot both pass), then marked executed when the handler succeeds or released back to consumed when it fails (mctl-api#772). A receipt consumed longer ago than MCTL_AGENT_RECEIPT_MAX_AGE, or whose decision is past its fresh_until, is _stale (mctl-api#773). Each decision also increments mcp_agent_receipt_gate_total{mode,code} (code valid for an authorizing receipt), which counts even when the best-effort audit write fails. A _malformed row stores no part of what was sent except a bounded malformed parameter: whether the ref has the aar_ prefix, both lengths, and at most eight letters or digits after the prefix. Gated callers are service:mctl-agent and every agent run token, both acting directly (agent run tokens since mctlhq/mctl-agents#717 S4; a token bound to no execution has no valid receipt); humans, surfaces and relayed requests are not gated. What v1 guarantees: a human approved an intent for this tool, requested by this principal, recently, and the approval authorizes one successful call. What it does not: the server does not recompute the arguments digest, so it does not bind the call to the exact approved arguments (the artifact hash is the agent's); "failed" is the handler's own verdict, so a handler that reports failure after a partial side effect gets the receipt back (a call whose request was cancelled or timed out has an unknown outcome and spends it), while a settle that cannot be written leaves it reserved and unusable; and only the hosted /mcp endpoint is gated, not the stdio cmd/mcp server, which reaches the platform over REST. enforce without the work-items store refuses startup. An unknown value refuses startup |
off |
No |
MCTL_AGENT_RECEIPT_MAX_AGE |
How long after its consume a receipt still authorizes a governed call through MCTL_AGENT_RECEIPT_GATE (mctl-api#773). A Go duration, positive and at most 1h. mctl-agents consumes a receipt immediately before the call, so an older one is a crashed run or a replay and is refused as `agent_receipt_sta |
mctl-api MCP questions
What tools does mctl-api MCP provide?
It exposes 12 tools, including mctl_list_tenants, mctl_list_services, mctl_get_tenant, mctl_get_service_status, mctl_get_service_config.
What protocols does mctl-api support?
It supports both REST endpoints and the Model Context Protocol (MCP) for dual-protocol access.
How are write operations executed in the platform?
All write operations are performed through Argo Workflows and reconciled by ArgoCD using a GitOps repository.
Which AI clients can connect to this server?
AI coding assistants such as Claude, Copilot, Cursor, Gemini, and others can connect via the MCP protocol.
Does the server support authentication?
Yes, it uses OAuth 2.1 with PKCE via ZITADEL, federated OIDC JWTs, and static service tokens.