Overview
Connect Claude Code, Cursor, claude.ai, or another MCP client to Telflo so an agent can validate, test, publish, and deploy collector configurations as tool calls.
The Telflo MCP server gives an AI agent your organization's configurations, validation, OTTL lint, flows, fleets, deploys, and pipeline tests as 21 tools. It is hosted at https://mcp.telflo.com/mcp; add that URL to any client that supports remote MCP servers over Streamable HTTP, such as Claude Code, Cursor, claude.ai, or VS Code.
The server wraps the same operations as the Telflo CLI, with exactly the CLI's access. Each tool call goes to the Telflo API with the credential your client sends, and reaches nothing else.
Connect in a minute
In Claude Code:
-
Add the server:
claude mcp add --transport http telflo https://mcp.telflo.com/mcpTo add it for every project, put
--scope userbeforetelflo. -
Start Claude Code with
claude, run/mcp, selecttelflo, and choose Authenticate. Your browser opens Telflo; sign in if asked. -
On the Authorize page, check that You will be sent back to shows a
localhostaddress, which is Claude Code on your machine, then select Allow. -
Ask the agent "Who am I in Telflo?" It calls
whoami, which returnskindasuser, your email address astoken_name, and theorg_idit acts in.
Every account has a personal workspace, so if you also belong to a team's organization, whoami fails and lists them; tell the agent which one to use, or see Choose an organization.
Two ways to sign in
Configure each client with your own sign-in or an API token from a service account. Both reach the same tools; they differ in who the agent acts as.
| Sign in as yourself | Service-account token | |
|---|---|---|
| How the client connects | It opens Telflo in your browser and you approve it on the Authorize page. | It sends Authorization: Bearer tf_... with every request. |
| Acts as | You, with your role. | The token's service account, a Contributor. |
| Organization | Any organization you are an active member of; the agent passes org_id to choose one. | The one organization the token belongs to. org_id is ignored. |
| Access | Everything your role allows. It sees your own drafts and every published configuration. | Read or Read & Write, set by the organization admin who creates the token under Settings > Service Accounts. It sees the service account's drafts and every published configuration. |
| Attribution | Changes are yours, as if made in the web app. | Changes are the service account's. Members, you included, see a configuration it creates only after it is published. |
| Best for | Your own agent, working on your behalf. | Shared or unattended agents, and agents you want to keep read-only. |
What an agent can do
The tools cover the CLI's commands except local-only ones such as login and skills install. Where a command reads a file, the tool takes the content.
| Area | What an agent can do |
|---|---|
| Identity | Confirm who it acts as, and list the organizations it can work in. |
| Configurations | List and read configurations and their versions, create a draft, save YAML as a draft edit or a new version, and publish a version. |
| Validation and OTTL | Validate YAML on a real collector, including the one a configuration is pinned to, and parse-check OTTL expressions. |
| Flows | Browse the prebuilt flows and start a configuration from one. |
| Fleets and deploys | List fleets and deploy groups, create a fleet, roll a published version out to a deploy group, and prepare a collector install command. The tools call a deploy group a deployment. |
| Pipeline tests | Replay a sample through one pipeline in the testing sandbox, check assertions on what it emits, and save the rules to a version's Validation sub-tab. |
Fourteen tools only read, so a Read token can call them; the other seven need a Read & Write token or your own sign-in. No tool deletes a configuration, version, fleet, deploy group, or token, but 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.
MCP server, CLI, or AI assistant
| MCP server | telflo CLI | AI assistant | |
|---|---|---|---|
| Where it runs | Hosted by Telflo; nothing to install. | Your machine or a CI runner, from npm (Node.js 20 or newer). | A chat panel in the Telflo editor. |
| How it signs in | Your browser sign-in, or a service-account token in a header. | telflo login, or a service-account token in TELFLO_API_TOKEN. | Your web app session. |
| Best for | Agents in an MCP client, including chat clients with no shell. | You in a terminal, scripts and CI that check exit codes, and coding agents that run shell commands. | Changing the configuration open on the canvas, and OpenTelemetry questions. |
For agents that run shell commands, the CLI also bundles a skill.
Limits
| Limit | Value |
|---|---|
| Requests | 60 per minute per credential, shared with the CLI or scripts using that credential. run_pipeline_test polls while it waits, and each poll counts. Above that, calls fail with 429; retry after a few seconds. |
| Request size | 2 MB per request to the MCP server, and 1 MB per request it makes to the Telflo API. A configuration must fit in 1 MB, as must a pipeline test's YAML, sample, and rules together. |
| Rules | 1 to 20 per run_pipeline_test call. |
| Test run | duration_seconds is 1 to 60, 5 by default. run_pipeline_test waits up to wait_seconds, 45 by default and at most 90; a longer run returns status: "Running" and the agent polls get_test_run. |
| IDs | org_id and every configuration, fleet, deployment, and test run ID must be a UUID. Anything else is refused before any request. |
| Collector distribution | Only otelcol-contrib can be named as a distribution, so some calls on a configuration locked to ClickStack are refused; see Which collector runs it. |
| Flows | A configuration an agent creates from a flow runs on the server's default collector version, which can differ from the flow's; see Start from a flow. |
Continue with Connect a client, the tool reference, Working with an agent, Access and security, and Troubleshooting.
Last updated on