Tools and approvals

You can control which tools Port AI may use, whether those tools pause for approval, and which MCP connectors are attached to a request. These options apply to /v1/ai/invoke and, where noted, to agent invoke requests.

For the invoke request shape and streaming response, see API interaction. For the UI in the side chat, see Port AI Assistant.

Chat modes

Port AI supports chat modes that control which tools are available during an interaction. In the Port AI Assistant side chat, you select a mode from the UI. In API requests, pass the chatMode field in the invoke request body.

Mode	Tool availability	Typical use
ask	Read-only Port tools (get_*, list_*, search_*, and similar) plus run_action and trigger_auto_discovery. Write tools are excluded.	Explore data and configuration without edits.
plan	Full tool set (minus disabled tools), including plan-specific tools for multi-step analysis.	Bigger changes that require deeper analysis across multiple components.
build	Full tool set (minus disabled tools).	Scoped changes in your environment.

Chat mode controls which tools exist, not whether they pause for approval. In ask mode, write tools never appear regardless of your automate settings. In plan and build modes, your per-tool approval preferences apply. See tool approval.

Tool execution modes

For action execution tools specifically, Port AI supports two execution modes:

Automatic execution

When configured for automatic execution, Port AI will:

1. Determine the appropriate parameters based on your request.
2. Execute actions immediately.
3. Provide a link to the action run or results.

This mode streamlines workflows but should be used carefully, especially for actions with significant impact.

Manual approval

When configured for manual approval, Port AI will:

1. Create a draft action based on your request.
2. Provide a link to the draft.
3. Allow you to review and modify parameters before execution.

This approach provides an additional safety layer, ensuring you can verify all parameters before execution.

Execution modes scope

Execution modes apply at the API and agent level. They mainly control how run_action executes Port self-service actions (automatically vs. as a manual draft). In the Port AI Assistant side chat, executionMode is not sent, so per-tool approval settings drive the pause-and-approve flow instead.

Tool approval

Port AI has two mechanisms that control how tools run. They are easy to conflate but serve different purposes:

Layer	What it controls	Where it lives
Per-tool approval settings	Whether a specific tool pauses for user confirmation before it runs	User preferences via the tool approval preferences API, or the side chat + menu
Execution mode (Automatic / Approval Required)	API and agent-level behavior, mainly how run_action runs Port self-service actions	Agent entity or API request body

Per-tool approval options

Each tool supports one of three states:

1. approval - the model can use the tool, but execution pauses until the user approves, edits arguments, or rejects the call.
2. automatic - the tool runs without pausing.
3. Disabled - the tool is removed from the model's tool list entirely.

Default behavior when no custom preference exists:

• Port read-only tools (get_*, list_*, and similar, plus run_action): automatic.
• Port write tools (create, update, delete, and similar): approval.
• External MCP tools: approval.

Approval resolution priority

The effective approval mode for a tool is resolved using the following priority (highest to lowest):

1. Per-invocation override - the toolApprovalOverrides field in the invoke request body. This takes the highest priority and can set any tool to automatic or approval for that single invocation.
2. Persistent preferences - the user's saved preferences via the tool approval preferences API. These apply to all invocations unless overridden by the request body.
3. Read-only annotation - if the tool's MCP annotation marks it as read-only (readOnlyHint: true), it defaults to automatic. All other tools default to approval.

Execution mode override

When executionMode is set to Automatic in the request body, per-tool user preferences are skipped for the approval-pause flow and all tools run automatically.

Runtime flow

When Port AI processes a request:

1. The backend loads saved preferences and builds the tool list (disabled tools are filtered out).
2. The model selects tools for the request.
3. For each tool call, the backend checks whether approval is required based on the resolution priority above.
4. If any tool needs approval, the stream pauses and the client displays a tool approval prompt.
5. The user approves, declines, or edits arguments, and the client resumes the invocation via toolApprovals on the next request.

Tools set to automatic in the same batch still run immediately. Only approval-mode tools block the turn.

Continuing a paused invocation

When a tool call requires approval, the stream pauses. To resume, send a follow-up request with toolApprovals instead of userPrompt. Each entry requires a toolCallId and an action of approve, approve_with_edit, or reject. Use editedArguments when the action is approve_with_edit, and optionally include rejectionReason when rejecting.

See the toolApprovals field in General-purpose AI interactions.

toolApprovals example (click to expand)

{
  "toolApprovals": [
    {
      "toolCallId": "call_0",
      "action": "approve"
    },
    {
      "toolCallId": "call_1",
      "action": "approve_with_edit",
      "editedArguments": {
        "blueprintIdentifier": "service",
        "identifier": "payment-service"
      }
    },
    {
      "toolCallId": "call_2",
      "action": "reject",
      "rejectionReason": "Not the right service"
    }
  ]
}

Tool approval in API requests

Per-invocation overrides take the highest priority and apply only to that single request. Persistent preferences apply to all future invocations unless overridden by toolApprovalOverrides in the request body. You can also disable specific tools through disabledTools in the preferences API. Disabled tools are excluded from all invocations unless the request includes an explicit tools array, which takes full control of tool availability.

