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.

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

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

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

5. 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>")

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

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