Getting Started with WorkflowGen MCP Server 1.0.0

Development Integration
1

Overview

Audience: WorkflowGen administrators and integration developers

WorkflowGen MCP Server 1.0.0 is available as a supported production integration with:

It enables compatible AI clients—including Claude and the Codex app—to access WorkflowGen operations through the Model Context Protocol (MCP).

The MCP client acts on behalf of an authenticated WorkflowGen user. Its access remains controlled by the deployment’s allowed scopes, the scopes granted to the connection, and the user’s WorkflowGen role and permissions.

MCP access does not bypass WorkflowGen authorization.

This article explains how to enable MCP, connect a client, and verify access. Installation and upgrade procedures remain covered by the official guides.

What can WorkflowGen MCP do?

Depending on the user’s permissions, an MCP client can help users:

  • identify their WorkflowGen profile and available capabilities;
  • list requests and actions;
  • launch requests;
  • complete, assign, or cancel actions;
  • add comments and manage attachments;
  • manage favorites and delegations;
  • query directories, users, participants, applications, and global lists;
  • perform process-management operations;
  • import and export complete process definitions using XPDL or JPDL;
  • import and export WorkflowGen applications and global lists;
  • perform administrative operations when authorized.

WorkflowGen MCP Server 1.0.0 provides 97 tools in total. Clients should discover the tools available to the current connection rather than assume that every tool is visible to every user.

Requirements

WorkflowGen installation

Use WorkflowGen 9.7.0 or 10.4.0 with the Portal and MCP components from the same installation package. Do not combine Portal assemblies from one version with MCP files from another version.

For existing installations, follow the applicable upgrade guide before enabling MCP:

In particular, complete the database updates and merge the supplied MCP configuration as directed by the guide.

WorkflowGen authentication

MCP OAuth browser authentication requires the main WorkflowGen site to use:

  • OpenID Connect (OIDC); or
  • SAML.

Other WorkflowGen authentication modes cannot be used as MCP OAuth browser-login sources.

HTTPS and client compatibility

The MCP endpoint must use HTTPS.

For a standard installation under /wfgen, use:

https://<workflowgen-host>/wfgen/mcp

For an installation deployed at the web root, use:

https://<workflowgen-host>/mcp

Use an MCP client that supports Streamable HTTP and the server’s OAuth authorization flow.

Runtime

WorkflowGen’s Node.js applications require:

  • Node.js 24.19.0 or later in the Node.js 24 release line;
  • iisnode 0.2.26 for IIS deployments.

Refer to the installation or upgrade guide for runtime preparation.

Enable MCP in WorkflowGen

After installing or upgrading WorkflowGen, open:

Administration > Configuration > Integration

Configure the OAuth Server section:

  • Ensure the OAuth server key-encryption key and bridge-token signing secret are configured. Generate them when setting up OAuth for the first time.
  • Enable the OAuth server.
  • Review the access-token, authorization-code, and refresh-token lifetimes.

For an existing OAuth installation, preserve the current secrets. Do not generate replacements simply because you are upgrading. Changing the key-encryption key can prevent the server from reading its stored signing key.

Then configure the MCP Server section:

  • Leave the MCP resource URI empty for a standard deployment.
  • Select the scopes the deployment is allowed to expose.
  • Keep the diagnostic log level at INFO for normal operation.

When the MCP resource URI is empty, WorkflowGen derives it from the configured ApplicationUrl.

For example:

ApplicationUrl: https://workflow.example.com/wfgen
MCP endpoint:   https://workflow.example.com/wfgen/mcp

Set an explicit MCP resource URI only when the public MCP address differs from ApplicationUrl + "/mcp". It must be an absolute HTTPS URL ending in /mcp, without a query string or fragment.

Verify the endpoint

Open the health endpoint:

https://<workflowgen-host>/wfgen/mcp/health

A healthy server returns a response containing:

{
  "status": "ok",
  "app": "workflowgen-mcp"
}

You can also verify the OAuth protected-resource metadata:

https://<workflowgen-host>/wfgen/mcp/.well-known/oauth-protected-resource

The resource URL, authorization server, and supported scopes should match the deployment.

For a web-root installation, omit /wfgen from these examples.

A successful health check confirms that MCP is responding; it does not verify the complete OAuth login or access to WorkflowGen data. Complete a client connection and try the identity prompt below.

Connect Claude

In Claude:

  1. Open the Connectors area.

  2. Add a custom remote MCP connector.

  3. Enter the WorkflowGen MCP URL:

    https://<workflowgen-host>/wfgen/mcp

  4. Connect and sign in through the WorkflowGen OIDC or SAML login page.

  5. Review and authorize the requested scopes.

  6. Return to Claude and enable the connector for the conversation.

For an organization-managed account, an owner may need to add the connector before members can connect individually.

Claude’s remote connectors reach MCP from Anthropic’s cloud infrastructure, including when used through Claude Desktop or Cowork. Access from your own browser alone is therefore insufficient: the endpoint must also be reachable from that service under your organization’s network policy. See Claude’s custom-connector documentation for current setup and network requirements.

Try:

Who am I in WorkflowGen, and what can I do here?

Claude should identify the authenticated WorkflowGen user and summarize the operations available to the connection.

Connect the Codex app

In the Codex app:

  1. Open the MCP server settings and add a server.

  2. Give it a recognizable name, such as workflowgen.

  3. Select Streamable HTTP and enter:

    https://<workflowgen-host>/wfgen/mcp

  4. Save the server and restart the connection if prompted.

  5. Select Authenticate.

  6. Sign in through the WorkflowGen OIDC or SAML login page and authorize the connection.

  7. Return to Codex after authentication completes.

Client interfaces can change; see the official MCP connection documentation for current instructions.