For request fields, see:

• toolApprovalOverrides - General-purpose AI interactions.
• Persistent preferences - Get tool approval preferences and Update tool approval preferences.

toolApprovalOverrides example (click to expand)

{
  "userPrompt": "Deploy service X to production",
  "tools": [".*"],
  "toolApprovalOverrides": {
    "run_action": "approval",
    "list_.*": "automatic"
  }
}

Update tool approval preferences example (click to expand)

{
  "toolOverrides": {
    "run_action": "approval",
    "list_entities": "automatic"
  },
  "disabledTools": ["delete_entity"]
}

Side chat vs. agents and API

• Side chat uses per-tool approval preferences from the + menu. executionMode is not sent, so your saved settings drive the pause-and-approve flow. See tool approval settings in the Port AI Assistant.
• AI agents use execution_mode on the agent entity (Automatic vs. Approval Required), or tool_approval_overrides if configured. Agent chat views show tool settings as read-only.
• API callers can pass executionMode or toolApprovalOverrides. When executionMode is set, per-tool user preferences are skipped for the approval-pause flow.

Tool selection

Port AI allows you to control which specific tools from the Port MCP server are available for each API interaction. This provides fine-grained control over what actions Port AI can perform, enabling you to create secure, purpose-specific AI interactions.

Controlling which tools are available

You can restrict which tools Port AI is allowed to use. For example, you can limit an interaction to read-only tools for simple Q&A, or allow only specific actions for automated workflows.

• Per-invocation: Pass the tools array in the invoke request body with regex patterns that match tool names. Only matching tools will be available for that invocation.
• Persistent preferences: Use the tool approval preferences API to disable specific tools entirely. Disabled tools are excluded from all future invocations unless overridden by a tools array in the request body.

Permission-based tool filtering

Selected tools will be available based on your regex patterns but won't include tools that are not within your permission scope. This means:

• If you request an action to create a Jira ticket but this action is not available to you as a user, it won't be available to Port AI.
• Members trying to use builder tools like upsert_blueprint will not have access to these tools through Port AI if they lack the necessary permissions.
• Tool availability is determined by the intersection of your regex selection AND your user permissions.

Port AI respects your individual user permissions and cannot access tools or perform actions that you don't have permission to use.

How tool selection works

Include a tools parameter in your API request with an array of regex patterns. Port AI will only use tools whose names match at least one of these patterns.

Basic format:

{
  "prompt": "Your question or request",
  "tools": ["regex_pattern_1", "regex_pattern_2"]
}

Port tools vs. MCP connector tools

When you attach MCP connectors, treat patterns in two groups. To enable tools from a connector, an entry in tools must start with that connector's identifier in Port, then an underscore, then the rest of your regex (for example notion_.* for the notion connector). You cannot place ^ or any other characters before that prefix: ^notion_.* does not count as a connector pattern and will not enable connector tools. Every other pattern applies only to Port MCP tools (catalog query, run_* actions, and the rest of the built-in Port tool surface), including very broad regex such as .* or ^run_.*. Those patterns never enable connector tools on their own, even when the regex text could match a connector tool name. Add an explicit pattern that begins with {identifier}_ when you need connector tools.

Common tool selection patterns

Read-only operations (click to expand)

Perfect for monitoring dashboards and reporting systems where no modifications should be made.

["^(list|search|track|describe)_.*"]

What this matches:

• list_entities, list_blueprints, list_scorecards.
• list_actions, list_integrations.
• describe_user_details.
• search_port_knowledge_sources.

Action execution only (click to expand)

Allows only action execution tools while blocking data query operations.

["^run_.*"]

What this matches:

• run_action (the underlying tool that executes all self-service actions).
• run_create_service, run_deploy_to_production.
• run_github_create_issue, run_jira_create_ticket.
• run_slack_notify_team.

run_action must be matched

Self-service actions are executed through the internal run_action tool. Your tools regex must match run_action - either explicitly or via a pattern like "^run_.*". If you only list specific action identifiers (e.g. ["run_deploy_to_production"]) without a pattern that also matches run_action, the agent will not be able to execute those actions.

Specific integration actions (click to expand)

Target specific third-party service integrations.

["run_.*github.*", "run_.*jira.*", "run_.*zendesk.*"]

What this matches:

• run_github_create_issue, run_github_merge_pr.
• run_jira_create_ticket, run_jira_update_status.
• run_zendesk_create_ticket.

Safe entity operations (click to expand)

Enables entity operations while preventing accidental deletions.

["(?!delete_)\\w+_entity$", "list_.*"]

What this matches:

• list_entities, upsert_entity.
• Excludes: delete_entity.

Documentation and help tools (click to expand)

Focus on documentation search and help functionality.

[".*docs.*", "search_.*", "describe_.*"]

What this matches:

• search_port_knowledge_sources.
• describe_user_details.

Blueprint and scorecard analysis (click to expand)

Focus on catalog structure and quality metrics without action execution.

