> ## Documentation Index
> Fetch the complete documentation index at: https://www.activepieces.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

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

\
Quick Start
-----------

### 1. Get Your Server URL

1. Go to **Settings** → **MCP Server**
2. Toggle the server **on**
3. Copy the **Server URL**

### 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 theme={null}
{
  "mcpServers": {
    "activepieces": {
      "url": "https://your-instance.com/mcp"
    }
  }
}
```

| 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

Tools are organized into categories. **Discovery tools** are always available. Other categories can be enabled or disabled per-project in the MCP Server settings.

| Category | Description |
| - | - |
| Discovery | Read-only tools for exploring flows, pieces, connections, tables, runs, and validation — including semantic search over the action and trigger catalog |
| Flow Management | Create, duplicate, rename, publish, and enable/disable flows |
| Flow Building | Add, update, and delete steps and triggers |
| Router & Branching | Add, update, and delete conditional branches |
| Annotations | Manage canvas notes |
| Tables | Full CRUD for tables, fields, and records |
| Testing & Runs | Test flows, inspect results, retry failures |

See the [Tools Reference](https://www.activepieces.com/docs/mcp/tools.md) for the complete catalog with input schemas, and [Tool Search](https://www.activepieces.com/docs/mcp/tool-search.md) 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.

## Self-Hosting Behind a Reverse Proxy

The MCP server and its OAuth endpoints are reachable both at the host root (`https://your-instance.com/mcp`) and under a path prefix (`https://your-instance.com/<prefix>/mcp`) when your reverse proxy routes `https://host/<prefix>/*` to Activepieces.

For a subpath deployment to work, set `AP_FRONTEND_URL` to the full public URL **including the prefix** (e.g. `https://your-instance.com/activepieces`). Activepieces then advertises its OAuth issuer, authorization/token endpoints, protected-resource metadata, and the `WWW-Authenticate` discovery header under that prefix, so the entire handshake stays inside your proxy rule.

> [!NOTE]
>
> Clients that ignore the `WWW-Authenticate` header and probe the RFC well-known paths at the host root (`https://host/.well-known/oauth-*`) require an additional proxy rule forwarding those host-root paths to Activepieces — that namespace is anchored to the host root by RFC 8414/9728 and cannot be relocated under the prefix. Header-honoring clients (such as Claude) do not need this.

## 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-scoped** — all operations are scoped to the authenticated project
* **Sensitive setup** — `ap_setup_guide` returns instructions for the user to configure connections in the UI, rather than handling secrets through MCP


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.