---
title: "MCP Server"
icon: "plug"
description: "Connect AI assistants to Activepieces using the Model Context Protocol (MCP)"
---

Activepieces includes a built-in [MCP](https://modelcontextprotocol.io/) server that lets AI assistants build flows, manage tables, test automations, and more — all through natural language.

## <br />Quick Start

### 1. Get Your Server URL

Open **MCP** in the sidebar. The **Connect** tab shows the server URL, `https://your-instance.com/mcp/platform`, and the setup steps for each client.

<Note>
  The platform URL reaches every project you can open, and the client picks a project with `ap_set_project_context`. To connect a client to one project only, use `https://your-instance.com/mcp` instead: the sign-in page then asks which project to connect. Flows that start with the **MCP Tool** trigger show up as tools only on this project URL.
</Note>

### 2. Connect Your Client

Add the URL to your MCP client config. Authentication is handled via OAuth — your client will open a browser to authenticate on first use.

```json
{
  "mcpServers": {
    "activepieces": {
      "url": "https://your-instance.com/mcp/platform"
    }
  }
}
```

| Client | Config Location |
| --- | --- |
| Cursor | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| Devin (formerly Windsurf) | `~/.config/devin/mcp_config.json` |
| GitHub Copilot CLI | `~/.copilot/mcp-config.json` |
| goose | `~/.config/goose/config.yaml`, under `extensions` |
| Cline | **MCP Servers** → **Configure MCP Servers** |
| Zed | `~/.config/zed/settings.json`, under `context_servers` |
| Antigravity | `~/.gemini/config/mcp_config.json`, with `serverUrl` instead of `url` |
| Claude.ai | **Organization Settings** → **Connectors** → **Add** → **Custom connector** |

### 3. Start Building

Once connected, ask your AI assistant things like:

- _"Create a flow that sends a Slack message when a new row is added to Google Sheets"_
- _"Check my flow for any issues before publishing"_
- _"Create a Contacts table and add 3 records"_
- _"Show me the last failed run and what went wrong"_
- _"What Slack triggers are available?"_

## Tool Categories

The **Tools** tab of the MCP page switches the built-in tools on and off for each project, in four groups:

| Group | Description |
| --- | --- |
| View | View flows, runs, tables, connections and pieces — including semantic search over the action and trigger catalog. Always on. |
| Edit flows | Create, rename and duplicate flows, and edit drafts |
| Publish and run | Publish, test and run flows and actions, and change tables |
| Delete | Permanently delete flows, tables, fields and records |

A platform admin can switch tools off for every project under **Platform Admin** → **MCP Server**. A project cannot switch on a tool that the platform switched off. Piece actions are controlled in piece sets.

See the [Tools Reference](/mcp/tools) for the complete catalog with input schemas, and [Tool Search](/mcp/tool-search) for how agents find the right action or trigger by describing a task in plain language.

<Note>
  MCP tools are free, except `ap_run_action`, which costs 1 credit per call. A flow that a tool call starts is billed as a normal flow run.
</Note>

## Self-Hosting Behind a Reverse Proxy

The MCP server and its OAuth endpoints live at the root of the Activepieces host: `/mcp`, `/mcp/platform`, `/authorize`, `/token`, `/register`, `/revoke`, `/userinfo` and the `/.well-known/oauth-*` paths. Forward them to Activepieces without a redirect. A client drops its `Authorization` header when it follows a redirect to another origin, and a redirect from `http` to `https` counts as another origin.

To serve MCP from its own hostname, or under a path prefix of a gateway, set `AP_MCP_URL`. See [Serving MCP from its own hostname](/install/reference/environment-variables#serving-mcp-from-its-own-hostname).

## Security

- **OAuth authentication** — secure, token-based authentication handled automatically by your MCP client
- **Credentials are never exposed** — connection secrets, API keys, and OAuth tokens are never returned by any tool
- **Project roles apply** — each call runs in one project with your role there: the project chosen at sign-in for `/mcp`, or the one selected with `ap_set_project_context` for `/mcp/platform`
- **Revocable** — the **Connections** tab lists each connected client, and **Revoke** ends its access at once
- **Sensitive setup** — `ap_setup_guide` returns instructions for the user to configure connections in the UI, rather than handling secrets through MCP