[".*blueprint.*", ".*scorecard.*", "^list_.*"]

What this matches:

• list_blueprints, upsert_blueprint.
• list_scorecards, upsert_scorecard.
• All list operations.

MCP connector tools (click to expand)

Tools from MCP connectors use names that start with the connector identifier in Port, followed by an underscore. A tools entry only applies to connector tools if the pattern string itself begins with that {identifier}_ text (for example notion_.*). A leading regex anchor breaks that rule, so ^notion_.* does not work for connector tools. Patterns meant for Port tools (list_*, run_*, .*, ^run_.*, and so on) never unlock connector tools by themselves; see Port tools vs. MCP connector tools above.

["notion_.*"]

What this matches:

• Any published tool for that connector, such as notion_notion-search.

Use the same identifier you pass in mcpServers[].identifier in place of notion.

Interactive tool matcher

Test your regex patterns to see which MCP tools would be available to Port AI. Enter your patterns in JSON array format (e.g., ["^(list|get)_.*", "run_.*github.*"]) and see the matching tools in real-time.

Regex Patterns Array:["(list|get|search)_.*"]

Enter an array of regex patterns in JSON format. Patterns automatically match from the beginning of tool names (^ is added automatically).

Tools (0 of 45 matched)

delete_actiondelete_workflowget_action_permissionsget_workflow_runlist_actionslist_self_service_triggerslist_workflowsrun_actiontrack_action_runtrigger_runupdate_action_permissionsupsert_actionupsert_workflowdelete_blueprintdelete_entitylist_blueprintslist_entitiessimulate_blueprint_permissionstrigger_auto_discoveryupsert_blueprintupsert_entitydescribe_user_detailsload_skillsearch_port_knowledge_sourcesget_integration_event_logsget_integration_kinds_with_examplesget_integration_sync_metricslist_integrationstest_integration_mappingdelete_sidebar_folderdelete_widgetduplicate_pageget_pageget_sidebarload_widget_schemamove_pageupdate_entity_pageupsert_dashboard_pageupsert_sidebar_folderupsert_widgetlist_pluginsupsert_plugindelete_scorecardlist_scorecardsupsert_scorecard

Action tools note

Action tools (starting with run_*) depend on your Port configuration. The examples shown represent common action patterns, but your actual available actions may differ based on the self-service actions configured in your Port instance.

Best practices

Security and control

• Principle of least privilege: Only include tools necessary for the specific use case.
• Test patterns: Use the interactive matcher above to verify your regex patterns.
• Automated systems: Use highly restrictive patterns for automated workflows.
• User-facing interfaces: Consider broader patterns for interactive use cases.

MCP servers in API requests

When using the /v1/ai/invoke endpoint, you can attach up to five configured MCP connectors per request. This allows Port AI to use tools from those servers in addition to your Port MCP tools, filtered by your tools patterns.

AI agent invocations

The mcpServers parameter is supported on /v1/ai/invoke and on workflow type: "AI" action nodes. It is not part of the invoke an agent request body. Agent entities use MCP connectors configured on the agent and require a connected user, so agent MCP works in chat only. See build an AI agent.

Prerequisites

• Your organization has MCP connectors set up (admins add servers under Data sources and publish allowed tools).
• The API token represents a user who is allowed to use those connectors. For connectors that use per-user OAuth, authenticate that user in Port before you rely on connector tools (for example from MCP Servers in the avatar menu or from the Port AI chat + menu) so OAuth tokens are available for tool calls.

Limitations

When /v1/ai/invoke runs with an organization automation token (for example, from an automation or a workflow type: "AI" node), per-user OAuth MCP connectors are not supported. Per-user OAuth tokens are keyed to the user, so automation-token callers cannot use them.

For automated contexts, use organization-level OAuth or connectors with shared header authentication.

Request body

Add an mcpServers array. Each item must include the connector identifier in Port (the _mcp_server entity identifier), for example the value you see on the connector in the catalog or in Data sources.

"mcpServers": [
  { "identifier": "notion" }
]

Port AI resolves which MCP servers to use based on this field:

• Omit mcpServers: Port AI falls back to all of your usable MCP servers.
• mcpServers: [] (empty array): Port AI uses no MCP servers.
• mcpServers with entries: Port AI uses only the listed servers.

Your existing tools array still controls which tool names may run. Port-side patterns (anything that does not begin with {identifier}_ as the first characters of the pattern string, including .* and ^notion_.*) only affect Port MCP tools; use notion_.* (not ^notion_.*) when the identifier is notion. See MCP connector tools and Port tools vs. MCP connector tools. Native Port tools and MCP connector tools are evaluated together against those patterns.

Example

curl 'https://api.port.io/v1/ai/invoke' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "userPrompt": "Search our Notion space for the onboarding checklist and summarize the steps.",
    "tools": ["notion_notion-search", "^list_.*", "^run_.*"],
    "mcpServers": [
      { "identifier": "notion" }
    ]
  }'

For all request fields (including userPrompt, tools, and optional mcpServers), see the General-purpose AI interactions API reference.