> For the complete documentation index, see [llms.txt](https://docs.flowcp.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowcp.ai/guides/agent-driven-onboarding.md).

# Agent-driven onboarding

FlowCP can be driven end-to-end by an AI coding agent (such as Claude Code). Instead of clicking through the dashboard, your agent connects an app, imports its API, enables tools, configures OAuth, publishes a server, and reads back the final MCP config — all through a hosted MCP server that exposes FlowCP's own control plane.

This works because FlowCP **dogfoods itself**: the platform's control-plane API is described by an OpenAPI document committed to the FlowCP GitHub repo as `openapi.json` (generated with `pnpm gen:openapi`), and that document is imported into FlowCP like any other app. The result is a published MCP server whose tools are the FlowCP operations themselves.

***

## How authentication works

The platform MCP server uses the standard MCP OAuth 2.1 flow (authorization code + PKCE, with dynamic client registration). Your AI client:

1. Connects to the platform MCP server URL.
2. Is redirected to FlowCP to authorize. You log in (or are already logged in to the dashboard) and approve.
3. Receives a workspace-scoped access token, which it presents on every tool call.

Every tool call acts **only** within the workspace bound to that token — an agent can never reach another workspace by changing a parameter.

***

## The tool workflow

Once connected, these tools are available to the agent (names match the operations in the repo's `openapi.json`):

| Tool                                   | What it does                                                         |
| -------------------------------------- | -------------------------------------------------------------------- |
| `get_context`                          | Show the user and workspace the token is bound to.                   |
| `connect_app`                          | Connect a new app (Bubble or generic OpenAPI).                       |
| `initiate_verification` / `verify_app` | Bubble ownership verification (see below).                           |
| `import_api`                           | Provision server branches and import the Swagger document.           |
| `get_import_status`                    | Poll an import until it is `valid`.                                  |
| `list_tools`                           | List the tools generated from the import.                            |
| `enable_tool`                          | Enable/disable or rename a generated tool.                           |
| `configure_oauth`                      | Set the OAuth provider config for the app.                           |
| `publish_server`                       | Publish the server (runs safety checks).                             |
| `get_mcp_config`                       | Return the hosted MCP server URL and a ready-to-paste client config. |
| `get_app_stats`                        | Read usage stats for an app (invocations, users, success/error).     |
| `list_app_logs`                        | List an app's execution logs, newest first, with optional filters.   |
| `list_skills` / `create_skill`         | List or author agent skills (SKILL.md playbooks) for a server.       |
| `update_skill` / `delete_skill`        | Enable/disable, edit, or remove a skill.                             |
| `list_widgets` / `create_widget`       | List or author interactive widgets for a server.                     |
| `update_widget` / `delete_widget`      | Enable/disable, edit, or remove a widget.                            |

A typical agent run looks like:

```
get_context
→ connect_app  (provider: "openapi", swaggerUrl: "https://my.api/openapi.json")
→ import_api   (then get_import_status until valid)
→ list_tools
→ enable_tool  (for each tool you want exposed)
→ configure_oauth
→ publish_server
→ get_mcp_config
```

### The one human-in-the-loop step

For **Bubble** apps, ownership must be proven before importing. The agent calls `initiate_verification` to get a token, relays the instructions to you, you publish the token in your Bubble app, and then the agent calls `verify_app`. **Generic OpenAPI apps skip this** — they are verified automatically when their Swagger URL is reachable, so the agent can go straight from `connect_app` to `import_api`.

### Default-deny still applies

Imported tools always start **disabled**. The agent must call `enable_tool` explicitly for each one. Enabling a destructive tool requires `requiresConfirmation: true`, otherwise `publish_server` will refuse to publish.

***

## Connecting the platform to itself

To create the platform MCP server in your own deployment, run the bootstrap script against a running API and an existing workspace:

```bash
PLATFORM_WORKSPACE_ID=<workspace-id> pnpm connect:platform
```

It connects the repo-hosted `openapi.json` (by default the raw GitHub URL) as an OpenAPI app, imports it, enables the agent tools, configures OAuth against the platform identity provider, publishes the server, and prints the MCP client config to paste into your AI client.

The relevant environment variables:

| Variable                                                    | Purpose                                                                          |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `API_PUBLIC_URL`                                            | Public origin of the control-plane API (serves `/id/*`).                         |
| `PLATFORM_OPENAPI_URL`                                      | URL of the repo-hosted `openapi.json` to import. Defaults to the raw GitHub URL. |
| `MCP_RUNTIME_PUBLIC_URL`                                    | Public origin of the MCP runtime (serves `/mcp/:serverId`).                      |
| `PLATFORM_OAUTH_CLIENT_ID` / `PLATFORM_OAUTH_CLIENT_SECRET` | Credentials the OAuth flow uses against the platform identity provider.          |
| `PLATFORM_TOKEN_TTL_S`                                      | Lifetime (seconds) of issued platform access tokens. Defaults to 3600.           |

Every published server also advertises how agents can authenticate to it via the [auth.md](/guides/agent-auth-discovery.md) discovery protocol.