Available tools
The Port MCP Server exposes different sets of tools based on your role and use case. The tools you see will depend on your permissions in Port.
- Developer
- Builder
Developers are typically users who consume and interact with the software factory - querying services, running actions, and analyzing data. These tools help you get information and execute approved workflows.
Actions & workflows9 tools
get_action_permissionsGet permissions/approval config for actions. API Reference
get_workflow_runGet the status and details of a workflow run by its identifier. Use after trigger_run to poll for completion, or to inspect any previously-triggered run. Returns status, result, per-node execution details, and timestamps. API Reference
list_actionsList actions and automations in your organization. Without identifiers, returns a summary list. With identifiers, returns full action details including complete input schemas. Self-service workflow triggers are a separate concept - use
list_self_service_triggers to discover those. API Referencelist_self_service_triggersList self-service workflow triggers the caller can execute. Returns workflow metadata, the trigger nodeIdentifier, and the input schema for each trigger. Use before
trigger_run to discover available operations and required inputs. API Referencelist_workflowsList workflows in your organization. Without identifiers, returns a summary list. With identifiers, returns full workflow details including trigger configuration and node definitions. API Reference
run_actionDynamicExecute a self-service action or automation by identifier. Prefer
trigger_run when you want one tool that covers both workflow runs and action runs. API Referencesubmit_input_node_responseSubmit a response to a workflow input node that is waiting for input, on behalf of the current user. Get the workflow run and node run identifiers from the user, call
get_run and read the input node run's output.evaluatedConfig for the description, form, and buttons, then submit the chosen button and inputs. Only responders on the node can submit. API Referencetrack_action_runTrack action execution status. API Reference
trigger_runTrigger a self-service workflow or action run. For workflows, pass
type: "WORKFLOW", the workflow identifier, the nodeIdentifier from list_self_service_triggers, and inputs matching the trigger schema. For actions, pass type: "ACTION" and the action identifier. Returns the run identifier and status so you can track progress. API ReferenceAudit logs1 tool
search_audit_logsSearch entity audit logs using structured filters for status, operation, trigger origin, date, errors, and related resources. Supports limit and offset pagination, optional response fields, and filtering entities or blueprints by identifier. API Reference
Data model3 tools
list_blueprintsList blueprints in your organization. Without identifiers, returns a summary list. With identifiers, returns full blueprint details including property definitions, schemas, and enum values. API Reference
list_entitiesQuery entities from a blueprint with filtering, sorting, pagination, and
include. Supports identifiers, groupBy for value distribution, and countOnly for a total count. API ReferenceThe following are behaviors that are easy to miss and cause confusions:
- These are the available operators by property type:
- string/enum:
=,!=,in,notIn,contains,doesNotContains,beginsWith,endsWith,isEmpty,isNotEmpty - number/date:
=,!=,>,>=,<,<=,between,notBetween,isEmpty,isNotEmpty - array:
contains,containsAny,doesNotContains,isEmpty,isNotEmpty - boolean:
=,!=,isEmpty,isNotEmpty
- string/enum:
- The include parameter accepts mirror and calculation properties: Use mirror and calculation property identifiers in the include parameter to retrieve computed or inherited values alongside regular properties.
- Set membership with in/notIn operators: Use
inornotInwith an array value to filter enum/string properties by multiple values:{ "property": "status", "operator": "in", "value": ["active", "pending"] }. This avoids needing verbose nested "or" blocks for multi-value checks. - Empty arrays in filter operators:
in: []returns 0 results (no entity matches an empty set)notIn: []returns all results (every entity passes an empty exclusion list)
- Limit controls groups returned when using groupBy: When groupBy is active, limit controls the number of groups returned, not entities. For example, limit: 5 with groupBy returns at most 5 groups.
groupByincludes a null value group: Results always include a group with {"value": null} representing entities where the grouped property is not set.- The
=operator on array properties returns 0 results: Using the=operator on an array-type property returns 0 results. Use thecontainsoperator instead for array properties.
simulate_blueprint_permissionsSimulate blueprint entity permissions for a user. Use list mode to return entities the user can access for a blueprint; use detail mode with entityIdentifier to check permissions for a specific entity. API Reference
General5 tools
describe_user_detailsDescribe the user, which organization he is connected to and what teams he is a member of and more information regarding the user. Can be useful for questions that relate to the user or when looking up for related entities to the user API Reference
load_skillLoad specialized guidance for a domain-specific task. Skills provide step-by-step instructions for common workflows like troubleshooting integrations. Load a skill before starting a specialized task to ensure consistent, thorough handling. Documentation
search_port_knowledge_sourcesSearch the official Port documentation and return the most relevant sections from it for a user query. Each returned section includes the url and its actual content in markdown. Use this tool for all queries that require Port knowledge.
get_port_knowledge_documentsFetch full Port documentation pages by their exact source URL. Returns the complete page content in markdown, with pagination and truncation for long documents. Use when you need the full page rather than the short chunks returned by search_port_knowledge_sources.
give_port_feedbackReport documentation issues, product gaps, or MCP server problems to the Port team. Provide a message and category (mcp_server, documentation, product, or other). Use when you notice broken links, outdated docs, or other issues while using Port knowledge tools.
Pages & dashboards3 tools
get_pageBetaGet a specific page by identifier. Returns full page details including widgets configuration. For entity pages (type "entity"), returns a tabs array with each tab's title, widgets, layout, and reserved flag. API Reference
get_sidebarBetaGet the software catalog sidebar structure including all pages and folders. API Reference
load_widget_schemaBetaGet the JSON schema for a specific dashboard widget type. Call this before upsert_dashboard_page, upsert_widget, or update_entity_page to understand the required structure for the widget you want to create.
Scorecards1 tool
list_scorecardsList scorecards in your organization. Without identifiers, returns a summary list. With identifiers, returns full scorecard details including complete rule configurations. API Reference
Builders are platform engineers or admins who design and configure your Port environment - creating blueprints, setting up scorecards, and managing the overall structure. These tools help you build and maintain the factory.
Builders have access to all the tools available to Developers, plus additional management tools for creating and configuring the portal.
Actions & workflows14 tools
delete_actionDelete action by identifier. API Reference
delete_workflowDelete workflow by identifier. API Reference
get_action_permissionsGet permissions/approval config for actions. API Reference
get_workflow_runGet the status and details of a workflow run by its identifier. Use after trigger_run to poll for completion, or to inspect any previously-triggered run. Returns status, result, per-node execution details, and timestamps. API Reference
list_actionsList actions and automations in your organization. Without identifiers, returns a summary list. With identifiers, returns full action details including complete input schemas. Self-service workflow triggers are a separate concept - use
list_self_service_triggers to discover those. API Referencelist_self_service_triggersList self-service workflow triggers the caller can execute. Returns workflow metadata, the trigger nodeIdentifier, and the input schema for each trigger. Use before
trigger_run to discover available operations and required inputs. API Referencelist_workflowsList workflows in your organization. Without identifiers, returns a summary list. With identifiers, returns full workflow details including trigger configuration and node definitions. API Reference
run_actionDynamicExecute a self-service action or automation by identifier. Prefer
trigger_run when you want one tool that covers both workflow runs and action runs. API Referencesubmit_input_node_responseSubmit a response to a workflow input node that is waiting for input, on behalf of the current user. Get the workflow run and node run identifiers from the user, call
get_run and read the input node run's output.evaluatedConfig for the description, form, and buttons, then submit the chosen button and inputs. Only responders on the node can submit. API Referencetrack_action_runTrack action execution status. API Reference
trigger_runTrigger a self-service workflow or action run. For workflows, pass
type: "WORKFLOW", the workflow identifier, the nodeIdentifier from list_self_service_triggers, and inputs matching the trigger schema. For actions, pass type: "ACTION" and the action identifier. Returns the run identifier and status so you can track progress. API Referenceupdate_action_permissionsUpdate action permissions configuration. API Reference
upsert_actionCreate or update an action. Updates if the action exists, creates if it does not. API Reference links to create; updates use
change-an-action-automation. API Referenceupsert_workflowCreate or update a workflow. Updates if the workflow exists, creates if it does not. API Reference
Audit logs1 tool
search_audit_logsSearch entity audit logs using structured filters for status, operation, trigger origin, date, errors, and related resources. Supports limit and offset pagination, optional response fields, and filtering entities or blueprints by identifier. API Reference
Data model8 tools
delete_blueprintDelete blueprint and all its entities. API Reference
delete_entityDelete entity with optional dependents. API Reference
list_blueprintsList blueprints in your organization. Without identifiers, returns a summary list. With identifiers, returns full blueprint details including property definitions, schemas, and enum values. API Reference
list_entitiesQuery entities from a blueprint with filtering, sorting, pagination, and
include. Supports identifiers, groupBy for value distribution, and countOnly for a total count. API ReferenceThe following are behaviors that are easy to miss and cause confusions:
- These are the available operators by property type:
- string/enum:
=,!=,in,notIn,contains,doesNotContains,beginsWith,endsWith,isEmpty,isNotEmpty - number/date:
=,!=,>,>=,<,<=,between,notBetween,isEmpty,isNotEmpty - array:
contains,containsAny,doesNotContains,isEmpty,isNotEmpty - boolean:
=,!=,isEmpty,isNotEmpty
- string/enum:
- The include parameter accepts mirror and calculation properties: Use mirror and calculation property identifiers in the include parameter to retrieve computed or inherited values alongside regular properties.
- Set membership with in/notIn operators: Use
inornotInwith an array value to filter enum/string properties by multiple values:{ "property": "status", "operator": "in", "value": ["active", "pending"] }. This avoids needing verbose nested "or" blocks for multi-value checks. - Empty arrays in filter operators:
in: []returns 0 results (no entity matches an empty set)notIn: []returns all results (every entity passes an empty exclusion list)
- Limit controls groups returned when using groupBy: When groupBy is active, limit controls the number of groups returned, not entities. For example, limit: 5 with groupBy returns at most 5 groups.
groupByincludes a null value group: Results always include a group with {"value": null} representing entities where the grouped property is not set.- The
=operator on array properties returns 0 results: Using the=operator on an array-type property returns 0 results. Use thecontainsoperator instead for array properties.
simulate_blueprint_permissionsSimulate blueprint entity permissions for a user. Use list mode to return entities the user can access for a blueprint; use detail mode with entityIdentifier to check permissions for a specific entity. API Reference
trigger_auto_discoveryStart auto-discovery to suggest or find entities for a blueprint. Call list_blueprints first to obtain the exact blueprint identifier before invoking this tool. Supports optional user context and excluded blueprints as supported by the tool. API Reference
upsert_blueprintCreate or update a blueprint. Updates if the blueprint exists, creates if it does not. API Reference
upsert_entityCreate or update an entity. Updates if the entity exists, creates if it does not. Uses merge by default to preserve existing fields. API Reference
External interfaces3 tools
list_external_interface_appsList external interface apps registered for your organization (public clients using PKCE). Requires organization admin. Documentation
revoke_external_interface_appRevoke (permanently delete) an external interface app registration. Any UI built against it will immediately lose the ability to authenticate. Requires organization admin permissions. Documentation
upsert_external_interface_appCreate or update an external interface app (public/PKCE OAuth client, no client secret) for your organization, so you can build a custom UI against Port's API. Omit appId to create; pass appId to update. Requires organization admin permissions. Documentation
The following are behaviors that are easy to miss and cause confusions:
- Create vs update: Omit appId to create — name and redirectUris are both required. Pass appId to update — at least one of name or redirectUris must be provided. Use the app's id (not clientId) as appId.
- redirectUris replaces the full set: When updating, redirectUris replaces the entire existing set rather than merging with it. Pass the full list the app should end up with.
General5 tools
describe_user_detailsDescribe the user, which organization he is connected to and what teams he is a member of and more information regarding the user. Can be useful for questions that relate to the user or when looking up for related entities to the user API Reference
load_skillLoad specialized guidance for a domain-specific task. Skills provide step-by-step instructions for common workflows like troubleshooting integrations. Load a skill before starting a specialized task to ensure consistent, thorough handling. Documentation
search_port_knowledge_sourcesSearch the official Port documentation and return the most relevant sections from it for a user query. Each returned section includes the url and its actual content in markdown. Use this tool for all queries that require Port knowledge.
get_port_knowledge_documentsFetch full Port documentation pages by their exact source URL. Returns the complete page content in markdown, with pagination and truncation for long documents. Use when you need the full page rather than the short chunks returned by search_port_knowledge_sources.
give_port_feedbackReport documentation issues, product gaps, or MCP server problems to the Port team. Provide a message and category (mcp_server, documentation, product, or other). Use when you notice broken links, outdated docs, or other issues while using Port knowledge tools.
Integrations5 tools
get_integration_event_logsFetch event logs for an integration. Defaults to ERROR-level logs. Supports filters for levels, event_id, etl_phases, and kinds. Paginate with timestamp and log_id from the previous response. API Reference
get_integration_kinds_with_examplesFetch all kinds (data types) that an integration ingests, along with raw data examples for each kind. For example, a GitHub integration might have kinds like "pull_request", "issue", and "repo".
get_integration_sync_metricsFetch sync metrics for an integration. Returns detailed metrics including status, number of items handled in each phase of the integration pipeline (extract, transform, load, delete), and per-kind statistics. API Reference
list_integrationsList integrations in your organization. Without identifiers, returns a summary list. With identifiers, returns full integration details including complete config with mapping configuration. Empty result is authoritative: no integrations are installed. Do not infer prior installation from existing blueprints. API Reference
test_integration_mappingTest an integration mapping against raw data examples. Validates the mapping, checks for errors, and returns the mapped results or error messages.
Pages & dashboards15 tools
delete_sidebar_folderBetaDelete a folder from the sidebar. Pages and nested folders inside it are also deleted. API Reference
delete_widgetBetaDelete a widget from a dashboard, home, or entity page by its ID. API Reference
duplicate_pageBetaDuplicate a dashboard page. Creates an identical copy with the same widgets, layout, page filters, icon, and description. Only dashboard pages are supported; entity pages cannot be duplicated. API Reference
get_pageBetaGet a specific page by identifier. Returns full page details including widgets configuration. For entity pages (type "entity"), returns a tabs array with each tab's title, widgets, layout, and reserved flag. API Reference
get_sidebarBetaGet the software catalog sidebar structure including all pages and folders. API Reference
load_widget_schemaBetaGet the JSON schema for a specific dashboard widget type. Call this before upsert_dashboard_page, upsert_widget, or update_entity_page to understand the required structure for the widget you want to create.
move_pageBetaMove a page to a different location in the sidebar. Use "parent" to place the page inside a folder (or null for sidebar root) and "after" to control its position within that level. API Reference
update_entity_pageBetaUpdate an existing entity page's tabs, tab order, tab names, page metadata, or page filters. Entity pages are auto-generated per blueprint and cannot be created manually. Use upsert_widget to update a single widget on a tab. API Reference
The following are behaviors that are easy to miss and cause confusions:
- Entity page identifier format: Entity page identifier is "{blueprintIdentifier}Entity" (for example, "serviceEntity"). Call get_page first to see existing tabs.
- Prefer upsert_widget for single widget changes: Use upsert_widget with tabTitle when updating one widget instead of this tool.
- tabOrder controls tab order and deletion: Provide tabOrder with every remaining tab title in display order. Custom tabs omitted from tabOrder are deleted. Reserved tabs (Overview, Runs, Audit Log, Related Entities) cannot be removed.
- pageFilters uses replace-all semantics: When provided, pageFilters replaces the entire filter list. Omit to leave filters unchanged, or pass an empty array to clear all filters.
upsert_dashboard_pageBetaCreate or update a dashboard or home page with widgets, layout, and optional page filters. Do not use on entity pages; use update_entity_page or upsert_widget instead. The dashboard-widget container is auto-generated. Use load_widget_schema to get the schema for a specific widget type before building widgets. API Reference
The following are behaviors that are easy to miss and cause confusions:
- pageFilters uses replace-all semantics: When provided, pageFilters replaces the entire filter list. Omit to leave filters unchanged, or pass an empty array to clear all filters. Call get_page first to see existing filters.
upsert_sidebar_folderBetaCreate or update a folder in the sidebar. Folders can be nested by specifying a parent folder identifier. Use "after" to control position. API Reference
upsert_widgetBetaCreate or update a single widget on a dashboard, home, or entity page. Preferred for updating one widget instead of update_entity_page. For entity pages, tabTitle is required — call get_page first to see available tabs. Call load_widget_schema first to get the full schema for the target widget type. API Reference
list_pluginsList plugins uploaded to your organization (Port admin permissions required). Without identifiers, returns a summary list. With identifiers, returns full plugin details including metadata and custom parameters used by custom widgets. API Reference
list_available_library_pluginsList plugins in the Port Plugins library - the curated catalog from the public port-plugins repository. Each entry includes readmeContent with catalog prerequisites. Call load_skill("list-available-library-plugins") to browse, or load_skill("install-plugin-library") before install flows. Not the same as list_plugins (already installed in your org). Documentation
install_library_pluginInstall a plugin from the Port Plugins library into your organization. Load install-plugin-library via load_skill first, read readmeContent from list_available_library_plugins, verify catalog prerequisites with list_blueprints, confirm missing properties with the user, then upsert_blueprint if needed before calling this tool. Returns alreadyInstalled: true if the plugin is already in your org. Do not use install_integrations for library plugins. API Reference Documentation
The following are behaviors that are easy to miss and cause confusions:
- Required install order: 1. load_skill({ name: "install-plugin-library" }). 2. list_available_library_plugins - read readmeContent. 3. list_blueprints - check Prerequisites and Catalog. 4. Confirm missing properties with the user and wait for their answer. 5. upsert_blueprint when catalog setup is confirmed - copy property schemas verbatim from README JSON. 6. install_library_plugin.
upsert_pluginCreate or update a plugin for custom widgets (Port admin permissions required). Updates if the plugin identifier exists, creates if it does not. Use after you have a built plugin artifact and metadata (for example identifier, title, optional params). Not for Plugins library widgets - use install_library_plugin for those. Documentation
Scorecards3 tools
delete_scorecardDelete scorecard by identifiers. API Reference
list_scorecardsList scorecards in your organization. Without identifiers, returns a summary list. With identifiers, returns full scorecard details including complete rule configurations. API Reference
upsert_scorecardCreate or update a scorecard. Updates if the scorecard exists, creates if it does not. API Reference
Client Support
Tool support in external MCP clients depends on whether the client implements the tools feature according to the MCP specification. Most MCP clients support tools. Check the MCP client documentation to see which features your client supports.
Select which tools to use
By default, when you open a chat with Port MCP, all available tools (based on your permissions) are loaded and ready to use. However, you can customize which tools are available if you want to focus on specific workflows.
For example, if you only want to query data from Port without building or modifying anything, you can limit the tools to just the read-only ones. This helps reduce complexity and ensures you don't accidentally make changes.
Using headers to control tool availability
You can use headers when configuring your MCP server connection to control which tools are available:
Read-only mode - The x-read-only-mode header controls whether write tools are available. Set it to 1 to restrict the MCP server to only expose read-only tools, completely hiding write tools from the available tools list. Set it to 0 (default) to allow all tools based on your permissions.
Control actions - The x-allowed-actions-to-run header controls which actions are available through the run_action tool. This header accepts a comma-separated list of action identifiers. Only the specified actions will be available. If the header is not specified, all actions you have permission to run will be available. If set to an empty string, no actions will be allowed to run.
Examples:
x-allowed-actions-to-run: "create_github_issue,create_incident"- Allows only the specified GitHub and incident actions.x-allowed-actions-to-run: "create_service,deploy_to_production"- Allows only the specified deployment actions.x-allowed-actions-to-run: ""- No actions will be allowed to run.
See the token-based authentication guide for examples of how to configure these headers.
Using client UI to select tools
- Cursor
- VSCode
- Claude
In Cursor, you can customize which tools are available through the UI after connecting to Port MCP. Once connected, you can select specific tools as shown below.
In VSCode, you can choose the tools through the UI after connecting to Port MCP.
When creating a custom connector in Claude, you can specify exactly which tools to expose instead of enabling everything.
Refer to the Claude custom connector documentation for detailed instructions.