Connect Your AI Application to Appian MCP Server

This page is for end users. It describes how to connect Model Context Protocol (MCP)-compatible AI applications to Appian MCP Server to interact with application data and business logic through natural language. Ask your administrator which connection method your environment supports.

Supported MCP clients

Appian MCP Server with OAuth 2.0 authentication supports the following MCP clients:

• Claude Code.
• Codex CLI and Desktop App.
• Kiro CLI.
• Antigravity IDE and Desktop App.
• Enterprise clients: Gemini Enterprise, Microsoft Copilot Studio, Salesforce Agentforce, and other enterprise MCP clients that let you enter the connection details manually.

The following MCP clients are not supported at this time:

• Kiro IDE.
• Cursor IDE and CLI.

Prerequisites for connecting to Appian MCP Server

Before you connect your AI application to Appian MCP Server via Model Context Protocol (MCP):

• Appian MCP Server enabled: A system administrator must enable Appian MCP Server in the Admin Console. If the server is not enabled, you cannot connect.
• Designer group membership: You must be a member of the Designers group to use Appian MCP Server. If you are not in this group, the server rejects your requests.
  • For OAuth 2.0, your Appian permissions determine which tools and data you can access.
  • For service account API key access, the service account must also be a member of the Application User group to invoke Appian AI agents through MCP.
• Supported connection method:
  • For OAuth 2.0, a system administrator must register an authorization code grant client with the mcp scope, a redirect URI, and required groups that include you.
  • For service account API key access, you need the service account API key provided by your system administrator.

Get connection details

Appian MCP Server supports two ways to connect an AI application through Model Context Protocol (MCP):

• OAuth 2.0: You authorize the AI application through Appian's sign-in page, and all requests run as you.
• Service account API key: You configure the AI application with an API key that authenticates as a shared service account. All requests run as the service account, not as an individual user.

Depending on your connection method, you need to obtain specific connection details from your system administrator.

Get your OAuth 2.0 connection details

The general flow for OAuth 2.0 authorization is:

• Your AI application starts the authorization and opens Appian's sign-in page in a browser.
• You sign in with your Appian credentials, or through your configured single sign-on.
• Appian confirms your access and returns you to the AI application.
• The AI application stores the access token and uses it for MCP requests.

To connect your AI application to Appian MCP Server with an OAuth 2.0 Authorization Code grant client, you need the following connection details from your system administrator:

The generic configuration format looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "mcpServers": {
    "appian": {
      "disabled": false,
      "url": "<ENVIRONMENT_URL>/mcp",
      "oauth": {
        "clientId": "<CLIENT_ID>",
        "clientSecret": "<CLIENT_SECRET>",
        "redirectUri": "<REDIRECT_URI>",
        "oauthScopes": ["mcp", "offline_access"]
      }
    }
  }
}

Replace the placeholders with the connection details listed above. Each AI application uses a different format for these fields—see Configure Your AI Application to Use Appian MCP Server for your client's exact configuration.

Get your service account connection details

To connect your AI application to Appian MCP Server with a service account API key, you need the following connection details from your system administrator:

The generic configuration format looks like this:

