MCP Server
Overview
The WorkflowGen MCP Server exposes WorkflowGen tools through the Model Context Protocol (MCP), allowing compatible AI clients and assistants to interact with WorkflowGen on behalf of an authenticated WorkflowGen user.
The standard MCP endpoint is https://<workflowgen-url>/wfgen/mcp (e.g. https://mycompany.com/wfgen/mcp).
The MCP Server uses OAuth for supported remote MCP clients. During connection, the MCP client starts a browser-based authorization flow. WorkflowGen authenticates the user through the configured OIDC or SAML authentication flow, then issues MCP OAuth tokens for the client.
MCP OAuth for supported MCP clients requires WorkflowGen OIDC or SAML authentication. Other WorkflowGen authentication modes are not supported as MCP browser login sources.
The MCP Server does not replace WorkflowGen permissions. Final authorization for each operation is still enforced by WorkflowGen and the WorkflowGen Service Facade.
Technical requirements
The MCP Server is a WorkflowGen Node.js-based web application hosted under IIS with iisnode. The following components are required:
Visual C++ Redistributable (if required by the server configuration for the
edgeandedge-jslibraries)HTTPS for OAuth-enabled MCP clients
Endpoints
The MCP Server is mounted under /wfgen/mcp .
GET /health
Health check endpoint
GET /.well-known/oauth-protected-resource
OAuth protected resource metadata
GET /.well-known/oauth-authorization-server
OAuth authorization server metadata
GET /jwks
JSON Web Key Set used to validate MCP access tokens
POST /register
Dynamic client registration endpoint
GET /authorize
OAuth authorization endpoint
GET /authorize/resume
OAuth authorization resume endpoint used after WorkflowGen browser authentication
GET /auth-bridge
Browser bridge endpoint used by the WorkflowGen portal after authentication
POST /token
OAuth token endpoint
POST /revoke
OAuth token revocation endpoint
POST /
MCP transport endpoint
The MCP transport uses POST / under the MCP base URL.
OAuth flow
The standard OAuth connection flow is:
The MCP client discovers the protected resource metadata.
The client reads the authorization server metadata.
The client registers itself with
POST /register.The client starts the browser authorization flow with
GET /authorize.WorkflowGen authenticates the user through the configured WorkflowGen OIDC or SAML authentication flow.
WorkflowGen redirects through the MCP browser bridge.
The MCP server resumes the OAuth authorization transaction.
The client exchanges the authorization code with
POST /token.The client calls MCP tools with
Authorization: Bearer <access_token>.
After a successful sign-in, the browser is redirected to the MCP client's registered callback URL so the client can receive the OAuth authorization code.
Depending on the identity provider, browser, operating system, and MCP client, the browser tab may close automatically, prompt to open the MCP client, or remain open on a page (e.g. Working...).
If the MCP client shows the connector as connected, the user can safely close the remaining browser tab.
Scopes & tool visibility
WorkflowGen MCP uses four OAuth scopes:
mcp:read
Read/query tools
mcp:write
End-user mutation tools, such as creating requests, completing actions, comments, favorites, and delegations
mcp:process_admin
Process and process-participant management tools for process managers and folder managers
mcp:admin
Global/system administration tools
Tool visibility depends on the deployment-level scope ceiling configured with McpAllowedScopes and the authenticated WorkflowGen user's coarse user type.
The default shipped configuration allows the full MCP tool surface:
If the key is missing or empty, the server falls back to:
Administrators can make the MCP deployment read-only by setting:
Changing granted scopes for an existing connector
The scopes granted to a connector are fixed for that OAuth authorization. If a user first grants only mcp:read and later wants to grant mcp:write, mcp:process_admin, or mcp:admin, the MCP client must start a new OAuth authorization flow so WorkflowGen can issue a new token with the broader granted scope.
In practice:
Use the MCP client's Authenticate, Reconnect, or Reauthorize action if it starts a fresh browser authorization flow.
If the client doesn't prompt for authorization again, remove the connector and add it again.
WorkflowGen user role alone does not widen an already-issued token. A WorkflowGen administrator who granted only mcp:read will still receive 403 insufficient_scope for write or admin operations until the connector is re-authorized with the additional scopes.
User types
Basic user
Read and write tools
Process manager / folder manager
Read, write, and process administration tools
WorkflowGen administrator
All allowed MCP tools, including global administration tools
Configuration
The main MCP settings can be managed under MCP Server on the Integration tab of the WorkflowGen Administration Module Configuration panel.
The Configuration panel writes the corresponding OAuthServer* and Mcp* application settings in the WorkflowGen web.config file under \wfgen. For scripted deployments, administrators can also set the same values directly in the web.config file.
Use an enabled production configuration only when WorkflowGen uses OIDC or SAML authentication. Otherwise, keep OAuthServerEnabled=false.
📌 Example of a production configuration
Key encryption key
OAuthServerKeyEncryptionKey must be a 32-byte base64 or base64url random key. The MCP server uses it to encrypt and decrypt the private signing JWK stored in the OAUTH_SIGNING_KEY database table.
Keep this value stable after MCP has been enabled. If it's changed after an active signing key already exists, token issuance can fail because the MCP server can no longer decrypt the stored private signing key.
This value is masked In the Configuration panel. Leaving the field blank keeps the existing value. The Generate button can be used during initial setup or intentional key rotation/reset.
Bridge token signing secret
OAuthServerBridgeTokenSigningSecret is used to sign short-lived browser bridge tokens during OAuth authorization.
This value is masked In the Configuration panel. Leaving the field blank keeps the existing value. The Generate button creates a new secret.
Resource URI
By default, the MCP public resource URI is derived from ApplicationUrl + "/mcp".
For a standard WorkflowGen URL:
The effective MCP resource URI is https://mycompany.com/wfgen/mcp.
Set McpResourceUri only when the public MCP URL must be overridden while still using an MCP endpoint whose path ends with /mcp.
McpResourceUri should normally be ApplicationUrl + "/mcp". If it's explicitly overridden, it must be an absolute HTTPS URL without a query string or fragment, and its path must end with /mcp. Custom MCP app names such as /custom-mcp are not supported.
If a deployment uses a custom ApplicationUrl path such as https://host/custom, the MCP resource URI becomes https://host/custom/mcp. In that case, administrators must adapt the root web.config URL Rewrite rules so the corresponding /.well-known/.../custom/mcp metadata URLs and /custom/oauth-auth-bridge browser bridge URL are routed correctly.
Diagnostic logging
McpDiagnosticLogLevel supports OFF, ERROR, WARN, INFO, and DEBUG. The default is INFO.
Local development settings
The following settings are for local/test environments only. They are web.config-only settings and aren't shown in the user-facing Configuration panel UI:
Do not enable the fixed-user development bridge in production.
Database objects
WorkflowGen MCP OAuth uses the following database tables:
OAUTH_CLIENTOAUTH_TXNOAUTH_CODEOAUTH_REFRESH_TOKENOAUTH_SIGNING_KEY
These tables are created by the WorkflowGen database update scripts.
Smoke tests
After configuring MCP, verify that:
The health endpoint returns a successful response:
https://<workflowgen-url>/wfgen/mcp/health.The protected resource metadata endpoint returns JSON:
https://<workflowgen-url>/wfgen/mcp/.well-known/oauth-protected-resource.The authorization server metadata endpoint returns JSON:
https://<workflowgen-url>/wfgen/mcp/.well-known/oauth-authorization-server.A supported MCP client can connect to:
https://<workflowgen-url>/wfgen/mcp.After login, the MCP client can list and call tools according to the authenticated WorkflowGen user's permissions.
Troubleshooting
The MCP client cannot discover OAuth metadata
Verify that IIS URL Rewrite is installed and that the root web.config contains the MCP well-known metadata rewrite rules.
The browser authorization flow returns to a 404 page
Verify that the root web.config contains the rewrite rule for /wfgen/oauth-auth-bridge.
The browser tab stays open after sign-in
After a successful MCP OAuth sign-in, WorkflowGen redirects the browser to the MCP client's callback URL. At that point, the final page is controlled by the MCP client, the identity provider, the browser, and the operating system protocol-handler behavior. If the MCP client shows the connector as connected, the user can safely close the remaining browser tab.
Token issuance fails after changing OAuthServerKeyEncryptionKey
Restore the previous OAuthServerKeyEncryptionKey value and recycle the IIS application pool. If the previous key is permanently lost, schedule a maintenance window to generate a fresh MCP signing key.
A tool appears but fails with an authorization error
This can be normal. MCP tool visibility is coarse. WorkflowGen still checks the exact operation, user, process, folder, request, action, and resource permissions through the Service Facade.
Last updated