Skip to main content

Operator

Operator interface for MCP clients. Connections are managed by a signed-in user; the operator namespace accepts only an operator connection credential. Cloud additionally requires a Pro/Team plan (402 PLAN_FEATURE_REQUIRED), refuses new writes while frozen (403 WORKSPACE_FROZEN), and applies monthly renewal quota admission (429 CERTOPS_RENEWAL_QUOTA_EXCEEDED).

📄️Withdraw my unapproved request before execution

Needs the scope for the stored request (mcp:renew:request or mcp:issue:request) and remains available when new requests are disabled or CertOps is paused. Authentication, scope and ownership still apply. May withdraw waiting approvals or claimable pending jobs without human approval. Withdrawal races atomically with approval and agent claim; if either wins first, return 409 without claiming execution was prevented. Response shape: packages/contracts/mcp/mcp-renew-tools.schema.json definition tt_cancel_request_output.

📄️Submit a previewed renewal under workspace job approval policy

Needs mcp:renew:request and both write switches. Creates an ordinary renewal job attributed to the person and connection. CertOps Job approval on creates pending_approval for independent review; off creates immediately claimable pending work without recording human approval. Existing jobs retain their gate; a policy change invalidates an unsubmitted preview. The body is exactly planId, planHash and requestId and cannot override policy. An identical retry returns the original outcome (200, replayed true), even after preview expiry or completion; reused requestId with different content is a 409. Revocation is serialized with submission. Submission is not proof of renewal. Response shape: packages/contracts/mcp/mcp-renew-tools.schema.json definition tt_request_renew_output.

📄️Redeem a setup code for an operator connection credential

The only operator route that takes no connection credential. It takes the single-use setup code as a bearer (ttopg_ prefix), which is accepted here and nowhere else. A cookie or session next to it is refused. The request body is ignored: the code fixes the user, workspace, scopes, role ceiling, name and lifetime, and the issuing person's access is checked again at this moment. On success the credential is returned once with Cache-Control no-store and is not stored or recoverable; if the response is lost, revoke the new connection and create a new setup code. Every failure before the code is proven valid looks the same, so a wrong or unknown code reveals nothing. Rate limited per client address.

📄️Create an operator enrollment (Connect an assistant)

Session only. Creates a single-use setup code that fixes the user, workspace, scopes, role ceiling, connection name and connection lifetime. It is valid for 10 minutes. The same checks as creating a connection apply now, so a request that could never be redeemed is refused immediately. The code is returned once, with Cache-Control no-store, and cannot be recovered afterwards. Redeeming it creates the connection; nothing about the resulting credential is kept.

📄️Show one job

Returns a job's status, approval state, attempt count, normalized error code and, for a waiting job, why it is waiting. The free-text error message, payload and claim id are never returned. Authenticated only with an operator connection credential holding the mcp:jobs:read scope; the workspace comes from the connection. Response shape: packages/contracts/mcp/mcp-read-tools.schema.json definition tt_get_job_output (tool tt_get_job). Unknown or repeated query parameters are refused with 400. Hidden with 404 while the operator interface or CertOps is disabled.

📄️List jobs

Lists job summaries by status, operation, subject or recency. Payloads, result metadata, lease and claim data, error text and requester ids are never returned. Free-text search is not offered, because the underlying job search also reads agent names and hostnames. Authenticated only with an operator connection credential holding the mcp:jobs:read scope; the workspace comes from the connection. Response shape: packages/contracts/mcp/mcp-read-tools.schema.json definition tt_list_jobs_output (tool tt_list_jobs). Unknown or repeated query parameters are refused with 400. Hidden with 404 while the operator interface or CertOps is disabled.

📄️Show agent health

Agent liveness, version, compatibility and declared capabilities. Requires a workspace manager or admin effective role, matching the session route, because fleet metadata is treated as sensitive. Agent names, target selectors, command profiles and signing key ids are never returned. Requires a workspace manager or admin effective role. Authenticated only with an operator connection credential holding the mcp:agents:read scope; the workspace comes from the connection. Response shape: packages/contracts/mcp/mcp-read-tools.schema.json definition tt_get_agent_health_output (tool tt_get_agent_health). Unknown or repeated query parameters are refused with 400. Hidden with 404 while the operator interface or CertOps is disabled.

📄️Explain a certificate's state

Deterministic and server-side. Composes reason codes the renewal-path, job and lifecycle services already produce and words them from a fixed table. It never returns a service's free-text summary or dependency list, which can name agents. Evidence that is missing is reported as an unknown area and never as a definitive answer. Authenticated only with an operator connection credential holding the mcp:certs:read scope; the workspace comes from the connection. Response shape: packages/contracts/mcp/mcp-read-tools.schema.json definition tt_explain_certificate_state_output (tool tt_explain_certificate_state). Unknown or repeated query parameters are refused with 400. Hidden with 404 while the operator interface or CertOps is disabled.

📄️Show where a certificate was observed

Returns observed locations with presence state (confirmed present, confirmed absent or unknown), evidence kind and freshness reason. Deployment paths and references are never returned. The source returns at most 20 locations per certificate; a longer list is reported as truncated with no cursor. Authenticated only with an operator connection credential holding the mcp:certs:read scope; the workspace comes from the connection. Response shape: packages/contracts/mcp/mcp-read-tools.schema.json definition tt_get_certificate_observations_output (tool tt_get_certificate_observations). Unknown or repeated query parameters are refused with 400. Hidden with 404 while the operator interface or CertOps is disabled.

📄️Show one certificate identity

Returns one certificate identity with its lifecycle, management periods, renewal path and observation summary. The identity id is the id returned by the list. A record in another workspace answers 404, exactly like a missing one. Authenticated only with an operator connection credential holding the mcp:certs:read scope; the workspace comes from the connection. Response shape: packages/contracts/mcp/mcp-read-tools.schema.json definition tt_get_certificate_output (tool tt_get_certificate). Unknown or repeated query parameters are refused with 400. Hidden with 404 while the operator interface or CertOps is disabled.

📄️List certificates

Lists certificate identities in the connection's workspace by status, expiry window or text. Search matches only names, issuer, subject alternative names and fingerprint. Key references, deployed paths and source references are never returned, and cannot be inferred by searching for them. Provisional rows (issuance in flight) have a null fingerprint. Authenticated only with an operator connection credential holding the mcp:certs:read scope; the workspace comes from the connection. Response shape: packages/contracts/mcp/mcp-read-tools.schema.json definition tt_list_certificates_output (tool tt_list_certificates). Unknown or repeated query parameters are refused with 400. Hidden with 404 while the operator interface or CertOps is disabled.

📄️Show the operator connection, workspace and effective role

Returns who an operator connection represents and what it may do right now. Authenticated only with an operator connection credential (bearer); the workspace comes from the connection and is never read from the path or the query. The effective role is the lower of the role ceiling fixed at creation and the user's current workspace role. Text that originates from the workspace is wrapped as untrusted data. Hidden with 404 while the operator interface is disabled. A request that also carries a session cookie is refused with 401.