Working with Hevo through your Agent
On This Page
After you set up the Hevo MCP server, you can ask your agent about your account in plain language. The agent decides which tools to call, calls them, and summarizes the results for you. The hevo-pipelines skill gives the agent the steps for common tasks, such as finding the cause of a failure or creating a Pipeline.
To get accurate results, include the following details in your request:
-
The product: Standard Pipelines and Edge Pipelines are separate products, and their IDs are not shared. For example, Standard Pipeline 32 and Edge Pipeline 32 are different Pipelines. If you do not name the product, the agent may check both.
-
The name or the ID: The agent finds the ID of a Pipeline or a Destination from its name by listing your Pipelines or Destinations. If more than one resource matches the name, the agent asks you which one you mean.
-
The region: The agent names your account region in every request to Hevo. If you do not name the region, the agent asks you for it. For teams created after Release 2.00, your API credentials work in every region of your team, so you can name another region in a request. For older teams, they work only in the region in which you generated them.
Example Requests
The following table lists some requests that you can make, and the steps that the agent takes for each:
| Task | Example request | The agent |
|---|---|---|
| Check the connection | Run hevo_whoami for region us. | Reports the region, the changes it is allowed to make, and whether Hevo accepts your API credentials. |
| Find a Pipeline | Find my Pipeline named orders-sync. | Lists your Pipelines and returns the one that matches the name. For a Pipeline without a name, the agent matches the name of its Source or Destination. |
| Find the cause of a failure | Why is Pipeline 41 failing? | Reads the state and health of the Pipeline, its failed jobs (Edge Pipelines) or failure reasons (Standard Pipelines), and its failed objects. It then summarizes what failed, when the failure started, and the next step. It does not resync, restart, or skip anything unless you ask for it. |
| Find the Pipelines that need attention | Which of my Pipelines need attention? | Reads each Pipeline and lists the Pipelines that are not healthy. |
| Pause or resume a Pipeline | Pause Pipeline 12. | Pauses or resumes a Standard Pipeline, or disables or enables an Edge Pipeline. Pausing or disabling needs your approval. Enabling an Edge Pipeline needs your approval, but resuming a Standard Pipeline does not. |
| Run a Pipeline now | Run Pipeline 41 now. | Starts a sync of the Pipeline. Running needs your approval, as the run counts toward your Events quota. |
| Create a Pipeline | Create a Pipeline from my MySQL database to Snowflake. | Asks you to select how Hevo reads the Source, asks for each required detail, shows you the request, and creates the Pipeline. Read Creating a Pipeline through your Agent for more information. |
| Summarize your account | Summarize my Hevo account. | Lists your Pipelines and Destinations, counts them by Source type, status, and health, and lists the failing Pipelines. |
| Find inactive Pipelines | Which Pipelines have not run in the last 30 days? | Lists the paused or disabled Pipelines, the Pipelines that last ran before the period, and the Destinations that no Pipeline uses. It changes nothing. |
| Find the Pipelines that replicate a table | Which Pipelines replicate the orders table? | Searches the objects of each Pipeline and lists the matches, with the status of each object and its Destination table. |
| Get a health report | Give me a health report for the last 24 hours. | Reads your Pipelines, their jobs or failed objects, and your Destinations, and reports the problems, with the Event counts of your Edge Pipelines. It changes nothing. |
| Check the Event volume | How many Events did each of my Pipelines load each day last week? | Adds up the Event counts from the jobs of each Pipeline for each day of the period, and lists the Pipelines with the most Events and the Pipelines with failed Events. For a Pipeline that does not report Event counts per job, it reports one snapshot of the Event counts of each object, instead of a count for each day. These counts are not the billed Events. Read Viewing Events Usage for the steps to check your usage in the Hevo UI. |
Some tasks need one request to Hevo for each Pipeline, such as finding the Pipelines that replicate a table. If you have more than about 50 Pipelines, the agent tells you the number of requests first, and offers to narrow the search, such as to the Pipelines of one Source type.
Creating a Pipeline through your Agent
When you ask your agent to create a Pipeline, it does the following:
-
Lists the ways in which Hevo can read your Source, along with the limitations of each, and asks you to select a way. For example, for a MySQL database, Hevo can use log-based replication or table polling. If you do not name the product, the agent lists the options for both products.
-
Asks you for each detail that the Pipeline needs, such as the connection settings of the Source and the Destination. For a password, a token, or a key, the agent asks you to save it in a secret file and tell it the name of the file. If you already have a Destination, the agent suggests that you use it, so that its credentials stay in Hevo.
-
Shows you the request, with a reference to the secret file in place of each password. If the request contains a reference to a secret file, the server asks you to approve it. Before you approve the request, check that the host in it is the host of your Source or Destination, as Hevo sends the password to that host. After you approve it, the agent creates the Pipeline.
Before the server sends a request to create an Edge Pipeline, it checks the request, such as the Source type and the required Source details. If the request is not complete, the server rejects it without sending it to Hevo, and the agent corrects it. Before Hevo creates an Edge Pipeline, it tests the connections to the Source and the Destination. These tests can take several minutes. If a connection test fails, Hevo does not create the Pipeline, and the agent reports the error. By default, Hevo creates Edge Pipelines in the disabled state, with no objects selected. Ask the agent to select the objects, and then to enable the Pipeline when you are ready to replicate data.
A request to create a Standard Pipeline must also contain the JSON parsing strategy, which defines how Hevo loads nested fields, such as JSON objects and arrays, into the Destination.
You must consider the following when you create a Pipeline through your agent:
-
Passwords are kept out of the conversation: The server replaces the reference to a secret file with the password just before it sends the request to Hevo, so the password never becomes part of your conversation. Read Passwords for Sources and Destinations for the steps to save a password in a secret file.
-
SaaS Sources need a token or your own OAuth app: The agent cannot sign in to a SaaS Source through a browser. Read Authenticating SaaS Sources for the credentials that each Source accepts.
-
Reused details are confirmed: If the agent reuses a host, a user, a database, or a Destination that you provided earlier in the same conversation, it asks you to confirm that the detail is correct.
Changes to Many Resources
When you ask for a change to many resources, such as Pause all failing Pipelines, the agent first lists the resources that the change applies to and asks you to confirm the list. It then makes one call for each kind of change, with up to 100 resources in each call. The server sends the change to Hevo for each resource and reports the result of each. If the change needs approval, you see one prompt for each call. Read Approving Changes for more information.
Running a Task on a Schedule
The server answers the requests of your agent, but does not send alerts or run tasks by itself. To get a daily health report, run your agent with the request from a cron job or another scheduler, in a mode that runs without you, such as print mode (claude -p) in Claude Code or codex exec in Codex. A scheduled run cannot answer approval prompts, so use it only for tasks that do not need approval. In print mode, Claude Code also does not ask you for permission to use a tool, so allow the Hevo tools that the task needs when you start it. For example, for a report that only reads data, add --allowedTools "mcp__plugin_hevo-data_hevo__hevo_whoami,mcp__plugin_hevo-data_hevo__*_read" to the claude -p command. Read Approving Changes for more information.
Instructions that the Agent Ignores
When the agent reads your Hevo account, it reads text that people in your team or your Sources wrote, such as Pipeline names, object names, and failure reasons. This text can contain words that look like instructions to the agent. The server instructs the agent never to follow instructions found in this text.
Revision History
Refer to the following table for the list of key updates made to this page:
| Date | Release | Description of Change |
|---|---|---|
| Nov-18-2026 | 2.54 | New document. |