Try:

Who am I in WorkflowGen?

Native clients such as Codex use a loopback OAuth callback. WorkflowGen permits these callbacks when OAuthServerAllowLocalhostRedirects is enabled. This permits HTTP callbacks only for loopback addresses such as localhost, 127.0.0.1, and [::1]; it does not permit arbitrary non-HTTPS redirects.

Scopes and tool visibility

WorkflowGen MCP uses four cumulative scopes:

  • mcp:read — read and query operations;
  • mcp:write — standard user changes;
  • mcp:process_admin — process-management operations;
  • mcp:admin — system-administration operations.

Tool discovery is filtered by:

  1. the deployment’s allowed scopes;
  2. the scopes granted during OAuth authorization;
  3. the authenticated user’s WorkflowGen role.

When a tool is called, WorkflowGen also checks whether the user is authorized to perform that operation on the requested resource.

With all scopes enabled and granted, these representative profiles expose:

WorkflowGen profile Visible tools
Basic user 35
Global-list manager 40
Process or folder manager 63
WorkflowGen administrator 97

These counts describe MCP Server 1.0.0. They are not a guarantee that every operation will succeed for every resource.

For a read-only deployment, expose only:

mcp:read

If scopes are expanded later, existing tokens do not automatically gain the additional permissions. Start a new OAuth authorization through the client’s reauthorization or reconnection option. Refreshing an existing token does not expand its scopes.

Suggested prompts

General user

Who am I in WorkflowGen, and what can I do here?

List my current WorkflowGen actions and summarize what needs my attention.

Show me the processes I can launch.

Help me prepare a simple approval request. Show me the details before launching it.

Process manager

What process-management operations can I perform through this connection?

Export this process definition as JPDL and summarize its activities and transitions.

Administrator

Summarize my WorkflowGen administrative capabilities through this MCP connection.

List the available WorkflowGen applications and global lists.

Always review important changes before asking an AI client to execute them, particularly administrative operations, process imports, and full-definition replacements.

Process-definition support

MCP Server 1.0.0 supports complete process-definition import and export in:

  • XPDL using .xml files;
  • JPDL using UTF-8 JSON files with the .json extension.

JPDL uses snake_case property names. The .jpdl extension is not supported.

Creating a new process version is different from creating an independent process copy. A new version based on an existing process remains in the same process family and inherits its folder. When using create_process to create a version, omit a replacement name unless you intend to rename the entire process family.

Granular editing of individual activities, transitions, data, parameters, or forms is not part of MCP Server 1.0.0. Use complete XPDL or JPDL import and export for process-definition changes, subject to WorkflowGen’s permissions and process-status restrictions.

Security and operational notes

  • Grant only the scopes users need, and review the AI client’s requests before approving consequential changes.
  • Apply your organization’s AI-service and data-handling policies to information retrieved through MCP.
  • Protect and securely back up the OAuth key-encryption key and bridge-token signing secret.
  • Use different secrets for production and non-production environments.
  • Keep the key-encryption key stable. Changing or losing it can make the stored OAuth signing key unreadable and prevent token issuance.
  • Use the production MCP configuration supplied with the applicable WorkflowGen package.
  • Keep the MCP Node.js process count at 1 and the MCP IIS application pool’s Maximum Worker Processes setting at 1.
  • Do not expose the MCP iisnode diagnostic directory through HTTP.
  • Diagnostic logs may contain usernames, user identifiers, OAuth client identifiers, request paths, and failure details. Apply appropriate access and retention controls.
  • Use INFO logging normally and enable DEBUG only for a limited investigation.

Follow the official deployment guides for the complete production configuration.

Troubleshooting

The connector cannot reach MCP

Check that:

  • the endpoint URL and deployment path are correct;
  • HTTPS is reachable from the system making the MCP connection;
  • the MCP IIS application is installed and configured according to the guide;
  • firewall or allow-list rules permit the required access;
  • the request uses a hostname configured through ApplicationUrl or the MCP resource URI.

For Claude remote connectors, check connectivity from Anthropic’s service—not only from the user’s workstation.

Health works, but OAuth discovery fails

Check that:

  • the WorkflowGen configuration includes the MCP OAuth rewrite rules supplied with the package;
  • the rules match the deployment path;
  • the IIS URL Rewrite module is installed.

Refer to the upgrade guide for the required configuration changes.

The browser opens, but authorization fails

Check that:

  • the main WorkflowGen site uses OIDC or SAML;
  • Portal and MCP files come from the same WorkflowGen package;
  • the MCP production configuration was merged correctly during the upgrade;
  • the WorkflowGen authentication module is active;
  • the OAuth server key and bridge-token signing secret are configured.

If authorization was interrupted by a deployment or application-pool recycle, start a fresh authorization after deployment completes.

Codex does not authenticate

Check that:

  • the MCP server uses Streamable HTTP;
  • the URL ends with /mcp;
  • localhost OAuth redirects are enabled;
  • a manually configured bearer token is not overriding the intended OAuth connection.

If an earlier authorization is being reused, use the client’s reauthorization option. If necessary, remove and recreate the connection, then sign in again.

The user sees fewer tools than expected

Check:

  • the deployment’s allowed scopes;
  • the scopes granted to the connector;
  • the user’s WorkflowGen role;
  • whether a new authorization was completed after a scope change;
  • whether the client has refreshed its discovered tools.

Releases and documentation

WorkflowGen MCP Server 1.0.0 is included with:

Upgrade procedures:

Refer to the official WorkflowGen installation, upgrade, integration, and technical guides for authoritative deployment procedures and the complete configuration reference.

WorkflowGen CLI 2.0.0: Work with WorkflowGen from Your Terminal