# Quick Start: Activepieces MCP

Canonical page: https://www.kuudo.com/docs/quick-start/activepieces/

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](https://www.activepieces.com/docs/mcp/overview).

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.

```text
https://{your-private-mcp-host}/mcp
```

## Understand 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:

```text
MCP Name: private-mcp
Server URL: https://{your-private-mcp-host}/mcp
Protocol: Streamable HTTP
Authentication Type: Bearer or header-based auth, if available
```

## Configure 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:

```text
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:

```text
https://{your-private-mcp-host}/mcp
```

If 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.

## Related docs

- [MCP Client Configuration](/docs/mcp-client-configuration/)
- [n8n MCP](/docs/quick-start/n8n/)
- [Hermes MCP](/docs/quick-start/hermes/)