Make Design Objects Available as MCP Tools

On This Page

This page is for developers. It describes how to make new or existing Appian design objects available to external AI applications through the Appian MCP Server.

Developers control which objects are available to external AI applications through MCP tools. AI agents, expression rules, and process models must be individually enabled before it appears in tool search. Object security controls who can access an object. For example, an MCP client that already knows an object's UUID can call it if the authenticated identity has permission.

Supported design objects

The following design objects are available as Model Context Protocol (MCP) tools:

AI agents: External AI applications can invoke Appian AI agents with a prompt and receive responses.
Business processes: External AI applications can query data in business processes.
Expression rules: External AI applications can evaluate expression rules with provided inputs.
Process models: External AI applications can start process models and check execution status.
Record types: External AI applications can read and query data from synced record types. Record types that use direct data access or have a record-level security expression cannot be queried by external systems or agents.

Enable a design object as an MCP tool

The enablement process differs by design object type.

Process models, expression rules, and AI agents must be explicitly enabled through each object's properties.
Synced record types are available through the data fabric MCP tools by default and do not require per-object enablement. Access to the data is controlled through object-level, record-level, and field-level security. You can configure how the data fabric tools identify the record type.
Business processes from Process HQ are available by default through the Process HQ tools and do not require per-object enablement. Access to the data is controlled through object security.

Enable process models, expression rules, and AI agents

To make a process model, expression rule, or AI agent available as a Model Context Protocol (MCP) tool:

Open the design object in Appian Designer.
Open the object's properties dialog.
Select Enable MCP Server Access.
Review the Description field to ensure it clearly explains what the object does and when to use it. For guidance, see Write effective design object descriptions.
Click OK.
Give the authenticating account the necessary permissions to interact with each object:
- At least Viewer permission for expression rules or AI agents.
- At least Initiator permission for process models.

Before enabling a design object, review the design considerations for your object type.

Process model design considerations

When you enable a process model as an MCP tool, process variables marked as inputs become tool parameters. The AI application provides values for these parameters when invoking the tool.

Caution: Process models with start forms or synchronous user input tasks cannot complete through MCP. The tool call stalls until the process times out. A warning appears in the properties dialog when you enable a process model that contains these elements.

Remove start form dependencies. Process models invoked through MCP cannot present forms to users. Remove start forms or create a separate version for MCP invocation.
Avoid synchronous user input tasks. Activities that wait for user input (such as attended tasks) block execution indefinitely through MCP.
Keep execution time reasonable. Long-running process models may time out before completion. Design MCP-invoked process models to complete without manual intervention.
Complex input types: When a process model accepts inputs that use record types or custom data types (CDTs), Appian MCP Server automatically sends the full nested schema to the AI application.

Expression rule design considerations

When you enable an expression rule as an MCP tool, the rule's input parameters become tool parameters. The AI application provides values for these parameters when invoking the tool.

Security behavior: If the expression rule queries objects the authenticated user lacks access to, the rule succeeds but returns null for inaccessible data. This behavior is consistent with standard platform behavior.
Timeout: Expression rules must complete within the execution timeout. Design rules that perform heavy computation or large data queries to complete efficiently.
Use cases: Expression rules work well as MCP tools for business logic, calculations, data transformations, and lookups.
Complex input types: When an expression rule accepts inputs that use record types or custom data types (CDTs), Appian MCP Server automatically sends the full nested schema to the AI application.

AI agent design considerations

When you enable an AI agent as an MCP tool, external AI applications send a prompt to the AI agent and receive the response.

Permission requirement: The authenticated user must have permission to view the AI agent and all of its underlying tools.
Single-turn interaction: MCP invocations are single-turn. The external AI application sends one prompt and receives one response. Multi-turn conversations are not supported through MCP.
Context limitations: The AI agent receives only the prompt provided by the external AI application. Context from the user's conversation in the external AI application is not automatically passed to the Appian AI agent.

Access record types through MCP

Synced record types are available to external AI applications when the Query Data Fabric tool collection is enabled. External AI applications identify each record type by its SQL reference name.

Access to record type data is controlled entirely through security. For details on required permissions, see Appian MCP Server Security.

Tip: Ensure each record type has a clear description since AI applications use them to decide when and how to use it. For guidance, see Write effective design object descriptions.

View or edit the SQL reference name

The data fabric MCP tools use a record type's SQL reference name to identify and query data. Appian generates a SQL reference name for each synced record type by default. You can view the current name or update it to a different unique name.

To view or edit the SQL reference name for a synced record type:

In Appian Designer, open the record type.
Click Settings > Properties.
In the SQL Reference Name field, enter a new name. SQL reference names must be unique across the environment.
Click SAVE CHANGES to close the properties.
Click SAVE to save the record type settings.

Note: When you deploy a synced record type, the SQL reference name is included in the deployment. If the name conflicts with a different record type in the target environment, the record type is not imported. You can resolve conflicts automatically using an import customization file, or resolve them manually before deploying.

Access business process data through MCP

Business processes are available to external AI applications through Process HQ when the Analyze Business Processes tool collection is enabled.

Access to business process data is controlled through business process object security or through process-level access in Process HQ. The authenticated user or service account must have access to a process to query its data through MCP.

How the generic tool architecture works

Appian MCP Server does not create a separate Model Context Protocol (MCP) tool definition for each design object you enable. Instead, Appian provides a fixed set of system tools that handle discovery and execution for all MCP-enabled design objects:

An external AI application calls appian_search_tools to find available tools matching the user's request.
The AI application calls appian_get_tool_schema to retrieve the full input and output schema for a specific tool.
The AI application calls the appropriate invocation tool to execute the design object.

Developers do not define individual tool names or schemas. Appian generates the tool schema automatically from the design object's configuration (input variables, parameters, and data types).

Write effective design object descriptions

The design object's description is how AI applications decide when and how to use your tool. A well-written description directly affects whether the AI application selects your tool for a user's request.

A good tool description includes:

What the tool does: A clear statement of the tool's purpose.
When to use it: Context about when this tool is the right choice.
What inputs it expects: A brief mention of key inputs the tool requires.

For detailed guidance and examples, see Write Effective MCP Tool Descriptions.

How MCP tool configurations deploy

Model Context Protocol (MCP) tool configuration metadata is stored as part of the design object. When you deploy a design object to a new environment through a package:

MCP configuration travels with the object. If the target environment has Appian MCP Server enabled, the tool becomes available automatically.
Changes appear in Compare and Deploy. MCP-related configuration changes are visible during deployment review.
Disabled target environments preserve configuration. If Appian MCP Server is disabled in the target environment, the MCP tool configuration is preserved but inactive. The tool becomes available automatically when Appian MCP Server is enabled.

For more details on deployment, see Deploy MCP Tool Configurations.

Feedback

Was this page helpful?