From Activepieces the Amazon work runs on a trigger rather than a prompt: schedule the report pull, patch listings when an upstream event fires, stage an audience once a threshold is crossed. Same scoped auth as every other client, no prompt required.
Use the Run Agent step's Agent Tools area when you want an Activepieces agent to connect to your private MCP server.
Activepieces also has built-in MCP server features for exposing Activepieces to MCP clients. That is the opposite direction. For the official server-side reference, see Activepieces MCP Server.
Your MCP server hostname is private to your deployment. It comes from your cloud provider, belongs to your environment, and is not shared across customers. Replace {your-private-mcp-host} with the private host shown in your dashboard.
Before you start
- Access to an Activepieces workspace where you can edit flows.
- A flow with a Run Agent step, or permission to add one.
- A private MCP server endpoint from your dashboard.
- An API key from the dashboard Keys tab, if your server requires bearer or header authentication.
- Confirmation of which authentication modes your Activepieces workspace exposes after opening the Authentication Type dropdown.
https://{your-private-mcp-host}/mcpUnderstand the direction
Activepieces can appear in MCP workflows in two different ways:
| Flow | What it does |
|---|---|
| Run Agent > Agent Tools > Add MCP Server | Activepieces connects an agent step to an external MCP server and can use its tools. |
| Activepieces MCP Server | Activepieces exposes its own tools to external MCP clients such as Claude, Cursor, or Windsurf. |
Use Run Agent > Agent Tools when connecting Activepieces to your private MCP server.
Open Run Agent
In your Activepieces flow, add or open a Run Agent step.
The observed Run Agent step includes:
| Area | What to configure |
|---|---|
| Prompt | Describe what you want the assistant to do. |
| AI Model | Choose the provider and model, such as OpenAI and gpt-5-mini. |
| Agent Tools | Connect apps, flows, MCPs, and other tools the agent can use. |
The Agent Tools area may show installed app icons, such as YouTube, Slack, GitHub, Notion, and a +500 indicator for additional integrations. Use Add from this area to connect more tools.
Add an MCP tool
From Run Agent > Agent Tools, click Add, then choose the MCP option. The current MCP form is Add MCP Server.
The form has four visible fields and two action buttons. Validate Server stays disabled until required fields are filled.
| Field | Required | Input type | Expected input |
|---|---|---|---|
| MCP Name | Yes | Text input | A short identifier, such as private-mcp or my-mcp-server. |
| Server URL | Yes | Text input | Your private MCP endpoint, such as https://{your-private-mcp-host}/mcp. |
| Protocol | Yes | Dropdown / combobox | Select Streamable HTTP unless your dashboard provides a different Activepieces-specific endpoint. |
| Authentication Type | Yes | Dropdown / combobox | Select the auth mode that matches your server. The observed default is None. |
Recommended generic values:
MCP Name: private-mcp
Server URL: https://{your-private-mcp-host}/mcp
Protocol: Streamable HTTP
Authentication Type: Bearer or header-based auth, if availableConfigure authentication
The observed form only shows Authentication Type = None while the dropdown is closed. It does not confirm which auth modes are available or whether choosing an auth mode reveals header fields.
If Activepieces supports bearer authentication, store the API key in the credential or secret field Activepieces provides.
If Activepieces supports custom headers, use this header shape:
Authorization: Bearer ${MCP_API_KEY}Do not paste a raw live key into labels, descriptions, prompts, or workflow notes. Use Activepieces' credential or secret storage if the form provides one.
Validate the server
After the required fields and authentication details are set, click Validate Server.
Validation should confirm that Activepieces can reach the MCP endpoint, negotiate the selected protocol, and authenticate if required. After validation succeeds, save or add the MCP server so it appears in the Run Agent step's Agent Tools list.
Troubleshooting
Validate Server is disabled
Fill every required field: MCP Name, Server URL, Protocol, and Authentication Type. The button should remain disabled while any required field is empty.
Authentication Type only shows None
Open the dropdown and check for bearer, header, OAuth, or custom authentication options. If none are available, the current Activepieces surface may only support unauthenticated MCP servers in that form.
The server URL fails
Confirm the URL uses the private host from your dashboard and the MCP path:
https://{your-private-mcp-host}/mcpIf your dashboard provides an Activepieces-specific or SSE-compatible endpoint, use that URL instead.
Validation succeeds but tools do not appear
Check whether Activepieces requires a second step to choose tools, enable the server, or attach the MCP server to the Run Agent step. Also confirm the server exposes tools over the selected protocol.