Pipefy Portal Setup

Portal setup

Configure an organization's Pipefy portal: bootstrap the main hub, add pages and widgets, wire and publish sub-portals. 20 MCP tools (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 skills/pipes-and-cards/, skills/automations/.
• Raw GraphQL when a portal tool exists — prefer the tools below.
• Bootstrapping a portal via undocumented createInterface GraphQL — always use create_portal / pipefy portal create.

Prerequisites

• Organization id: UUID or numeric org id from pipefy org get / 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).
• Cursor MCP: after changing PIPEFY_* in .env, restart the MCP server so tools pick up the new credentials.

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

   MCP:

   list_portals organization_uuid="123456789"
   

   Expect at most one main portal row. If none:

   MCP:

   create_portal organization_uuid="123456789"
   

   CLI:

   pipefy portal list --organization-uuid 123456789
   pipefy portal create --organization-uuid 123456789
   

   Capture uuid where subType is the main portal.

2. Inspect structure

   MCP:

   get_portal portal_uuid="<MAIN_PORTAL_UUID>"
   

   CLI:

   pipefy portal get <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)

   MCP:

   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.

   CLI:

   pipefy portal element create --page-id <PAGE_ID> --type forms \
     --metadata '{"name":"Request access","gridMap":{"height":66,"columns":4,"minColumns":4}}'
   

4. Create a sub-portal

   MCP:

   create_sub_portal main_portal_uuid="<MAIN_PORTAL_UUID>" name="Partner hub"
   

   CLI:

   pipefy portal sub-portal create --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

   MCP:

   publish_sub_portal portal_uuid="<MAIN_PORTAL_UUID>" element_id="<FORMS_ELEMENT_ID>" sub_portal_uuid="<SUB_PORTAL_UUID>"
   

   CLI:

   pipefy portal sub-portal publish <MAIN_PORTAL_UUID> <FORMS_ELEMENT_ID> <SUB_PORTAL_UUID>
   

6. Verify publish state

   MCP:

   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

   MCP:

   update_portal portal_uuid="<MAIN_PORTAL_UUID>" visibility="public"
   

   CLI:

   pipefy portal update <MAIN_PORTAL_UUID> --visibility public
   

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. delete_portal_page with MCP two-step (confirmation_token from the preview, then confirm=true), or CLI --yes.

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 layout from get_portal for that page and send the full array back with intentional edits. Never invent { "rows": [ ... ] } stubs.

sort_portal_pages: pass a non-empty page_ids list with no duplicates. If the raw response exposes nested success: false, treat the operation as failed even when the MCP envelope looks ambiguous.

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

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

Two-step destructive deletes

MCP deletes (delete_portal, delete_portal_page, delete_portal_element, delete_sub_portal, delete_sub_portal_element) return a preview with confirmation_token. Echo that token with confirm=true on the second call. CLI uses --yes. unpublish_sub_portal is not gated.

Steps — unpublish or remove sub-portal

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

MCP:

unpublish_sub_portal portal_uuid="<MAIN_PORTAL_UUID>" element_id="<FORMS_ELEMENT_ID>"

CLI:

pipefy portal sub-portal unpublish <MAIN_PORTAL_UUID> <FORMS_ELEMENT_ID>

Detach element wiring (destructive: MCP two-step with confirmation_token, --yes on CLI):

MCP:

delete_sub_portal_element portal_uuid="<MAIN_PORTAL_UUID>" element_id="<FORMS_ELEMENT_ID>" confirm=false

Then after approval, echo the preview's confirmation_token:

delete_sub_portal_element portal_uuid="<MAIN_PORTAL_UUID>" element_id="<FORMS_ELEMENT_ID>" confirm=true confirmation_token="<token from preview>"

CLI:

pipefy portal sub-portal detach <MAIN_PORTAL_UUID> <FORMS_ELEMENT_ID> --yes

Delete sub-portal interface (irreversible):

MCP two-step delete_sub_portal (echo confirmation_token) / CLI:

pipefy portal sub-portal delete <SUB_PORTAL_UUID> --yes

MCP response shape

• Read tools return { success: true, data: { ... } } when PIPEFY_MCP_UNIFIED_ENVELOPE is enabled (default). Parse data for portals, pages, subPortals, etc.
• GraphQL/transport failures → { success: false, error: { message: "..." } } — do not treat transport errors as success.
• PERMISSION_DENIED on portal tools usually names create_portal or manage_portals. Re-check org id, token, and SA joinAsAdmin (see Confirm access).
• Only PERMISSION_DENIED is rewritten to the portal permission hint; other GraphQL codes surface as generic errors with the API message.
• Destructive deletes: default confirm=false returns a preview (requires_confirmation: true, confirmation_token); call again with confirm=true and that token only after explicit human approval.

CLI --json prints the raw SDK payload (no success wrapper).

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
• skills/introspection/pipefy-introspection/SKILL.md — verify Interfaces / internal_api mutations before changing tools