MCP System Tools

This page is for system administrators, developers, and end users. It describes the system-level Model Context Protocol (MCP) tools provided by Appian MCP Server out of the box.

How system tools work with developer-enabled tools

Appian MCP Server provides two categories of Model Context Protocol (MCP) tools:

• System tools provide discovery and data access. System tools let external AI applications find available tools, retrieve schemas, invoke design objects, and query your data fabric.
• Developer-enabled tools provide business logic. Developers make process models, expression rules, and Appian AI agents available through MCP. For enablement instructions, see Make Design Objects Available as MCP Tools.

System tools and developer-enabled tools work together. The AI application uses system tools to discover and invoke developer-enabled tools.

Generic tools

Generic Model Context Protocol (MCP) tools handle discovery and invocation of developer-enabled design objects. These tools form the core workflow for interacting with Appian business logic through MCP.

appian_search_tools

Search for design objects that are available as MCP tools.

Inputs:

Outputs:

Limitations: Results only include tools the authenticated user has permission to access.

appian_get_tool_schema

Get the full input and output schema for a specific design object enabled as an MCP tool.

Inputs:

Outputs:

appian_invoke_process_model

Start a process model that has been made available as an MCP tool and wait for completion.

Inputs:

Outputs:

Limitations: Process models with start forms or synchronous user input tasks stall until timeout. Design process models for MCP invocation without UI-dependent steps.

appian_get_process_status

Check the status of a running or completed process instance started through MCP.

Inputs:

Outputs:

appian_invoke_expression_rule

Evaluate an expression rule that has been made available as an MCP tool with provided inputs.

Inputs:

Outputs:

Limitations: If the expression rule queries objects the authenticated user lacks access to, the rule succeeds but returns null for inaccessible data.

appian_invoke_agent

Invoke an Appian AI agent that has been made available as an MCP tool with a message.

Inputs:

Outputs:

Limitations: Multi-turn conversations are not supported through MCP. Each invocation is a single prompt and response.

appian_get_agent_status

Check whether an AI agent started through MCP is still running or has finished. While the AI agent runs, the response also returns summaries of the steps it has completed and a hint for how soon to request status again.

Inputs:

Outputs:

Step summaries returned during execution

While an AI agent is pending or running, the steps output returns the history of steps the AI agent has completed so far. Each entry summarizes what the AI agent found or did at that step, such as "Searching for Q2 support cases…", "Found 47 cases. Analyzing by category…", or "Top issues: VPN connectivity (7), password resets (5), SSO lockouts (4)". The AI agent platform produces these summaries as it works, so they require no extra processing.

A step summary describes the result of a step at a high level. It does not include tool inputs, query parameters, raw returned records, or the AI agent's internal reasoning. This lets an AI application show what the AI agent is working on without surfacing query details or sensitive data.

Before the AI agent completes its first step, the steps output is absent from the response, even though the status is already "PENDING" or "RUNNING". The nextPollHint output, by contrast, is present throughout the pending and running states.

Each summary is limited to 500 characters. A single response returns at most 20 step summaries and shows the most recent steps. When the first index in the steps list is greater than 0, earlier steps were truncated from the response.

Adaptive polling with nextPollHint

The nextPollHint output tells the AI application how soon to request status again through its pollAfterMs value. Appian sets this value based on how recently the AI agent completed a step:

• 2000 (poll again after two seconds): The AI agent completed a step within the last five seconds, so it is actively working and new progress is likely soon.
• 5000 (poll again after five seconds): No steps have completed yet, or the last step completed more than five seconds ago, which suggests the AI agent is waiting on a longer operation.

An AI application should poll appian_get_agent_status at intervals of five seconds or less while the AI agent is running.

Example enriched status response

The following response shows an AI agent that is still running. The steps list contains the completed step summaries, and nextPollHint recommends requesting status again in two seconds:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "status": "RUNNING",
  "invocationId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "startedAt": "2026-08-17T14:32:00Z",
  "numToolCalls": 3,
  "steps": [
    {
      "index": 0,
      "summary": "Searching for Q2 support cases...",
      "timestamp": "2026-08-17T14:32:14Z"
    },
    {
      "index": 1,
      "summary": "Found 47 cases. Analyzing by category...",
      "timestamp": "2026-08-17T14:32:17Z"
    },
    {
      "index": 2,
      "summary": "Top issues: VPN connectivity (7), password resets (5), SSO lockouts (4)",
      "timestamp": "2026-08-17T14:32:28Z"
    }
  ],
  "nextPollHint": {
    "pollAfterMs": 2000
  }
}

Limitations: Step summaries and polling hints are available only when an AI agent is started with appian_invoke_agent. Process models started with appian_invoke_process_model do not return step summaries.

Data fabric tools

The Query Data Fabric tool collection provides access to synced record types that are published for analytics and AI. System administrators enable or disable the collection in the Admin Console.

Data fabric tools identify record types by their SQL reference name. Appian automatically generates a SQL reference name for each record type, and developers can edit the SQL reference name in the record type's properties. AI applications use the SQL reference name as the table identifier when constructing queries against the data fabric.

