pipefy-portal-setup

Portal setup

MCP clients: read references/mcp.md. CLI users: read references/cli.md. Examples below describe shared operation arguments.

Configure an organization's Pipefy portal: bootstrap the main hub, add pages and widgets, wire and publish sub-portals (Interfaces GraphQL + internal_api for sub-portal wiring).

Deep reference: `docs/mcp/tools/portal.md`. Parity matrix: `docs/parity.md`. Env vars: `docs/config.md`.

When to use

• "Create our company portal", "list portals for org X", "publish a sub-portal".
• Add or change portal pages, layout, or page elements (forms, link, etc.).
• Attach, publish, unpublish, or delete sub-portals on the main portal.

Do not use for:

• Pipes, phases, cards, or automations — see pipefy-pipes-and-cards, pipefy-automations.
• Raw GraphQL when a portal tool exists — prefer the tools below.
• Bootstrapping a portal via undocumented createInterface GraphQL — always use `create_portal`.

Prerequisites

• Organization id: UUID or numeric org id from the organization lookup or the Pipefy URL (examples below use fictional 123456789 per `fixture_ids.py`). SDK resolves numeric ids before Interfaces calls. The org you pass to `list_portals` / `create_portal` must be the same org your token can write on.
• Portal writes: token needs `create_portal` and/or `manage_portals` on that org. Many service accounts only have pipe/card scope on their default org → PERMISSION_DENIED on portal mutations even when reads succeed elsewhere.
• One main portal per org — create_portal is idempotent (second call returns the same portal UUID).

Confirm access before writes

Reads on the wrong org can succeed while Interfaces writes fail. Before page/element/sub-portal mutations:

1. Call `list_portals` with the intended organization_uuid.
2. Ensure the token is meant for that org (service account email vs human user on a different org is a common mismatch).
3. Prefer an org where the account has `manage_portals` and portal admin in Pipefy (not only canManagePortals on a read query from another org).

If `update_portal` or `delete_portal` returns PERMISSION_DENIED but the user insists the org role is correct: Pipefy may require `joinAsAdmin` on that portal interface for service accounts (Interfaces mutation, not shipped as MCP/CLI). The user must join as portal admin once in the UI (or via GraphQL) per portal UUID before SA writes succeed.

How portals are organized

Main portal lifecycle

• Prefer `update_portal` on an existing main portal over delete + `create_portal` on orgs you reuse for testing.
• `delete_portal` on the main removes one interface UUID; orphan sub-portals can remain unless deleted first.
• After deleting the main, `create_portal` may fail with `Menu already created` (org menu state persists while mainPortal is null). Recovery: delete orphan sub-portals, use Pipefy admin/support, or bootstrap content on the surviving UUID — do not switch to raw `createInterface`, which leaves a skeleton main page ("Page", 0 elements) and a broken builder; idempotent `create_portal` will keep returning that UUID.

Empty main page

If `get_portal` shows a main page with no elements, call `create_portal_page` with `title` only (no elements in the request). The API typically returns a page with ~14 templated widgets (text, forms, links, etc.). Use that page for publish slots and element tests. Do not pass type: subPortal inside `create_portal_page` — validation fails at create time.

Schema notes

Tools needed

Element type values (15): text, table, field, embedLink, embedVideo, embedImage, button, divider, link, forms, pages, subPortal, automationButton, contentBlock, document.

Steps — happy path (main portal + sub-portal publish)

1. List or bootstrap the main portal

Operation arguments:

   list_portals(organization_uuid="123456789")

Expect at most one main portal row. If none:

Operation arguments:

   create_portal(organization_uuid="123456789")

Capture uuid where subType is the main portal.

1. Inspect structure

Operation arguments:

   get_portal(portal_uuid="<MAIN_PORTAL_UUID>")

Note pages[], elements[], and `forms` element ids. If the main page has zero elements, run `create_portal_page` (title only) on that portal before adding widgets.

1. Optional — add a `forms` element (if no templated forms slot exists)

Operation arguments:

   create_portal_element(page_id="<PAGE_ID>", type="forms", metadata={"name": "Request access", "gridMap": {"height": 66, "columns": 4, "minColumns": 4}})

If `create_portal_element` returns an opaque or INTERNAL_SERVER_ERROR from Interfaces, `duplicate_portal_element` from an existing link on the same portal_uuid and page_id instead of retrying create blindly.

1. Create a sub-portal

Operation arguments:

   create_sub_portal(main_portal_uuid="<MAIN_PORTAL_UUID>", name="Partner hub")

Capture the sub-portal uuid. `get_portal` will list it under `subPortals[]` with `published: false` — the main hub UI is unchanged until step 5.

