MCP Gateway Tools

Overview

Tools enable you to discover, search, and execute actions across your Apigene applications. Agent mode adds context tools, Agent Skills-compatible skill listing/retrieval/creation, and Agent Workflows (run_workflow, resume_workflow, and CRUD). When MCP App UI is enabled, additional tools render results in UI widgets. All tools follow the standard MCP tool calling protocol.

Tools Reference

get_instructions

Get the complete agent instructions and capabilities. Available in: Agent mode only Parameters: None Returns: Agent instructions including description, guidelines, and available apps Example:

{
  "tool": "get_instructions",
  "arguments": {}
}

list_available_apps

List all available applications in the agent. Available in: Agent mode only Parameters:

include_action_summaries (boolean, optional): Include action summaries (default: true)
max_action_summary (number, optional): Max summaries per app (default: 20)

Returns: List of applications with optional action summaries Example:

{
  "tool": "list_available_apps",
  "arguments": {
    "include_action_summaries": true,
    "max_action_summary": 10
  }
}

list_actions

Retrieve actions from one or multiple applications. Available in: Both MCP and Agent modes Parameters:

requests (array, required): Array of action requests, each containing:
- app_name (string, required): Application identifier
- operationIds (array, optional): Specific action IDs to fetch. If omitted, returns all actions
- detail_level (string, optional): "summary" or "full" (default: "full")

Usage Modes:

Discovery Mode: Omit operationIds to get all actions (use detail_level: "summary" for lightweight listing)
Details Mode: Provide operationIds to get full parameter schemas

Returns: Array of actions or object with app names as keys (for multiple apps) Example:

{
  "tool": "list_actions",
  "arguments": {
    "requests": [
      {
        "app_name": "Slack",
        "detail_level": "summary"
      }
    ]
  }
}

search_actions

Search across all agentic metadata to find relevant actions. Available in: Both MCP and Agent modes Parameters:

query (string, optional): Free text search
action_type (string, optional): Filter by type (get, search, add, update, delete, execute)
resource (string, optional): Filter by resource type
min_rating / max_rating (number, optional): Filter by rating
required_input (string, optional): Only actions requiring this parameter
max_results (number, optional): Maximum results to return
detail_level (string, optional): "summary" or "full" (default: "full")

Returns: Filtered list of matching actions. When nothing matches, the response may include actions, a short message, and suggestions (for example: broaden the query, use list_available_apps, or use list_actions for a specific app) instead of only an empty list. Example:

{
  "tool": "search_actions",
  "arguments": {
    "query": "send message",
    "detail_level": "summary"
  }
}

run_action

Execute a single action for a specific application. Available in: Both MCP and Agent modes Parameters:

app_name (string, required): Application identifier
user_input (string, required): Natural language description
context (object, required): Action parameters including operationId
response_format (string, optional): "raw" or "formatted_md" (default: "raw")
response_projection (string, optional): JMESPath expression to transform response
customer_execution_context (object, optional): Customer-specific context
reasoning (string, optional): Short explanation of why this action was chosen; supports decision tracing in agent workflows

Returns: Action execution result Example:

{
  "tool": "run_action",
  "arguments": {
    "app_name": "Slack",
    "user_input": "Send a message to #general",
    "context": {
      "operationId": "chat.postMessage",
      "channel": "#general",
      "text": "Hello, world!"
    }
  }
}

run_action_batch

Execute the same action multiple times in parallel with different parameters. Available in: Both MCP and Agent modes Parameters:

app_name (string, required): Application identifier
user_input (string, required): Natural language description
base_context (object, required): Shared parameters (must include operationId)
batch_context (array, required): Array of varying parameters, one per execution
response_format (string, optional): Output format
response_projection (string, optional): JMESPath expression
customer_execution_context (object, optional): Customer context

Returns: Object with batch_results array and summary statistics Example:

{
  "tool": "run_action_batch",
  "arguments": {
    "app_name": "Gmail",
    "user_input": "Read multiple emails",
    "base_context": {
      "operationId": "readEmail"
    },
    "batch_context": [
      { "email_id": "123" },
      { "email_id": "456" },
      { "email_id": "789" }
    ]
  }
}

