Help us improve
Share bugs, ideas, or general feedback.
From Pipefy
Discovers GraphQL type shapes, mutation signatures, enum values, and executes arbitrary GraphQL queries as a fallback when dedicated MCP tools fail.
npx claudepluginhub pipefy/ai-toolkit --plugin pipefyHow this skill is triggered — by the user, by Claude, or both
Slash command
/pipefy:pipefy-introspectionThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Schema discovery, organization info, and a fallback executor. **6 MCP tools.**
Read, create, update, and delete Pipefy pipes, phases, fields, labels, cards, comments, and field conditions via 37 MCP tools.
Discovers GraphQL schemas via introspection, constructs queries and mutations, and executes them from the command line using gh api or curl, with jq-based response parsing.
Automates Grafbase operations via Composio's Grafbase toolkit through Rube MCP. Discovers tools, manages connections, and executes workflows.
Share bugs, ideas, or general feedback.
Schema discovery, organization info, and a fallback executor. 6 MCP tools.
This is Tier 2 in the resolution strategy: when a dedicated MCP tool fails or doesn't exist, use introspection to understand the API, then execute_graphql to run the operation directly.
Tier 1: dedicated MCP tool exists — use it.
Tier 2: use introspection + execute_graphql (this skill).
Tier 3: direct curl/httpx fallback — see skills/api-troubleshoot/pipefy-api-fallback/SKILL.md.
| Tool (MCP) | CLI | Read-only | Purpose |
|---|---|---|---|
introspect_type | pipefy introspect type | Yes | Type shape: fields, inputFields, enumValues. Optional max_depth. |
introspect_query | pipefy introspect query | Yes | Root query arguments and return type. Optional max_depth. |
introspect_mutation | pipefy introspect mutation | Yes | Root mutation arguments and return type. Optional max_depth. |
search_schema | pipefy introspect schema search | Yes | Keyword search on type names/descriptions. Optional kind filter. |
execute_graphql | pipefy graphql exec | No | Execute arbitrary GraphQL (--yes required for mutations). |
get_organization | pipefy org get | Yes | Load organization info (name, plan, UUID, member count, pipe count). |
include_parsed flagexecute_graphql, introspect_type, introspect_mutation, introspect_query, and get_organization all accept an optional include_parsed: bool (default false).
false): response is { success, result } where result is the raw GraphQL JSON as a string.true: response includes both result (the raw JSON string) AND data (the parsed dict). Drill into data programmatically; keep result to forward verbatim.Use include_parsed=true whenever you plan to read nested fields (e.g. iterating over phases[].fields[]). Leave it off for one-shot reads where the raw string is sufficient.
max_depth (introspect_type / query / mutation)MCP tools accept max_depth (default 1). CLI: --max-depth.
1 — type/field info only (no inlined sub-types).2+ — resolves referenced input/output types inline (resolvedType), so one call can replace introspecting the mutation then each input type separately.Example (CLI):
pipefy introspect mutation createCard --max-depth 2 --json
Example (MCP):
introspect_mutation mutation_name="createCard" max_depth=2 include_parsed=true
Scalars (ID, String, Int, …) are never expanded.
kind on search_schemaOptional filter: OBJECT, INPUT_OBJECT, ENUM, SCALAR, INTERFACE, UNION.
search_schema keyword="automation" kind="INPUT_OBJECT"
pipefy introspect schema search automation --kind INPUT_OBJECT --json
introspect_type('CreatePhaseFieldInput') to discover valid type enum values.extra_input: introspect the corresponding input type to find optional keys.introspect_mutation('createSomething') before execute_graphql.search_schema('automation') to find related types and inputs.execute_graphqlpipe(id: $id) { organization { uuid } }.Always prefer dedicated MCP tools — they validate inputs, handle pagination, and format errors consistently. execute_graphql is the fallback when dedicated tools can't solve the problem.
Search for the mutation by keyword:
search_schema keyword="label"
Get the full mutation signature:
introspect_mutation mutation_name="createLabel"
Discover input type fields:
introspect_type type_name="CreateLabelInput"
Execute the mutation (CLI):
pipefy graphql exec --query "mutation …" --vars '{"input":{…}}' --yes --json
Mutations: the CLI exits with code 2 unless
--yesis passed (guardrail for agents and scripts).
Execute the mutation (MCP):
execute_graphql query="mutation CreateLabel($input: CreateLabelInput!) { createLabel(input: $input) { label { id name } } }" variables='{"input": {"pipe_id": 67890, "name": "Urgent", "color": "#FF0000"}}'
Ready-to-use patterns for situations where dedicated tools are insufficient.
create_phase_fieldintrospect_type('CreatePhaseFieldInput')
Look for the type field; it references an enum. Introspect the enum to get all valid values.
get_ai_agent returns behavior headers only. To inspect the full config (event_params, actionParams, actionsAttributes):
execute_graphql query='query($uuid: ID!) { aiAgent(uuid: $uuid) { uuid name instruction behaviors { id name active event_id event_params { to_phase_id triggerFieldIds fromPhaseId } action_params { aiBehaviorParams { instruction referencedFieldIds actionsAttributes { name actionType referenceId metadata { destinationPhaseId pipeId fieldsAttributes { fieldId inputMode value } } } } } } } }' variables='{"uuid":"<agent-uuid>"}'
find_cards)find_cards only searches custom field values. To search by title:
execute_graphql query='query($pipeId: ID!, $first: Int) { cards(pipe_id: $pipeId, first: $first) { edges { node { id title current_phase { name } } } } }' variables='{"pipeId":"<pipe-id>","first":50}'
Filter by title client-side. For large pipes, paginate with after.
extra_input accepts for any mutationWhen a tool accepts extra_input (e.g. create_automation, update_label), discover all optional keys:
introspect_mutation('createAutomation') # find the input type name
introspect_type('CreateAutomationInput') # see all inputFields
Compare with the tool's primary arguments to know which keys are additive via extra_input.
Several tools need organization_id but the user only has a pipe ID:
execute_graphql query='query($id: ID!) { pipe(id: $id) { organization { id uuid name } } }' variables='{"id":"<pipe-id>"}'
create_phase_field does not accept options. Create first, then update:
execute_graphql query='mutation($id: ID!, $options: [String!]) { updatePhaseField(input: { id: $id, options: $options }) { phase_field { id label options } } }' variables='{"id":"<field-id>","options":["High","Medium","Low"]}'
When move_card_to_phase fails with "not a valid target phase":
execute_graphql query='query($id: ID!) { phase(id: $id) { id name cards_can_be_moved_to_phases { id name } } }' variables='{"id":"<current-phase-id>"}'
Returns the valid destination phases from the current phase.
For long-running agent sessions, the MCP can reuse the fetched GraphQL schema across requests instead of re-introspecting on every call. Enable via the gql_reuse_fetched_graphql_schema setting (env or settings file). Off by default. After a breaking Pipefy schema change, the process must be restarted to pick up the new schema. Single-session agents rarely benefit — leave it off unless you measure real improvement.
introspect_type returns the complete field list for the input type.execute_graphql returns the expected data without errors.introspect_type returns null — type name is case-sensitive; try PascalCase (e.g., CreateLabelInput, not create_label_input).search_schema returns many hits — case-insensitive substring matching; broad keywords like "card" flood results. Prefer specific names like "AiAgent", "FieldCondition".introspect_mutation is expensive — fetches all root mutation fields and filters client-side (single large query). Prefer introspect_type on the specific input type when you already know the mutation name.execute_graphql returns GraphQL errors — check path and message; pass debug=true on the next call to surface the correlation_id.app.pipefy.com/graphql; real operations use api.pipefy.com/graphql. The MCP server handles this automatically; raw-API users must distinguish (see api-fallback).execute_graphql.execute_graphql).