Tool reference
seylo-mcp offers 35 tools. A token can see and call only the tools whose capability was ticked when it was issued. See capabilities. A tool the token can’t call isn’t listed, and calling it anyway is refused as if it didn’t exist.
Five rules apply to every tool:
- No tool takes a namespace or cluster. The token’s one namespace is the
only one. If an agent sends a
namespaceorclusterargument anyway, the call is refused and the refusal names the argument. - No tool returns a Secret value, whether in a result or an error.
- Seylo records every call, including refusals.
- Unknown arguments are refused, by name, with the list of arguments the tool does take. Seylo never ignores one silently.
- Every call is rate-limited per token, in two separate buckets: 60 calls
a minute for reads (every tool that changes nothing) and 10 calls a
minute for writes (
deploy,rollback,put_config,request_secret,dashboard_proposeandscrape_target_propose). The daily deploy cap applies on top. See limits.
The Effect column says what a tool does to your cluster:
- Read: changes nothing.
- Change: applies to the cluster.
- Propose: creates something a person decides on.
- Record: writes only an audit entry.
Deploy and inspect
Section titled “Deploy and inspect”| Tool | Capability | Effect | What it does |
|---|---|---|---|
list_targets |
list_targets |
Read | The token’s single cluster and namespace, its capabilities, its daily cap, its label, and the per-minute call limits for reads and writes. Call it first |
describe_target |
describe_target |
Read | Workloads in the namespace: image, replicas, ready count, rollout status. Also reports the cluster’s Kubernetes version |
diagnose |
describe_target |
Read | Why a workload isn’t running. Correlates rollout status, pod conditions, container exit codes and Events into a cause, the evidence and, where it can, the spec field to change. Answers unknown rather than guessing. Rule-based, with no model involved. Argument: component |
logs |
logs |
Read | Recent logs from one pod. Without pod, it lists the namespace’s pods with phase, restart count and container names, up to 50. tailLines defaults to 200, at most 2000. previous: true reads the container instance before a restart. Seylo never stores pod logs |
operation_status |
operation_status |
Read | One operation by id: the same record a person sees in Seylo. An operation in another namespace is reported as not existing |
validate |
validate |
Read | Generates manifests from a deploy spec, runs them through the policy catalogue and a server-side dry run, and returns the YAML, the findings and anything it couldn’t check. Changes nothing |
deploy |
deploy |
Change | Generates, validates and applies the manifests for an image that is already built and pushed. There is no approval step: the namespace was opened to coding-agent deploys, so a deploy that passes the checks is applied at once. Each applied deploy counts once against the daily cap; a refusal doesn’t count. See what deploy refuses |
rollback |
rollback |
Change | Returns a workload to its previous recorded revision, or to toCommitSha from its history. Restores the image and the configuration of that revision, as a new forward change. Env is replaced with that revision’s set, so a variable added since is removed. The answer names every variable removed, in envRemoved and in its summary (This rollback removes: …). Secret references are left as they are. Refused, naming the owner, if Argo CD, Flux, Helm or an operator owns the Deployment. Each applied rollback counts against the daily cap; a refused one does not |
propose_deploy |
propose_deploy |
Proposal | Files Kubernetes manifests (workloads, Services, Ingresses, ConfigMaps, HPAs, PodDisruptionBudgets, NetworkPolicies, ServiceAccounts, Roles and RoleBindings, PVCs, and instances of custom resources the cluster serves) for the token’s namespace as one deploy for a person to approve. Roles, RoleBindings and privileged or hostPath workloads need an admin. Nothing cluster-scoped. A Secret only with keys and empty values, and only one that already exists; a value is refused. Images need a fixed tag or digest. Objects managed by Argo CD, Flux or Helm are refused, naming the owner. Counts against the daily cap. See deploy from the coding agent |
The deploy spec
Section titled “The deploy spec”validate and deploy take a small spec, not YAML:
| Field | Required | Notes |
|---|---|---|
name |
Yes | Workload name. Also the Service name |
image |
Yes | Full reference with an explicit tag or digest. :latest, or no tag at all, is refused |
port |
Yes | The port the container listens on |
replicas |
No | Default 1 |
env |
No | Plain values only. A value that looks like a password, key or token is refused, and never repeated back: call request_secret, then deploy with propose_deploy and a secretKeyRef |
envFromConfigMaps |
No | ConfigMap names to import as environment |
resources |
No | cpuRequest, cpuLimit, memRequest, memLimit. Defaults 50m, 500m, 64Mi, 256Mi |
healthPath |
No | Path the probes hit. Default / |
expose |
No | host, path (default /) and tlsSecret, an existing TLS Secret name. Omit expose for a cluster-internal service |
Any other field is refused. Pod security settings, service accounts, host networking and volumes are set by Seylo and can’t be overridden. Manifests are generated to fit this cluster, for example by using the IngressClass that exists there. The spec can’t describe every workload: StatefulSets, DaemonSets and init containers aren’t in it. Use Seylo directly for those.
What deploy refuses
Section titled “What deploy refuses”deploy repeats the full check itself rather than trusting an earlier
validate. Nothing is applied when:
- a policy finding is blocking, or the cluster’s dry run rejects a resource;
- the namespace has no ResourceQuota, or its quotas can’t be listed. See give the namespace a budget;
- Argo CD, Flux, Helm or an operator owns any object it would write. The
refusal names the owner, for example
Nothing was applied: Deployment shop-dev/checkout is managed by Argo CD.A token can’t acknowledge another owner, so the change belongs in that owner’s source; - the token has used its daily cap, or the namespace is no longer open.
Policy findings about the namespace itself, such as a missing quota, are
reported separately as preExistingNamespaceConditions. They are conditions of
the namespace, not something the agent wrote.
Configuration and Secrets
Section titled “Configuration and Secrets”| Tool | Capability | Effect | What it does |
|---|---|---|---|
list_config |
list_config |
Read | ConfigMaps with their keys and values, and Secrets with their names and key names only. ConfigMap values that look like credentials are withheld and marked |
put_config |
put_config |
Change | Adds or updates keys in a ConfigMap. Keys you don’t mention are left alone, and nothing is deleted. A value that looks like a credential is refused. A ConfigMap that Argo CD, Flux, Helm or an operator manages is refused, naming the owner. A running pod doesn’t pick up the change until it re-reads the file or restarts |
request_secret |
request_secret |
Record | Records that the application needs a Secret: name, keys and reason (at least 10 characters). There is no value parameter. The reply says where a person must create it, and whether it already exists |
request_secret tells the agent whether the Secret is synced from a vault
by the secrets-store CSI driver. If it is, a person adds the key in the
vault, because the driver would overwrite a hand-made Secret. If it isn’t, a
person creates an ordinary Kubernetes Secret. Seylo writes the request to the
audit log, and the agent tells its user what to create. The agent can write its
manifest referencing the Secret straight away. The pod stays pending until the
Secret exists.
Observability
Section titled “Observability”These 25 tools need the observe capability. All of them only read.
Every query is limited to the token’s namespace by the store itself, the same way the Metrics page limits a person to the namespaces they can see. Before answering, Seylo must have proved that the store enforces that filter. If it hasn’t, the signal is refused for every token on that cluster. Series with no namespace label, such as node CPU or the kubelet, aren’t visible to a token.
| Tool | What it does |
|---|---|
observability_status |
Which stores are installed: metrics, logs and traces. Also whether they answer, their retention, and whether each has been proved to filter by namespace, plus this token’s limits. Call it first, and again after a refusal |
metrics_query |
A PromQL (MetricsQL) expression at one instant |
metrics_query_range |
A PromQL expression over a window. The default step gives about 240 points. A step that gives more than 11,000 points per series is refused, and the refusal states the smallest step that fits |
metrics_names |
Metric names with series in the namespace over the last hour. Optional match selector and contains substring |
metrics_labels |
Label names on the namespace’s series, optionally for one selector |
metrics_label_values |
One label’s values over the last 6 hours, for example pod |
metrics_series |
Label sets of series matching 1 to 10 selectors. limit defaults to 100, at most 1000 |
logs_query |
A LogsQL search, newest first, with pod and container. Lines are redacted before they reach the agent, and the number of redactions is reported. limit defaults to 100, at most 1000 |
logs_hits |
How many matching lines arrived per time bucket. The cheap way to see when errors started |
logs_field_names |
The fields log lines carry, such as kubernetes.pod_name or level |
logs_field_values |
One field’s values, with a count for each. Redacted like log lines |
logs_stats |
A LogsQL query ending in a | stats pipe. The rows are redacted. A query without the pipe is refused |
traces_services |
Services that sent spans from the namespace in the last day. Empty means no spans arrived from this namespace |
traces_search |
Recent traces of one service, with an optional operation and duration bounds. Gives a summary per trace. limit defaults to 20, at most 100 |
trace_get |
One trace’s spans, searched over the last 7 days unless a window is given. Spans from namespaces the token can’t see are left out, so a gap in the tree is a span from elsewhere |
query_catalogue |
The query catalogue as worked examples, with metric queries filled in for this namespace |
cost_allocation |
What this namespace cost over window (1h, 24h (the default), 7d or 30d), by workload (the default) or namespace, from the cost engine in your cluster. Prices are checked against the price book; anything else is reported as unpriced with the reason. Node prices are never returned to a token. With aggregate (1 to 3 levels of namespace, controller, label:<key> or annotation:<key>, such as label:team,namespace) it returns chargeback rows with shared cost, idle and efficiency instead; needs agent 0.2.11. shareIdle spreads idle into the rows, for whole-cluster tokens only |
dashboards_list |
Your organisation’s dashboards: id, title and panel count. Drafts only with includeProposed: true |
dashboard_get |
One dashboard’s full spec: variables, panels, queries and layout |
dashboard_preview |
Runs every panel of a dashboard spec, unsaved, or of a saved dashboard or draft, as the Dashboards page would for this token, and reports per panel whether it shows data, is empty, refused or failed, and why. Counts only, never the data |
dashboard_templates |
Seylo’s dashboard templates, or one template’s spec |
apm_coverage |
For each Deployment and StatefulSet in the namespace: whether it serves traffic, whether spans arrive from it, its language and the evidence for it, and whether your OpenTelemetry Operator and an Instrumentation are there. See APM coverage. It only reads: instrumenting is a person’s approval in Seylo |
alerts_list |
Alerts for this namespace. status is open (the default), firing, acknowledged or resolved. limit defaults to 50, at most 200 |
alert_get |
One alert with its timeline. An alert in another namespace is reported as not existing |
silences_list |
Silences that cover this namespace. With includeEnded, also those that ended in the last 7 days |
Tools with a time window take either since or start and end, not both.
since is a duration such as 15m, 6h or 7d, and the default is 1h.
start and end are unix seconds.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Calls per token | 60 a minute, shared with every other read tool, such as logs, diagnose and validate. Writes, including the two proposal tools, are counted separately at 10 a minute. The refusal says how long to wait |
| Answer size | 4 MiB, the same ceiling as the Metrics page |
| Longest window | 30 days |
| Query length | 4000 characters |
| Points per series | 11,000 |
Every refusal says what to send instead, such as a shorter window, a larger
step or sum by (pod) instead of one query per pod.
Proposals
Section titled “Proposals”| Tool | Capability | Effect | What it does |
|---|---|---|---|
dashboard_propose |
dashboard_propose |
Propose | Saves a dashboard spec as a draft marked as proposed by this token. Nothing is published. An optional note for the reviewer can be up to 1000 characters. A token can have up to 10 drafts waiting |
scrape_target_propose |
scrape_target_propose |
Propose | Asks to add prometheus.io/scrape, prometheus.io/port and prometheus.io/path to a Deployment’s pod template. The request goes into the approval queue after an ownership check and a server-side dry run. workload and port are required. path defaults to /metrics. The optional reason can be up to 500 characters |
What the reviewer sees, and what is refused, is on proposals and approval.
Alert-rule and silence proposals aren’t available. A coding agent can read alerts and silences, but it can’t create either.
Long-running work
Section titled “Long-running work”deploy and rollback return before the work is finished. What comes next
depends on the client:
- If the client declares the MCP tasks extension
(
io.modelcontextprotocol/tasks), it gets a task handle. It pollstasks/get, and Seylo suggests waiting 3 seconds between polls. A handle stays valid for 24 hours, and only the token that created it can read it. - If it doesn’t, it gets the result inline with an
operationId, and it pollsoperation_status.
tasks/cancel stops the polling, not the deploy. Anything already applied
stays applied. Use rollback to undo it.