run_multi_actions

Execute multiple different actions in parallel across different applications. Available in: Both MCP and Agent modes Parameters:

actions (array, required): Array of action requests, each containing:
- app_name (string, required)
- user_input (string, required)
- context (object, required): Must include operationId
- response_format (string, optional)
- response_projection (string, optional)
- customer_execution_context (object, optional)
- template_id (string, optional): Only set when a specific MCP App template should render that action’s result in the UI

Returns: Object with results array and summary statistics Example:

{
  "tool": "run_multi_actions",
  "arguments": {
    "actions": [
      {
        "app_name": "Gmail",
        "user_input": "Get latest email",
        "context": { "operationId": "getLatestEmail" }
      },
      {
        "app_name": "Jira",
        "user_input": "List my tasks",
        "context": { "operationId": "listIssues", "assignee": "me" }
      }
    ]
  }
}

run_action_ui

Execute a single action with MCP App UI rendering so results can be shown in a visual widget (when your host supports MCP Apps). Available in: Both MCP and Agent modes, when MCP App UI features are enabled for your Apigene deployment. Parameters:

app_name (string, required): Application identifier
user_input (string, required): Natural language description
context (object, required): Action parameters including operationId
response_format (string, optional): "raw" or "formatted_md" (default: "raw")
customer_execution_context (object, optional): Customer-specific context
reasoning (string, optional): Why this action was chosen
template_id (string, optional): Only include when the user explicitly requests a specific template; otherwise omit so the default template applies

Returns: Action result; when a template applies, the response includes data suitable for the UI resource (see MCP Gateway Resources). Note: Unlike run_action, this tool does not accept response_projection.

run_multi_actions_ui

Execute multiple different actions in parallel with MCP App UI rendering (for example a grid or mesh layout comparing outputs). Available in: Both MCP and Agent modes, when MCP App UI features are enabled for your Apigene deployment. Parameters:

actions (array, required): Same shape as run_multi_actions (each item may include template_id when a specific template is requested)

Returns: Combined results with UI-oriented payload for supported hosts.

Generative UI Tools

These tools render json-render specs as interactive MCP App widgets. They are separate from run_action_ui (which visualizes API action results). Generative UI tools are available when MCP App UI is enabled (APIGENE_FEATURE_SHOW_GENERATIVE_UI is not disabled on your deployment).

Only call generative UI tools when the user explicitly asks for interactive or visual UI. Do not auto-invoke for normal text answers.

show_generative_ui

Render a one-off generative UI from an inline json-render spec. Available in: Both MCP and Agent modes, when generative UI is enabled. Parameters:

title (string, optional): Heading shown above the widget
spec (object, required): json-render spec { root, elements, state? } — layout in elements, dynamic values in state bound via { "$state": "/path" }

Returns: Validated spec plus MCP App metadata pointing at ui://show-generative-ui. Example:

{
  "tool": "show_generative_ui",
  "arguments": {
    "title": "Plan comparison",
    "spec": {
      "root": "stack",
      "elements": {
        "stack": { "type": "Stack", "props": {}, "children": ["title"] },
        "title": { "type": "Text", "props": { "text": "Hello" }, "children": [] }
      }
    }
  }
}

list_generative_ui_templates

List saved generative UI templates for the agent from the MCP connection URL. Available in: Both MCP and Agent modes, when generative UI is enabled. Parameters:

detailed (boolean, optional, default false): If true, include full generative_spec per template; if omitted/false, return summary fields only (template_id, description, audit fields)

Returns: Array of template records from the generative-ui-templates API.

create_generative_ui_template

Persist a new generative UI template for reuse. Available in: Both MCP and Agent modes, when generative UI is enabled. Parameters:

template_id (string, required): Unique template id (client-provided)
generative_spec (object, required): json-render spec (same shape as show_generative_ui)
description (string, optional): Human-readable description

Returns: Created template record.

Put all dynamic values in state, not as literals in elements. show_generative_ui_from_template only deep-merges runtime data into state.

