# 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.

{% hint style="info" %}
The MCP Server does not replace WorkflowGen permissions. Final authorization for each operation is still enforced by WorkflowGen and the WorkflowGen Service Facade.
{% endhint %}

## Technical requirements

The MCP Server is a WorkflowGen Node.js-based web application hosted under IIS with iisnode. The following components are required:

* [Node.js v22.22.2 LTS](https://nodejs.org/download/release/v22.22.2/)
* [iisnode](https://github.com/Azure/iisnode/releases/tag/v0.2.21)
* [IIS URL Rewrite](https://www.iis.net/downloads/microsoft/url-rewrite)
* [Visual C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads) (if required by the server configuration for the `edge` and `edge-js` libraries)
* HTTPS for OAuth-enabled MCP clients

### Endpoints

The MCP Server is mounted under `/wfgen/mcp` .

<table><thead><tr><th valign="top">Endpoint</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>GET /health</code></td><td valign="top">Health check endpoint</td></tr><tr><td valign="top"><code>GET /.well-known/oauth-protected-resource</code></td><td valign="top">OAuth protected resource metadata</td></tr><tr><td valign="top"><code>GET /.well-known/oauth-authorization-server</code></td><td valign="top">OAuth authorization server metadata</td></tr><tr><td valign="top"><code>GET /jwks</code></td><td valign="top">JSON Web Key Set used to validate MCP access tokens</td></tr><tr><td valign="top"><code>POST /register</code></td><td valign="top">Dynamic client registration endpoint</td></tr><tr><td valign="top"><code>GET /authorize</code></td><td valign="top">OAuth authorization endpoint</td></tr><tr><td valign="top"><code>GET /authorize/resume</code></td><td valign="top">OAuth authorization resume endpoint used after WorkflowGen browser authentication</td></tr><tr><td valign="top"><code>GET /auth-bridge</code></td><td valign="top">Browser bridge endpoint used by the WorkflowGen portal after authentication</td></tr><tr><td valign="top"><code>POST /token</code></td><td valign="top">OAuth token endpoint</td></tr><tr><td valign="top"><code>POST /revoke</code></td><td valign="top">OAuth token revocation endpoint</td></tr><tr><td valign="top"><code>POST /</code></td><td valign="top">MCP transport endpoint</td></tr></tbody></table>

The MCP transport uses `POST /` under the MCP base URL.

### OAuth flow

The standard OAuth connection flow is:

1. The MCP client discovers the protected resource metadata.
2. The client reads the authorization server metadata.
3. The client registers itself with `POST /register`.
4. The client starts the browser authorization flow with `GET /authorize`.
5. WorkflowGen authenticates the user through the configured WorkflowGen OIDC or SAML authentication flow.
6. WorkflowGen redirects through the MCP browser bridge.
7. The MCP server resumes the OAuth authorization transaction.
8. The client exchanges the authorization code with `POST /token`.
9. 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.&#x20;

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...`).&#x20;

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:

<table><thead><tr><th valign="top">Scope</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>mcp:read</code></td><td valign="top">Read/query tools</td></tr><tr><td valign="top"><code>mcp:write</code></td><td valign="top">End-user mutation tools, such as creating requests, completing actions, comments, favorites, and delegations</td></tr><tr><td valign="top"><code>mcp:process_admin</code></td><td valign="top">Process and process-participant management tools for process managers and folder managers</td></tr><tr><td valign="top"><code>mcp:admin</code></td><td valign="top">Global/system administration tools</td></tr></tbody></table>

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:

```xml
<add key="McpAllowedScopes" value="mcp:read mcp:write mcp:process_admin mcp:admin" />
```

If the key is missing or empty, the server falls back to:

```
mcp:read
```

Administrators can make the MCP deployment read-only by setting:

```xml
<add key="McpAllowedScopes" value="mcp:read" />
```

### 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.

{% hint style="info" %}
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.
{% endhint %}

### User types

<table><thead><tr><th valign="top">WorkflowGen user type</th><th valign="top">Visible MCP tools when allowed by configuration and granted to the connector</th></tr></thead><tbody><tr><td valign="top">Basic user</td><td valign="top">Read and write tools</td></tr><tr><td valign="top">Process manager / folder manager</td><td valign="top">Read, write, and process administration tools</td></tr><tr><td valign="top">WorkflowGen administrator</td><td valign="top">All allowed MCP tools, including global administration tools</td></tr></tbody></table>

### 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.&#x20;

{% hint style="warning" %}
Use an enabled production configuration only when WorkflowGen uses OIDC or SAML authentication. Otherwise, keep `OAuthServerEnabled=false`.
{% endhint %}

#### 📌 Example of a production configuration

```xml
<add key="OAuthServerEnabled" value="true" />
<add key="OAuthServerKeyEncryptionKey" value="<32-byte base64-or-base64url random key>" />
<add key="OAuthServerBridgeTokenSigningSecret" value="<strong random secret>" />
<add key="OAuthServerAccessTokenLifetimeSeconds" value="3600" />
<add key="OAuthServerAuthorizationCodeLifetimeSeconds" value="600" />
<add key="OAuthServerRefreshTokenLifetimeSeconds" value="7776000" />
<add key="McpResourceUri" value="" />
<add key="McpAllowedScopes" value="mcp:read mcp:write mcp:process_admin mcp:admin" />
<add key="McpDiagnosticLogLevel" value="INFO" />
```

#### 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:

```xml
<add key="ApplicationUrl" value="https://mycompany.com/wfgen" />
<add key="McpResourceUri" value="" />
```

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:

```xml
<add key="OAuthAllowLocalhostRedirects" value="true" />
<add key="McpDevAuthBridgeMode" value="fixeduser" />
<add key="McpDevAuthBridgeUsername" value="<local-test-workflowgen-username>" />
```

{% hint style="warning" %}
Do not enable the fixed-user development bridge in production.
{% endhint %}

### Database objects

WorkflowGen MCP OAuth uses the following database tables:

* `OAUTH_CLIENT`
* `OAUTH_TXN`
* `OAUTH_CODE`
* `OAUTH_REFRESH_TOKEN`
* `OAUTH_SIGNING_KEY`

These tables are created by the WorkflowGen database update scripts.

### Smoke tests

After configuring MCP, verify that:

1. The health endpoint returns a successful response: `https://<workflowgen-url>/wfgen/mcp/health`.
2. The protected resource metadata endpoint returns JSON: `https://<workflowgen-url>/wfgen/mcp/.well-known/oauth-protected-resource`.
3. The authorization server metadata endpoint returns JSON: `https://<workflowgen-url>/wfgen/mcp/.well-known/oauth-authorization-server`.
4. A supported MCP client can connect to: `https://<workflowgen-url>/wfgen/mcp`.
5. 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.workflowgen.com/integration/10.3/mcp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.