1
2
3
4
5
6
7
8
9
10
{
  "mcpServers": {
    "appian": {
      "url": "<ENVIRONMENT_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

Replace the placeholders with the connection details listed above.

Configure your AI application to use Appian MCP Server

Once you have your connection details, add the Appian MCP Server configuration to your AI application's MCP settings. Appian MCP Server works with any AI model your application supports.

The following sections provide configuration instructions for each supported MCP client.

Claude Code

Claude Code supports both OAuth 2.0 and service account API key authentication for Appian MCP Server.

To connect Claude Code to Appian MCP Server with OAuth 2.0:

1. Open the .mcp.json file in the directory where you run the CLI, or the global ~/.claude.json file for all projects.

2. Add the following configuration to the mcpServers section, replacing the placeholders with your OAuth 2.0 connection details:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   {
     "mcpServers": {
       "appian": {
         "type": "http",
         "url": "<ENVIRONMENT_URL>/mcp",
         "oauth": {
           "clientId": "<CLIENT_ID>",
           "callbackPort": 8080,
           "authServerMetadataUrl": "<ENVIRONMENT_URL>/suite/.well-known/openid-configuration",
           "scopes": "mcp offline_access"
         }
       }
     }
   }
   

   Each field maps to the following:

   Field	Description
   type	The transport type. Use http for Appian MCP Server.
   url	Your Appian environment URL followed by /mcp.
   clientId	The client ID provided by your system administrator.
   callbackPort	The local port Claude Code uses for the sign-in callback. Use any available port. Register http://localhost:PORT/callback with this port on the Appian client.
   authServerMetadataUrl	Your Appian environment URL followed by /suite/.well-known/openid-configuration.
   scopes	A space-separated list of OAuth scopes. Use mcp offline_access.

3. Save the file.

To connect Claude Code to Appian MCP Server with a service account API key:

1. Open the .mcp.json file in the directory where you run the CLI, or the global ~/.claude.json file for all projects.

2. Add the following configuration to the mcpServers section, replacing <ENVIRONMENT_URL> with your Appian environment URL and <API_KEY> with the API key provided by your system administrator:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   {
     "mcpServers": {
       "appian": {
         "url": "<ENVIRONMENT_URL>/mcp",
         "headers": {
           "Authorization": "Bearer <API_KEY>"
         }
       }
     }
   }
   

3. Save the file.

For more information, see the Claude Code MCP documentation.

Codex

Codex supports both OAuth 2.0 and service account API key authentication for Appian MCP Server.

To connect Codex to Appian MCP Server with OAuth 2.0:

1. Register the client in Codex and copy the callback URL that Codex provides.
2. Ask your system administrator to register that exact callback URL as a redirect URI on the Appian client. You can register the client without the port and disable strict port validation, if needed for local or native clients.
3. Open your Codex configuration file (config.toml).

4. Add the following configuration under [mcp_servers.appian], replacing the placeholders with your OAuth 2.0 connection details:

   1
   2
   3
   4
   5
   6
   7
   [mcp_servers.appian]
   enabled = true
   url = "<ENVIRONMENT_URL>/mcp"
   scopes = ["mcp", "offline_access"]
   [mcp_servers.appian.oauth]
   client_id = "<CLIENT_ID>"
   callback_url = "<REDIRECT_URI>"
   

   Each field maps to the following:

   Field	Description
   enabled	Turns the server on. Set to true.
   url	Your Appian environment URL followed by /mcp.
   scopes	The list of OAuth scopes. Use ["mcp", "offline_access"].
   client_id	The client ID provided by your system administrator.
   callback_url	The callback URL Codex provides when you register the client. Register this exact value as a redirect URI on the Appian client.

5. Save the file.

To connect Codex to Appian MCP Server with a service account API key:

1. Open your Codex configuration file (config.toml).

2. Add the following configuration under [mcp_servers.appian], replacing <ENVIRONMENT_URL> with your Appian environment URL:

   1
   2
   3
   [mcp_servers.appian]
   url = "<ENVIRONMENT_URL>/mcp"
   bearer_token_env_var = "APPIAN_MCP_API_KEY"
   

   Each field maps to the following:

   Field	Description
   url	Your Appian environment URL followed by /mcp.
   bearer_token_env_var	The name of the environment variable that holds the service account API key. Codex sends its value as a bearer token.

3. Set the environment variable to your service account API key:

   1
   export APPIAN_MCP_API_KEY="<API_KEY>"
   

4. Save the file.

For more information, see the Codex MCP documentation.

Kiro CLI

Kiro CLI supports both OAuth 2.0 and service account API key authentication for Appian MCP Server.

To connect Kiro CLI to Appian MCP Server with OAuth 2.0:

1. Open the MCP configuration file at .kiro/settings/mcp.json in your workspace, or ~/.kiro/settings/mcp.json for global configuration.

2. Add the following configuration to the mcpServers section, replacing the placeholders with your OAuth 2.0 connection details:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   {
     "mcpServers": {
       "appian": {
         "disabled": false,
         "url": "<ENVIRONMENT_URL>/mcp",
         "oauth": {
           "clientId": "<CLIENT_ID>",
           "redirectUri": "http://localhost:8080/callback",
           "oauthScopes": ["mcp", "offline_access"]
         }
       }
     }
   }
   

   Each field maps to the following:

   Field	Description
   url	Your Appian environment URL followed by /mcp.
   clientId	The client ID provided by your system administrator.
   redirectUri	The redirect URI in the format http://localhost:PORT/callback, using any available port. Register this exact value on the Appian client.
   oauthScopes	The list of OAuth scopes. Use ["mcp", "offline_access"].

3. Save the file.

To connect Kiro CLI to Appian MCP Server with a service account API key:

1. Open the MCP configuration file at .kiro/settings/mcp.json in your workspace, or ~/.kiro/settings/mcp.json for global configuration.

2. Add the following configuration to the mcpServers section, replacing <ENVIRONMENT_URL> with your Appian environment URL and <API_KEY> with the API key provided by your system administrator:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   {
     "mcpServers": {
       "appian": {
         "url": "<ENVIRONMENT_URL>/mcp",
         "headers": {
           "Authorization": "Bearer <API_KEY>"
         }
       }
     }
   }
   

3. Save the file.

For more information, see the Kiro MCP configuration documentation.

Antigravity and Gemini CLI

Antigravity supports both OAuth 2.0 and service account API key authentication for Appian MCP Server. The configuration is the same across the Antigravity IDE, Desktop App, and CLI. Add it to your global configuration (~/.gemini/config/mcp_config.json) or your workspace configuration (.agents/mcp_config.json).

To connect Antigravity to Appian MCP Server with OAuth 2.0:

1. Open the Antigravity MCP configuration file (~/.gemini/config/mcp_config.json for global, or .agents/mcp_config.json for a workspace).

2. Add the following configuration to the mcpServers section, replacing the placeholders with your OAuth 2.0 connection details:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   {
     "mcpServers": {
       "appian": {
         "serverUrl": "<ENVIRONMENT_URL>/mcp",
         "disabled": false,
         "oauth": {
           "clientId": "<CLIENT_ID>",
           "oauthScopes": ["mcp", "offline_access"]
         }
       }
     }
   }
   

   Each field maps to the following:

   Field	Description
   serverUrl	Your Appian environment URL followed by /mcp.
   clientId	The client ID provided by your system administrator.
   oauthScopes	The list of OAuth scopes. Use ["mcp", "offline_access"].

3. Save the file.
4. Complete authentication:
   • Antigravity IDE or Desktop App: Sign in through the authentication prompt in the app.
   • Antigravity CLI: Authenticate from the CLI using your credentials.

To connect Antigravity to Appian MCP Server with a service account API key, pass the key as a bearer token in the headers object:

1
2
3
4
5
6
7
8
9
10
{
  "mcpServers": {
    "appian": {
      "serverUrl": "<ENVIRONMENT_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

Replace the placeholders with your Appian environment URL and API key. Each field maps to the following:

For more information, see the Antigravity MCP documentation.

Enterprise clients

Any enterprise MCP client that accepts the authorization URL, token URL, and scopes as inputs—rather than relying on automatic discovery as described in the MCP specification—is supported by Appian. These platforms connect a custom MCP server by entering the OAuth details manually (client ID, authorization and token URLs, and scopes) in the platform's own connector configuration.

Before connecting, ensure your Appian environment is reachable from the platform. Your system administrator must also register the platform's callback URL as a redirect URI on the Appian authorization code grant client.

For setup instructions, see each platform's documentation:

• Salesforce Agentforce.
• Google Gemini Enterprise.
• Microsoft Copilot Studio.

Verify your Appian MCP Server connection

After configuring your AI application, verify the Model Context Protocol (MCP) connection is working:

1. Open your AI application.
2. Ask a question about your Appian data. For example, What tables are available?
3. Confirm the AI application returns results from your Appian environment.

If the connection is successful, you can see the available MCP tools from Appian in your AI application's tool list.

What you can do once connected

Once connected to Appian MCP Server via Model Context Protocol (MCP), you can use natural language to:

• Query data: Ask questions about the data in your applications, powered by your data fabric. The data fabric surfaces record types as tables, so your AI application refers to them by their table name rather than their record type name.
• Start processes: Kick off automated workflows built with process models.
• Run calculations: Perform calculations or data transformations using expression rules.
• Chat with AI agents: Send prompts to Appian AI agents and receive responses.

The AI application uses the available MCP tools to fulfill your requests. You do not need to know which specific tools to call, the AI application handles tool discovery and selection based on your natural language input.

Understand error messages

The following table describes common Model Context Protocol (MCP) error messages you may encounter:

Troubleshoot connection issues

If you cannot connect your AI application to Appian MCP Server via Model Context Protocol (MCP):

1. Verify the server URL matches the format <ENVIRONMENT_URL>/mcp.
2. Confirm the API key is correct and has not been regenerated since you received it.
3. Confirm Appian MCP Server is enabled by checking with your system administrator.
4. Restart your AI application after making configuration changes.
5. If the issue persists, contact your system administrator with the specific error message you are receiving.

If you are connected but cannot see an expected tool, contact your system administrator to verify that your account has the appropriate permissions and that the Appian developer has enabled the tool for MCP in the design object's properties.

Feedback