update_generative_ui_template

Patch an existing template. Available in: Both MCP and Agent modes, when generative UI is enabled. Parameters:

template_id (string, required): Template to update
description (string, optional, nullable): New description; null clears it; omit to leave unchanged
generative_spec (object, optional): Replacement spec; omit to keep current layout

Returns: Updated template record.

get_generative_ui_template

Load one template including its full generative_spec. Available in: Both MCP and Agent modes, when generative UI is enabled. Parameters:

template_id (string, required)

Returns: Full template record.

delete_generative_ui_template

Remove a saved template. Available in: Both MCP and Agent modes, when generative UI is enabled. Parameters:

template_id (string, required)

Returns: Deletion confirmation.

show_generative_ui_from_template

Render UI from a saved template, merging runtime data into spec.state. Available in: Both MCP and Agent modes, when generative UI is enabled. Parameters:

template_id (string, required): Id from create_generative_ui_template
title (string, optional): Override title
data (object, optional): Values deep-merged into the template’s state before render

Returns: Rendered widget via ui://show-generative-ui. Example:

{
  "tool": "show_generative_ui_from_template",
  "arguments": {
    "template_id": "pricing-table",
    "data": { "selectedPlan": "pro" }
  }
}

list_contexts

List all available contexts and context type definitions. Available in: Agent mode only Parameters: None Returns: Object with contexts array and context_types array Example:

{
  "tool": "list_contexts",
  "arguments": {}
}

get_context

Get detailed information about a specific context. Available in: Agent mode only Parameters:

context_id (string, required): The context identifier

Returns: Full context details Example:

{
  "tool": "get_context",
  "arguments": {
    "context_id": "ctx_123"
  }
}

search_contexts

Search for contexts with flexible filtering. Available in: Agent mode only Parameters:

query (string, optional): Search query
type (string, optional): Filter by context type
status (string, optional): Filter by status (default: "active")
max_results (number, optional): Maximum results (default: 5)

Returns: Object with matching contexts and context_types Example:

{
  "tool": "search_contexts",
  "arguments": {
    "query": "customer support",
    "type": "Knowledge"
  }
}

add_context

Create a new context in the system. Available in: Agent mode only Parameters:

name (string, required): Unique context name
description (string, required): Detailed description
summary (string, optional): Short summary
when_to_use (string, optional): Usage guidelines
type (string, optional): Context type (must match existing types)
apps (array, optional): Associated app names
status (string, optional): "active" or "disabled" (default: "active")

Returns: Created context object Example:

{
  "tool": "add_context",
  "arguments": {
    "name": "Customer Support Guidelines",
    "description": "Guidelines for handling customer support requests...",
    "summary": "Support handling guidelines",
    "type": "Knowledge",
    "apps": ["Zendesk", "Slack"]
  }
}

list_skills

List skill metadata attached to the agent (Agent Skills style). Does not return the full SKILL.md body; use get_skill_content for that. Available in: Agent mode only Parameters:

detail_level (string, optional): "summary" (id, name, description only; fewer tokens) or "full" (all metadata fields; default: "full")

Returns: Object with skill_list entries. Summary mode is best for discovery; full mode includes fields such as license, compatibility, metadata, allowed tools, status, and timestamps. Example:

{
  "tool": "list_skills",
  "arguments": {
    "detail_level": "summary"
  }
}

get_skill

Fetch one skill by id: metadata plus optional packaged files (scripts, references, assets). Does not return the main SKILL.md body; use get_skill_content for the instruction text. Available in: Agent mode only Parameters:

skill_id (string, required): Skill identifier

Returns: Object with a skill payload (metadata and optional path→content maps for scripts, references, assets). Example:

{
  "tool": "get_skill",
  "arguments": {
    "skill_id": "sk_abc123"
  }
}

get_skill_content

Return the full SKILL.md content for a skill (YAML front matter plus Markdown body). Available in: Agent mode only Parameters:

skill_id (string, required): Skill identifier

Returns: Object with a content string. Example:

