Tools
Every tool the Telflo MCP server offers, its inputs, the access it needs, and the CLI command it matches.
The MCP server offers 21 tools: the telflo CLI's commands minus those that only make sense on your own machine, such as login and skills install. Where a CLI command reads a file, the tool takes the content as an inline string. The tools call a deploy group a deployment, as the API does.
Common inputs
| Input | Meaning |
|---|---|
org_id? (UUID) | The organization to act in, an id from list_organizations; a tf_ token ignores it. Signed in as yourself, you need it only when you belong to several organizations and your client sends no X-Telflo-Org header (Choose an organization). |
configuration_id, fleet_id, deployment_id, run_id (UUID) | IDs from list_configurations, list_fleets, list_deployments, and run_pipeline_test. A value that is not a UUID is refused before any request. |
version (integer, 1 or more) | A configuration version number. Where optional, it defaults to the latest version, or on deploy_configuration to the published version. |
yaml, sample_text (string) | The full collector configuration or test sample, inline. Size limits are on Limits. |
In the tables below, ? marks an optional input and org_id is left out. Access is Read when a Read token can call the tool and Write when it needs Read & Write; signed in as yourself, your role decides what you can change. CLI flags are on Commands.
Identity
| Tool | What it does | Inputs | Access | CLI equivalent |
|---|---|---|---|---|
whoami | Returns who the credential acts as: org_id, token_name (the token's name, or your email address), claims, the granted access, and kind (service_account or user). | None | Read | telflo whoami |
list_organizations | Lists the organizations the credential can act in, with id, name, type, and your role. A tf_ token returns its one organization. It works before an organization is chosen. | None, and no org_id | Read | None |
Configurations
| Tool | What it does | Inputs | Access | CLI equivalent |
|---|---|---|---|---|
list_configurations | Lists the configurations you can see (your own, drafts included, and every published one), without YAML: id, name, is_published, version_number (the latest), published_version_number, collector_version, and collector_distribution. | None | Read | telflo config list |
get_configuration | Shows a configuration with its latest version's YAML and collector pin, plus its versions, newest first, each with version_number, status (draft or published), description, and created_at. | configuration_id | Read | telflo config get <id> |
get_configuration_version | Returns one version's YAML and the collector version and distribution it is pinned to. | configuration_id; version? | Read | telflo config pull <id> |
get_validation_rules | Shows the rules saved on a version's Validation sub-tab, grouped by pipeline, each with rule_type, rule_input, target, and api_owned (true for rules saved through the API). | configuration_id; version? | Read | telflo config rules <id> |
create_configuration | Creates a configuration with the YAML as its unpublished draft, version 1, and returns it with its id. The YAML is not validated, and the configuration runs on the server default collector. | name; yaml | Write | telflo config create |
push_configuration | Saves YAML to an existing configuration: if the latest version is a draft, it is validated and edited in place; if published, the YAML is validated on its collector pin and appended as a new version. Returns status: "saved" with action (patched or appended), version_number, and published, or status: "invalid" with errors. | configuration_id; yaml; publish? (boolean); description? (an appended version's label, at most 200 characters; a longer one returns status: "invalid" with validation failed) | Write | telflo config push <id> |
publish_configuration_version | Publishes a version and returns the configuration. Published versions are immutable; see Versions & publishing. | configuration_id; version | Write | telflo config publish <id> |
Validation and OTTL
| Tool | What it does | Inputs | Access | CLI equivalent |
|---|---|---|---|---|
validate_configuration | Validates YAML against a real collector binary. Returns valid, version, errors (each with message and component_path), and collector, the pin used, where nulls mean the server default. | yaml; configuration_id?, whose pin to use; collector_version? (such as 0.147.0) and distribution? (such as otelcol-contrib), which override that pin | Read | telflo validate <file> |
lint_ottl | Parse-checks OTTL with the real grammar. Returns valid, ottl_version, checked, items (each with kind, index, input, valid, error, context, location, a dotted YAML path, and an advisory note), and skipped, the expressions the linter cannot judge. | yaml?; context? (span, spanevent, metric, datapoint, log, resource, or scope); kind? (condition, the default, statement, or value); expressions? (array of strings) | Read | telflo ottl lint |
Pass configuration_id to validate_configuration whenever the YAML belongs to a stored configuration: on the server default collector, YAML can pass and still fail on push or in the fleet. Passing the ID of a configuration locked to ClickStack fails with Unknown collector distribution: 'clickstack'; see Which collector runs it.
Without context, lint_ottl checks every transform, filter, routing, and tail_sampling expression in yaml, a whole collector configuration. With context, it lints raw expressions of the given kind from expressions and from the lines of yaml; expressions without context is refused. A single-escaped regex such as "\d" is reported as an error even though it parses; write "\\d".
Flows
| Tool | What it does | Inputs | Access | CLI equivalent |
|---|---|---|---|---|
list_flows | Lists the prebuilt flows without YAML: slug, name, summary, signals, tags, and the collector_version and collector_distribution each was validated on. | None | Read | telflo flows list |
get_flow | Returns one flow with its description in Markdown and its yaml. | slug | Read | telflo flows get <slug> |
A configuration created from a flow's yaml runs on the server default collector, not the flow's; Start from a flow says how to keep the flow's collector.
Fleets and deploys
| Tool | What it does | Inputs | Access | CLI equivalent |
|---|---|---|---|---|
list_fleets | Lists the organization's fleets with id, label, type (server-supervisor for a server fleet, kubernetes-supervisor for a Kubernetes supervisor fleet), status, and created_at. Kubernetes bridge fleets are not included. | None | Read | telflo fleet list |
list_deployments | Lists a fleet's deploy groups with id, name, configuration_id, version_number (the version it serves), replicas, namespace, and role. | fleet_id | Read | telflo fleet deployments <fleet-id> |
create_fleet | Creates a fleet and issues its tokens. Returns id, label, type, token_id (the install token's ID, never its value), and token_expires_at, null because the install token does not expire. | label (unique in the organization); type (server-supervisor or kubernetes-supervisor); expires_in? (180d, 1y, 2y, or never, the default), the fleet token's lifetime on a server fleet | Write | telflo fleet create |
get_fleet_install_command | Returns the command that installs a collector into a fleet: docker or linux (the All In One supervisor bundle, from a download URL valid for 24 hours) on a server fleet, kubernetes (Helm) on a Kubernetes supervisor fleet. Also returns url, url_expires_at, env_var_names, notes, and the command's parts, including token for docker and linux. Where a note says --env NAME=value, pass the value in env. | fleet_id; platform (docker, linux, or kubernetes); deployment_id?, needed only on a Kubernetes supervisor fleet with several deploy groups (a server fleet defaults to Default); server_name? (docker); arch? (amd64, the default, or arm64), root_path? (default /etc/otelcol), and systemd? (default true) for linux; env? (variable name to value; names use letters, digits, and _, not starting with a digit) | Write | telflo fleet install <fleet-id> |
deploy_configuration | Rolls a published version out to a deploy group and returns action (updated or created), id, and version_number. It updates the group deployment_id names, else the one group already serving the configuration; name and role apply only when no group serves it and the tool creates one. | fleet_id; configuration_id; version?; deployment_id?; name?; replicas? (integer); namespace?; role? (node, cluster, or gateway, on a Kubernetes supervisor fleet) | Write | telflo deploy |
get_fleet_install_command refuses a platform that does not match the fleet type; Install collectors and Deploy cover the order of the steps.
The install command carries the fleet's install token, so have the agent hand it to whoever runs it and keep it out of other tools and logs; see Secrets in transcripts.
Pipeline tests
| Tool | What it does | Inputs | Access | CLI equivalent |
|---|---|---|---|---|
run_pipeline_test | Runs a pipeline test in the sandbox on a real collector: replays sample_text through one pipeline and checks the rules. Waits up to wait_seconds, then returns id, status (Success, Fail, Error, or Running for a longer run), success, stderr, validation_results, rules_source, validation_pipeline (with save_rules), and collector, the pin sent, where nulls mean the stored version's own pin on a stored-version run, else the server default. | signal_type, pipeline, sample_text, and more; see Test inputs | Write | telflo test |
get_test_run | Returns a run: id, status (Queued, Running, Success, Fail, or Error), success, stderr, collector_version and collector_distribution, mutations, the sandbox's changes and advisories (such as R-105 when an organization variable was replaced with a placeholder), and, once finished, validation_results. | run_id | Read | None; telflo test polls for you |
get_test_run_output | Returns run_id and output, what the target pipeline emitted. A 404 means the run has not finished or produced no output. | run_id | Read | None; telflo test --output |
Test inputs
| Input | Meaning |
|---|---|
signal_type | The signal the sample carries: traces, metrics, or logs. |
pipeline | The service.pipelines key to test, such as logs/in. Only this pipeline runs. |
sample_text | The sample to replay, matching the pipeline's receiver: OTLP JSON for OTLP receivers, raw lines for filelog, syslog lines for syslog. At most 1 MB; sample, YAML, and rules together must stay under 1 MB once JSON-encoded. |
duration_seconds? (integer) | How long the sandbox collector runs, 1 to 60 seconds. Default 5. |
yaml?, configuration_id?, version? | What to test: yaml, a stored version (configuration_id and version, default the latest), or yaml on that version's collector pin. |
collector_version?, distribution? | The collector to run on. Overrides any pin. |
rules? (array) | 1 to 20 assertions, described below. |
save_rules? (boolean) | Save rules to the version's Validation sub-tab for pipeline, replacing the rules saved earlier through the API and keeping rules added by hand, then run the whole saved set. |
use_saved_rules? (boolean) | Run the rules already saved there for pipeline. |
name? | The test's name, at most 200 characters. With save_rules, the saved set's display name. |
wait_seconds? (integer) | How long to wait for the result, 0 to 90 seconds. Default 45, as many clients give up on a call after 60; 0 returns at once. |
Each item in rules is an OTTL assertion over what the pipeline emits, with the fields of the editor's validation rules; Write the rules covers writing good ones.
| Field | Meaning |
|---|---|
context | The OTTL context the rule evaluates: span, spanevent, metric, datapoint, log, resource, or scope. |
quantifier | all passes when every record matches, including when there are none; any when at least one matches; none when none matches. count compares the number of matching records with count, and distinct counts the distinct values of expression. |
condition? | A boolean OTTL condition. Required except with distinct, where it filters the records first. |
expression? | distinct only, and required there: the value expression whose distinct values are counted. Use Concat([...], "|") for composite keys. |
count? | operator (eq, ne, gt, gte, lt, lte, or between), value (the lower bound for between), and value2? (the upper bound). Required with count and distinct. |
name? | The label shown in validation_results. |
run_pipeline_test checks how its inputs combine before it starts a run:
| Inputs | Rule |
|---|---|
yaml, configuration_id | Pass one or both. |
version | Needs configuration_id. |
rules, use_saved_rules | Pass exactly one. |
save_rules, use_saved_rules | Set at most one. Both need configuration_id without yaml. |
The sandbox strips connectors, removes every pipeline but the target, and does not substitute organization variables (${org:NAME} or $orgvar:NAME), so inline real values. If the client sends a progress token, the tool reports progress on the first poll and then at most every 10 seconds; Wait for the result covers polling.
Results and errors
Every result is JSON, sent as text and structured content. The results below mean the call succeeded; the agent fixes the YAML or polls the run.
| Result | Returned by | Meaning |
|---|---|---|
status: "invalid" with errors | push_configuration | Nothing was saved. errors says why, usually a failed validation. |
valid: false | validate_configuration, lint_ottl | The collector rejected the YAML, or an OTTL expression did not parse. |
status: "Fail" | run_pipeline_test, get_test_run | The run finished and at least one assertion failed. validation_results says which. |
status: "Error" | run_pipeline_test, get_test_run | The collector or the sandbox failed. Read stderr first. |
status: "Running" with id | run_pipeline_test | The run outlived wait_seconds, or a poll failed and poll_error says why. Poll get_test_run with the id. |
A result with isError set means the call itself failed, and its text says nothing about your YAML. Troubleshooting has every error string and its fix.
| Text starts with | Meaning |
|---|---|
Telflo rejected the token (401) | The credential is wrong, expired, or deleted, or its service account left the organization. |
Not allowed (403) | A read-only token tried a write, the credential is not in the organization, or your role does not allow the change. |
Rate limited by the Telflo API (429 | The credential used its 60 requests a minute, shared with the CLI. Retry after a few seconds. |
could not validate, could not lint | The validator or the OTTL linter was unavailable. Nothing was checked or saved. |
Telflo API error <status> | Any other API refusal, such as 404 for an ID you cannot see. See error statuses. |
Pass org_id, Your account has no active organization | You belong to several organizations and the call named none (the message lists them), or the account has no active organization, which should not happen. |
Several deployments serve, No deployment serves, This configuration has no published version | deploy_configuration could not choose a deploy group or version; the message says which input to pass. |
A message naming the inputs, such as version needs configuration_id. | Inputs that do not fit together, or a value outside the schema, such as an ID that is not a UUID. |
Tool annotations
Each tool declares four MCP annotations, which some clients use to decide which calls need your approval. Approvals for writes says which tools to keep approving.
| Annotation | Value | What it means |
|---|---|---|
readOnlyHint | true on the 14 Read tools, false on the seven Write tools | The tool changes nothing in Telflo. |
idempotentHint | true on the Read tools and publish_configuration_version, false on the other six Write tools | Repeating the call with the same inputs has no further effect. |
destructiveHint | false on every tool | No tool deletes a configuration, version, fleet, deploy group, or token. Some writes replace earlier state: push_configuration overwrites the latest version while it is a draft, deploy_configuration changes the version a deploy group runs, and run_pipeline_test with save_rules replaces the rules saved earlier through the API for that pipeline. |
openWorldHint | false on every tool | Every tool reaches only Telflo's API. |
get_fleet_install_command is marked as a write because each call can mint a fresh download URL, is audited, and hands out the fleet's install token. Annotations do not grant or limit access; the credential does.
Server instructions
When a client connects, the server also sends a short guide, which clients that support server instructions pass to the agent. It covers the same ground as Working with an agent.
Last updated on