mctl-api MCP server
2026년 11월 15일 커밋REST와 MCP를 통해 서비스, 워크스페이스, 데이터베이스 및 플랫폼 운영을 관리할 수 있는 이중 프로토콜 게이트웨이를 제공합니다.
다른 이름 mctlhq/mctl-api
- 스타
- 0
- Tools
- 12
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 15일
- 라이선스
- Apache-2.0
mctl-api MCP란?
mctl-api은(는) MCP server입니다. REST와 MCP를 통해 서비스, 워크스페이스, 데이터베이스 및 플랫폼 운영을 관리할 수 있는 이중 프로토콜 게이트웨이를 제공합니다. 12개 도구를 제공합니다. 예: mctl_list_tenants, mctl_list_services, mctl_get_tenant.
프로젝트 README에서 생성된 요약
mctl-api MCP server 정보
mctl-api는 mctl.ai Internal Developer Platform을 위한 중앙 제어 평면 게이트웨이 역할을 합니다. 개발자가 REST 엔드포인트와 MCP 도구를 모두 사용하여 서비스, 워크스페이스, 데이터베이스 및 커스텀 도메인을 관리할 수 있도록 이중 프로토콜 인터페이스를 제공합니다. Backstage와 CLI 도구는 REST API를 활용하는 반면, Claude, Cursor, Copilot과 같은 AI 코딩 어시스턴트는 MCP 프로토콜을 통해 연결하여 플랫폼 운영을 수행합니다.
모든 쓰기 작업은 Argo Workflows를 통해 처리되며, GitOps 리포지토리를 사용하는 ArgoCD를 통해 조정됩니다. 이 시스템은 리소스 할당량 모니터링을 위해 Kubernetes와 통합되어 있으며, 서비스 로그 쿼리를 위해 Loki와 통합되어 있습니다. 인증은 ZITADEL을 통한 OAuth 2.1 및 PKCE를 통해 처리되며, 연합 OIDC JWT를 지원합니다. 서버는 리소스 보호를 위해 속도 제한을 구현하여, 인증된 요청은 분당 300회, 쓰기 요청은 분당 20회까지 허용합니다.
활용 사례
- 1플랫폼 서비스 배포AI 어시스턴트가 플랫폼 게이트웨이를 통해 서비스 배포 또는 롤백을 트리거할 수 있습니다.
- 2인프라 리소스 관리개발자는 API를 사용하여 새로운 데이터베이스를 프로비저닝하거나 애플리케이션을 위한 커스텀 도메인을 관리할 수 있습니다.
- 3GitOps 워크플로우 자동화API가 GitOps 리포지토리와 직접 상호작용하여 서비스 구성을 관리합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
mctl-api MCP 도구 12
README에서 감지됨mctl_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 | — |
구성
MCTL_API_TOKENMCTL_API_URL
| 이름 | 설명 | 유형 |
|---|---|---|
| MCTL_API_TOKEN | — | |
| MCTL_API_URL | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능mctlhq/mctl-api is public and reachablegithub.com/mctlhq/mctl-api ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-13github.com/mctlhq/mctl-api ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음12 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기mctl-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 질문
mctl-api MCP는 어떤 도구를 제공하나요?
12개 도구를 제공합니다. 예: mctl_list_tenants, mctl_list_services, mctl_get_tenant, mctl_get_service_status, mctl_get_service_config.
mctl-api는 어떤 프로토콜을 지원하나요?
REST 엔드포인트와 Model Context Protocol (MCP)을 모두 지원하여 이중 프로토콜 액세스가 가능합니다.
플랫폼 내 쓰기 작업은 어떻게 실행되나요?
모든 쓰기 작업은 Argo Workflows를 통해 수행되며, GitOps 리포지토리를 사용하는 ArgoCD에 의해 조정됩니다.
어떤 AI 클라이언트가 이 서버에 연결할 수 있나요?
Claude, Copilot, Cursor, Gemini 및 other AI 코딩 어시스턴트가 MCP 프로토콜을 통해 연결할 수 있습니다.
서버에서 인증을 지원하나요?
네, ZITADEL을 통한 OAuth 2.1 및 PKCE, 연합 OIDC JWT, 그리고 정적 서비스 토큰을 사용합니다.