{
  "tool": "get_skill_content",
  "arguments": {
    "skill_id": "sk_abc123"
  }
}

add_skill

Create a new skill and attach it to the current agent. Content should follow the Agent Skills specification (valid name format, description length, structured front matter, reasonably sized body with long reference material in references/ when needed). Available in: Agent mode only Parameters:

name (string, required): Skill name (lowercase, hyphens; per spec)
description (string, required): What the skill does and when to use it
content (string, required): Full SKILL.md (front matter + Markdown body)
license (string, optional)
compatibility (string, optional)
metadata (object, optional)
allowed_tools (string, optional)
status (string, optional): "active" or "disabled" (default: "active")
scripts (object, optional): Map of file path to content under scripts/
references (object, optional): Map of file path to content under references/
assets (object, optional): Map of file path to content under assets/

Returns: The created skill record. Example:

{
  "tool": "add_skill",
  "arguments": {
    "name": "my-workflow",
    "description": "Steps for our internal review workflow.",
    "content": "---\nname: my-workflow\ndescription: Steps for our internal review workflow.\n---\n\n## When to use\n..."
  }
}

Agent workflow tools

Multi-step graphs on an agent. Product guide: Workflows.

list_workflows

List workflows for the current agent. Available in: Agent mode only Parameters:

detailed (boolean, optional): Return full definitions instead of summaries

create_workflow

Create a workflow (workflow_id, description, nodes, connections; optional name, inputs). Available in: Agent mode only

get_workflow

Fetch one workflow by workflow_id (detailed optional). Available in: Agent mode only

update_workflow

Update an existing workflow by workflow_id (optional fields: description, name, nodes, connections, inputs). Available in: Agent mode only

delete_workflow

Delete a workflow by workflow_id. Available in: Agent mode only

run_workflow

Execute a workflow. Available in: Agent mode only Parameters:

workflow_id (string, required)
inputs (object, optional): Runtime inputs merged over stored defaults
include_data (boolean, optional): Include per-step traces (needed to Simulate in Copilot)
dry_run (boolean, optional): Walk the graph without live API / MCP / LLM side effects

Example:

{
  "tool": "run_workflow",
  "arguments": {
    "workflow_id": "onboard-new-hire",
    "inputs": { "email": "alex@example.com" },
    "include_data": true,
    "dry_run": true
  }
}

resume_workflow

Continue a run paused at a human approval (waiting_human). Available in: Agent mode only Parameters:

run_id (string, required)
decision (string, required): "approve" or "reject"
edits (object, optional): Field overrides before approve
reason (string, optional)
include_data (boolean, optional)

Recommended Workflows

Discovering and Executing Actions

Discovery: Use list_actions with detail_level: "summary" to find relevant actions
Get Details: Use list_actions with operationIds to get full parameter schemas
Execute: Use run_action with complete parameters

Searching for Actions

Search: Use search_actions with detail_level: "summary" to find actions
Get Details: Use list_actions with specific operationIds for full schemas
Execute: Use run_action with proper parameters

Batch Operations

Identify Action: Find the action you want to execute multiple times
Prepare Batch: Create base_context with shared parameters and batch_context with varying parameters
Execute: Use run_action_batch for parallel execution

Skills

Discover: list_skills with detail_level: "summary" to see what exists
Read instructions: get_skill_content for the main SKILL.md body when activating a skill
Optional files: get_skill if you need scripts, references, or assets
Create: add_skill when adding a new skill to the agent (follow Agent Skills formatting rules)

Agent Workflows

Create / update: create_workflow or update_workflow with nodes and connections
Dry run: run_workflow with dry_run: true and include_data: true
Simulate in Copilot on the agent’s Workflows tab after a traced run
HITL: when status is waiting_human, call resume_workflow with run_id and decision

Generative UI

Ad hoc: show_generative_ui with an inline { root, elements, state? } spec
Persist: create_generative_ui_template → list_generative_ui_templates / get_generative_ui_template to manage
Render saved: show_generative_ui_from_template with data merged into template state
Update or remove: update_generative_ui_template or delete_generative_ui_template

