MCP connectors — flowwork docs

Import any MCP server as a flowwork connector. Its tools become connector operations you call from a connector() step, with no per-tool limit. Add --dry-run to any import to preview the generated manifest before registering.

Pro feature

MCP (and CLI) connector import requires a Pro license. The HTTP and LLM connectors are available on every tier.

Import a remote MCP server (HTTP)

Remote servers need no process to spawn — just a URL and (usually) an auth header. Secrets are referenced as placeholders and supplied per workspace later:

flowctl mcp import --name ctx7 --transport http --url https://mcp.example/sse \
    --header 'Authorization=Bearer ${credentials.token}' --secret token

Import a local MCP server (stdio)

A stdio server is spawned as a child process, so process adapters must be enabled first:

export FLOWWORK_CONNECTOR_ALLOW_PROCESS=true
flowctl mcp import --name neon --secret-env NEON_API_KEY -- \
    docker run -i --rm -e NEON_API_KEY mcp/neon

Process adapters are off by default

Spawning a stdio server runs arbitrary code on the engine host, so it’s gated behind FLOWWORK_CONNECTOR_ALLOW_PROCESS=true (default off). Remote —transport http servers don’t spawn anything and are always allowed.

Create an instance and call it

Importing builds the manifest; a per-workspace instance holds the actual credentials. Then reference the connection + instance from a connector() step:

flowctl conn ops neon                                # list the imported operations
flowctl conn schema neon run_sql                     # request/response shape for an operation
flowctl instance create neon --name prod --credentials '{"NEON_API_KEY":"napi_..."}'

connector("query_db", {
  connection: "neon",
  instance: "prod",
  operation: "run_sql",
  requestMapper: (ctx) => ({ params: { sql: "select count(*) from orders" } }),
  responseCombiner: (ctx, response) => ({ rows: response }),
  next: "summarize",
});

Confirm the tool's argument shape

MCP tools often nest their arguments (e.g. Neon wraps fields under a required params object). The exact request/response schema comes from flowctl conn schema <connection> <operation> — author your requestMapper to match it precisely.

A few servers known to work

Server	Transport	Notes
Neon	remote HTTP	`list_projects`, `run_sql`, `get_connection_string`, …
GitHub	stdio (Docker)	issues, pull requests, repos, search
Filesystem	stdio (npx)	`read_file`, `write_file`, `list_directory`, `move_file`
Postgres	stdio (npx)	`query`, schema introspection
Fetch	stdio (uvx)	`fetch` (URL → markdown/text)
Brave Search	stdio (npx)	`brave_web_search`, `brave_local_search`
Slack	stdio (npx)	list channels, post message, replies, reactions

Debugging imports and calls

Set FLOWWORK_CONNECTOR_DEBUG=true on the engine host to log the launch command (with secrets masked), the JSON-RPC wire exchange, the child process’s stderr, and any request-schema validation failures with the offending payload. A common symptom — a 401 with the credential showing len=0 — means the instance’s credential key doesn’t match the manifest placeholder; recreate the instance with the right key.

Integrating your own application

Two ways to make your own app callable from a workflow:

Write an MCP server that exposes your app’s features as tools, then flowctl mcp import it. Best when you want a typed, self-describing surface reusable across agents and workflows.
Wrap your app as a CLI that emits JSON and register it with flowctl cli import — the fastest path for an app you already drive from the shell.

CLI import

The CLI connector adapter is designed on the same process substrate as stdio MCP, but is not shipped yet — use the MCP path today.