appian_data_fabric_metadata

Get available record types, fields, and relationships in the data fabric to understand which data to query. This tool provides both keyword search and semantic search options to the AI agent to explore the data model available.

Inputs:

Outputs:

appian_data_fabric_sql_query

Query record data using SQL syntax.

Inputs:

Outputs:

Limitations: Appian MCP Server cannot query the following record types:

• Unsynced record types.
• Legacy record types.
• Record types with record-level security expressions. Replace the security expression with security rules to query the record data.

Process HQ tools

The Analyze Business Processes tool collection lets AI applications query, analyze, and build reports for business processes and record data in Process HQ. System administrators enable or disable the collection in the Admin Console.

appian_data_catalog_metadata

Discover record types available for reporting, filtered by data catalog visibility. This tool returns only the record types that are published for analytics and AI.

Inputs:

Output: A text response listing available record types with their names, fields, data types, and relationships.

appian_create_report

Create a new report in Process HQ from a dataset. The report is persisted immediately and the tool returns the report name and a link to open it.

Inputs:

Output: A text response with the name of the created report and a link to open it in Process HQ.

Limitations:

• This tool only creates reports from datasets. Process-backed reports are not supported. Reports are persisted immediately on creation.
• There is no draft or preview state. If the report configuration is invalid, the tool returns a descriptive error that the AI application can use to retry with corrected parameters.

appian_list_business_processes

List all business processes available in the environment.

Inputs:

Output: A text response listing the available business processes with their names, descriptions, and Appian IDs.

appian_get_business_process

Get detailed information about a specific business process.

Inputs:

Output: A text response describing the business process metadata, including its datasets, filters, and sync schedule.

appian_aggregate_business_process

Query aggregated process metrics—case counts, durations, and activity frequencies.

Inputs:

Output: A text response with the aggregated metrics, such as case counts, average durations, or activity frequencies.

appian_explore_attributes

Explore which attribute values correlate with longer or shorter durations.

Inputs:

Output: A text response listing attribute values and how they correlate with the specified metric.

appian_discover_cases

Discover individual cases matching specific criteria.

Inputs:

Output: A text response listing the matching cases with their IDs and names.

appian_discover_events_in_case

Retrieve the ordered sequence of events within specific cases.

Inputs:

Output: A text response listing the ordered sequence of events for each case, including activity names and timestamps.

appian_get_filter_reference

Get the filter schema reference to understand how to filter process data.

Inputs:

Output: A text response documenting all available filter types with schemas and examples.

appian_start_insights

Start an asynchronous root cause analysis for a business process KPI. Returns a job ID that you use to poll for results with appian_get_insights_status.

Inputs:

Output: A job ID string to use with appian_get_insights_status.

appian_get_insights_status

Poll the status of an insight generation job started by appian_start_insights.

Inputs:

Output: A text response with the job status and, when complete, a ranked list of insights. Each insight includes the contributing factors, their impact score, and the number of affected cases.

appian_get_recommendations_reference

Get Appian-specific remediation guidance for common process issues.

Inputs:

Output: A text response with categorized remediation guidance for common process issues such as long durations, rework loops, SLA violations, and unbalanced workloads.

appian_model_statistics

Get the full process model with activity and sequence performance statistics.

Inputs:

Output: A text response with per-activity duration statistics, per-sequence wait time statistics, and global extrema across all activities.

End-to-end examples

The following examples show how an AI application chains Model Context Protocol (MCP) system tools together to answer a user's question or complete a task.

Query data with system tools

This example uses data fabric tools to find and query record data:

1. A user asks their AI application: How many open support cases about connectivity issues are assigned to the West region?
2. The AI application calls appian_data_fabric_metadata to discover available record types and finds a "Support Case" record type with fields for status, region, and a description field with smartSearchEnabled set to true.
3. The AI application calls appian_data_fabric_sql_query with a SQL query that uses smart search to semantically search the description field for "connectivity issues," filtered to open cases in the West region.
4. The AI application receives the filtered results (respecting all record type security) and returns the count to the user.

Invoke developer-enabled tools

This example uses generic tools to discover and invoke a developer-enabled expression rule:

1. A user asks their AI application: Calculate the discount for order 12345.
2. The AI application calls appian_search_tools with the query "calculate discount" and finds an MCP-enabled expression rule called "Calculate Order Discount."
3. The AI application calls appian_get_tool_schema to retrieve the input schema (order ID as a required input).
4. The AI application calls appian_invoke_expression_rule with the order ID.
5. The AI application receives the calculated discount value and returns it to the user.

Create a report in Process HQ

This example uses Process HQ tools to discover a data source and create a report from a dataset:

1. A user asks their AI application: Create a bar chart of average cycle time by region.
2. The AI application calls appian_data_catalog_metadata to discover record types the user can report on and finds a record type with fields for cycle time and region.
3. The AI application calls appian_create_report with a structured report configuration that specifies the data source, a bar chart type, cycle time as the measure, and region as the grouping.
4. The report is persisted in Process HQ. The AI application receives the report name and a link, which it returns to the user.

Feedback