Author templates in the Copilot Agents editor (Generative UI tab) or entirely via these MCP tools.

Complete Tool Index

Tool	MCP mode	Agent mode
`list_actions`	✅	✅
`search_actions`	✅	✅
`run_action`	✅	✅
`run_action_batch`	✅	✅
`run_multi_actions`	✅	✅
`run_action_ui`	✅*	✅*
`run_multi_actions_ui`	✅*	✅*
`show_generative_ui`	✅*	✅*
`list_generative_ui_templates`	✅*	✅*
`create_generative_ui_template`	✅*	✅*
`update_generative_ui_template`	✅*	✅*
`get_generative_ui_template`	✅*	✅*
`delete_generative_ui_template`	✅*	✅*
`show_generative_ui_from_template`	✅*	✅*
`get_instructions`	—	✅
`list_available_apps`	—	✅
`list_contexts`	—	✅
`get_context`	—	✅
`search_contexts`	—	✅
`add_context`	—	✅
`list_skills`	—	✅
`get_skill`	—	✅
`get_skill_content`	—	✅
`add_skill`	—	✅
`list_workflows`	—	✅
`create_workflow`	—	✅
`get_workflow`	—	✅
`update_workflow`	—	✅
`delete_workflow`	—	✅
`run_workflow`	—	✅
`resume_workflow`	—	✅

* Requires MCP App UI / generative UI features to be enabled on your deployment. Individual tools can also be disabled per agent via Setup → MCP tool toggles in the Agents editor.

Response Formatting

response_format Parameter

"raw" (default): Returns exact API response
"formatted_md": Returns Markdown-formatted response (use when explicitly requested)

response_projection Parameter

Use JMESPath expressions to transform and reduce response size:

Field Selection: "{name: name, email: email}"
Array Extraction: "items[*].name"
Filtering: "items[?price > 100]"
Aggregation: "sum(items[*].price)"

Error Handling

Tools return standard error responses when:

Authentication fails
Required parameters are missing
Action execution fails
Invalid operation IDs are provided

Check the error message for specific details about what went wrong.

Next Steps

Workflows — product guide for graphs, simulate, and approvals
Learn about resources
See usage examples

​Overview

​Tools Reference

​get_instructions

​list_available_apps

​list_actions

​search_actions

​run_action

​run_action_batch

​run_multi_actions

​run_action_ui

​run_multi_actions_ui

​Generative UI Tools

​show_generative_ui

​list_generative_ui_templates

​create_generative_ui_template

​update_generative_ui_template

​get_generative_ui_template

​delete_generative_ui_template

​show_generative_ui_from_template

​list_contexts

​get_context

​search_contexts

​add_context

​list_skills

​get_skill

​get_skill_content

​add_skill

​Agent workflow tools

​list_workflows

​create_workflow

​get_workflow

​update_workflow

​delete_workflow

​run_workflow

​resume_workflow

​Recommended Workflows

​Discovering and Executing Actions

​Searching for Actions

​Batch Operations

​Skills

​Agent Workflows

​Generative UI

​Complete Tool Index

​Response Formatting

​response_format Parameter

​response_projection Parameter

​Error Handling

​Next Steps

Overview

Tools Reference

get_instructions

list_available_apps

list_actions

search_actions

run_action

run_action_batch

run_multi_actions

run_action_ui

run_multi_actions_ui

Generative UI Tools

show_generative_ui

list_generative_ui_templates

create_generative_ui_template

update_generative_ui_template

get_generative_ui_template

delete_generative_ui_template

show_generative_ui_from_template

list_contexts

get_context

search_contexts

add_context

list_skills

get_skill

get_skill_content

add_skill

Agent workflow tools

list_workflows

create_workflow

get_workflow

update_workflow

delete_workflow

run_workflow

resume_workflow

Recommended Workflows

Discovering and Executing Actions

Searching for Actions

Batch Operations

Skills

Agent Workflows

Generative UI

Complete Tool Index

Response Formatting

response_format Parameter

response_projection Parameter

Error Handling

Next Steps