Serveur MCP mctl-api
Commit 15 nov. 2026Fournit une passerelle à double protocole pour gérer les services, les espaces de travail, les bases de données et les opérations de plateforme via REST et MCP.
Aussi connu sous mctlhq/mctl-api
- Étoiles
- 0
- Outils
- 12
- Téléchargements, 30 jours
- —
- Dernière version
- —
- Dernier commit
- 15 nov. 2026
- Licence
- Apache-2.0
Qu'est-ce que mctl-api MCP ?
Fournit une passerelle à double protocole pour gérer les services, les espaces de travail, les bases de données et les opérations de plateforme via REST et MCP. Il expose 12 outils, comme mctl_list_tenants, mctl_list_services, mctl_get_tenant.
Résumé généré à partir du README du projet
À propos du MCP server mctl-api
mctl-api sert de passerelle de plan de contrôle central pour l'Internal Developer Platform de mctl.ai. Il fournit une interface à double protocole qui permet aux développeurs de gérer les services, les espaces de travail, les bases de données et les domaines personnalisés via des points de terminaison REST et des outils MCP. Alors que Backstage et les outils CLI utilisent l'API REST, les assistants de codage IA comme Claude, Cursor et Copilot se connectent via le protocole MCP pour effectuer des opérations sur la plateforme.
Toutes les opérations d'écriture sont traitées via Argo Workflows et réconciliées via ArgoCD à l'aide d'un dépôt GitOps. Le système s'intègre à Kubernetes pour la surveillance des quotas de ressources et à Loki pour les requêtes de logs de service. L'authentification est gérée via OAuth 2.1 et PKCE via ZITADEL, prenant en charge les JWT OIDC fédérés. Le serveur implémente une limitation de débit pour protéger les ressources, autorisant 300 requêtes authentifiées par minute et 20 requêtes d'écriture par minute.
Ce que vous pouvez faire avec
- 1Déploiement de services de plateformeUn assistant IA peut déclencher des déploiements ou des rollbacks de services via la passerelle de la plateforme.
- 2Gestion des ressources d'infrastructureLes développeurs peuvent utiliser l'API pour provisionner de nouvelles bases de données ou gérer des domaines personnalisés pour leurs applications.
- 3Automatisation des workflows GitOpsL'API gère les configurations de service en interagissant directement avec un dépôt GitOps.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Outils MCP mctl-api 12
Détectés depuis le 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
| Nom | Description | Type |
|---|---|---|
| MCTL_API_TOKEN | — | |
| MCTL_API_URL | — |
Vérifications automatisées
Exécuté le 14 nov. 2026Rapport complet →Pas encore vérifié. Un serveur nécessite un score de 80, aucune faille sérieuse et suffisamment de données pour que nous puissions effectuer les vérifications. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessiblemctlhq/mctl-api is public and reachablegithub.com/mctlhq/mctl-api ↗Réussi
- Le nom du package correspond au dépôt sourceNon vérifié
- Provenance du build (attestation Sigstore)Non vérifié
- Licence open source (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-13github.com/mctlhq/mctl-api ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNon vérifié
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
- Aucune instruction cachée destinée au modèle12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNo tool named like delete, drop or execRéussi
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur 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 |
Questions sur mctl-api MCP
Quels outils mctl-api MCP fournit-il ?
Il expose 12 outils, dont mctl_list_tenants, mctl_list_services, mctl_get_tenant, mctl_get_service_status, mctl_get_service_config.
Quels protocoles mctl-api prend-il en charge ?
Il prend en charge à la fois les points de terminaison REST et le Model Context Protocol (MCP) pour un accès à double protocole.
Comment les opérations d'écriture sont-elles exécutées sur la plateforme ?
Toutes les opérations d'écriture sont effectuées via Argo Workflows et réconciliées par ArgoCD à l'aide d'un dépôt GitOps.
Quels clients IA peuvent se connecter à ce serveur ?
Les assistants de codage IA tels que Claude, Copilot, Cursor, Gemini et d'autres peuvent se connecter via le protocole MCP.
Le serveur prend-il en charge l'authentification ?
Oui, il utilise OAuth 2.1 avec PKCE via ZITADEL, des JWT OIDC fédérés et des jetons de service statiques.