1. Publish on a `forms` element

Operation arguments:

   publish_sub_portal(portal_uuid="<MAIN_PORTAL_UUID>", element_id="<FORMS_ELEMENT_ID>", sub_portal_uuid="<SUB_PORTAL_UUID>")

1. Verify publish state

Operation arguments:

   get_portal(portal_uuid="<MAIN_PORTAL_UUID>")

Success: target `subPortals[].published` is `true`. End users can see the sub-portal only after this (and hub visibility rules).

1. Optional — make the main hub public

Update <MAIN_PORTAL_UUID> with visibility="public" through update_portal (SDK argument: interface_uuid; MCP argument: portal_uuid).

Steps — pages, layout, and safe edits

Use a disposable page for element/layout experiments on a shared org main portal:

1. `create_portal_page` with a unique title (e.g. Agent smoke 2026-06-01).
2. Run `create_portal_element`, `update_portal_element`, `duplicate_portal_element`, `update_portal_page_layout` on that page only.
3. Review and approve deletion of the disposable page, then use delete_portal_page.

`duplicate_portal_element`: element_id, portal_uuid, and page_id must refer to the same page that already contains the source element (duplicate on the same page, not cross-page).

`update_portal_page_layout`: read the target pages[].layout from `get_portal` and preserve its row IDs, child element UUIDs, and unaffected rows. Send the complete array with only the intended order/grouping changes; then re-read and compare. elements[].metadata.gridMap (height, columns, minColumns) describes dimensions, so it cannot reconstruct row order or grouping. Preserve the full metadata when resizing an element. If the layout is unavailable, stop the positional edit instead of guessing. Never wrap the array in { "rows": [ ... ] }.

MCP:

get_portal portal_uuid="<portal_uuid>"
update_portal_page_layout page_id="<page_uuid>" layout=[<complete edited rows from that page>]
get_portal portal_uuid="<portal_uuid>"

CLI:

pipefy portal get <portal_uuid> --json
pipefy portal page layout update --page-id <page_uuid> --layout '[<complete edited rows from that page>]' --json
pipefy portal get <portal_uuid> --json

`create_portal_element` with placement: read pages[].layout, generate a UUID for element_id, append or insert a row { "id": "<new row uuid>", "type": "row", "children": ["<element_id>"] }, and pass both element_id and the complete layout. Without layout the element is created but stays off the grid. Re-read and compare.

MCP:

create_portal_element page_id="<page_uuid>" type="link" metadata={...} element_id="<element_id>" layout=[<existing rows>, {"id": "<row uuid>", "type": "row", "children": ["<element_id>"]}]

CLI:

pipefy portal element create --page-id <page_uuid> --type link --metadata '{...}' --element-id <element_id> --layout '[<existing rows>, {"id": "<row uuid>", "type": "row", "children": ["<element_id>"]}]' --json

`delete_portal_element` with pruning: read pages[].layout, remove element_id from every row's children, and pass the complete array as layout. The grid and the element change in one call, so no row is left pointing at a deleted element. A layout that still lists element_id is rejected. Re-read and compare. The MCP and CLI references show the delete call with layout.

`sort_portal_pages`: pass a non-empty page_ids list with no duplicates. If the response exposes nested success: false, treat the operation as failed.

Link element metadata (create/update, full replace):

{
  "gridMap": { "height": 64, "columns": 4, "minColumns": 4 },
  "linkUrl": "https://example.com",
  "linkName": "Example link"
}

A link has no bindings, so its update also passes data_sources: [] (CLI --data-sources '[]').

Steps — unpublish or remove sub-portal

Unpublish (keeps sub-portal entity; visitors lose access):

Operation arguments:

unpublish_sub_portal(portal_uuid="<MAIN_PORTAL_UUID>", element_id="<FORMS_ELEMENT_ID>")

Detach element wiring with delete_sub_portal_element after reviewing the impact and obtaining approval.

Delete sub-portal interface with delete_sub_portal (irreversible); review and approve before deletion.

Success criteria

• list_portals returns the org main portal (typically one row); create_portal returns the same UUID on repeat.
• get_portal shows expected pages / elements after writes.
• After `create_sub_portal`, sub-portal exists in API but `published: false` until publish.
• After publish: `subPortals[].published` is true and the main page shows the wired `forms` slot.
• After unpublish: `published` is false without deleting the sub-portal entity (unless you called delete_sub_portal).
• After layout/element edits on a disposable page, main portal pages used in production still open in the builder (no HTTP 500).

Failure modes

See also

• `docs/mcp/tools/portal.md` — endpoints, wire naming, maintainer introspection
• pipefy-introspection — verify Interfaces / internal_api mutations before changing tools