> This page is for Agent Studio. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.moveworks.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server. # Set Up a ServiceNow MCP Server with Subflows and Actions > **Controlled Availability** > > MCP Workspace is available to a limited set of customers. Moveworks is validating the experience and gathering feedback, so capabilities and limits may change. To request access, [register your interest](https://community.moveworks.com/p/mcp-workspace-controlled-availability). ServiceNow's MCP Server Console lets you turn existing **Subflows** and **Actions** into MCP tools and expose them from an MCP server on your instance. Once that server is connected to MCP Workspace, the assistant can call those tools on behalf of your employees. This is a good fit when you already have deterministic workflow logic in ServiceNow and want employees to use it from the assistant without rebuilding it in Agent Studio. This guide walks through the full setup end to end: 1. **Prepare** a Subflow or Action so ServiceNow allows it to be called by AI. 2. **Create tools and an MCP server** in ServiceNow's MCP Server Console. 3. **Create an OAuth inbound integration** so Moveworks can authenticate. 4. **Connect the server** in Moveworks MCP Workspace, test, and launch. > **ServiceNow's documentation is the source of truth** > > ServiceNow updates MCP Server Console regularly, so each ServiceNow step below links to the matching ServiceNow page. If what you see on your instance differs from this guide, follow ServiceNow's docs. Start with [Creating tools for a Model Context Protocol server](https://www.servicenow.com/docs/r/intelligent-experiences/creating-tools-mcp-server.html) for an overview. ## Before You Start ### Prerequisites **ServiceNow** * An instance on a release that includes MCP Server Console. We recommend **Australia Patch 3 or later**, with **MCP Server Console**. * Integration Hub, if your Subflows or Actions use spoke actions. * A user who can elevate to **security\_admin** (to create ACLs) and who holds **sn\_mcp\_server.admin** or **admin** (to create tools and servers), plus **oauth\_admin**, **mi\_admin**, or **admin** (to create the OAuth integration). **Moveworks** * MCP Workspace enabled for your organization. * Agent Studio admin access. ### Choose Which Subflows and Actions to Expose Not every Subflow or Action can become an MCP tool. Start with a small set that meets all of these: * **Synchronous.** Subflows and Actions with wait steps, asynchronous execution, or human intervention steps (such as approvals) can't be used as tools. See the prerequisites in ServiceNow's [Create a tool from a Subflow](https://www.servicenow.com/docs/r/intelligent-experiences/create-subflow-tool.html) and [Create a tool from an Action](https://www.servicenow.com/docs/r/intelligent-experiences/create-action-tool.html). * **Fast.** Moveworks tool calls time out after about 60 seconds. Avoid long-running logic. * **Supported input and output types.** To see the list of supported input types, open `sys_properties.list` and search for `sn_fd_genai.mcp_tools.compatibility.inputs`. See ServiceNow's [Check the compatibility of a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/check-compatibility-of-subflow.html). * **Net-new for the assistant.** Avoid exposing tools that duplicate something the assistant can already do (for example, an existing ServiceNow plugin). Overlap makes tool selection less predictable. See [Configure and Test MCP Workspace](/agent-studio/mcp-workspace/configure-and-test-mcp-workspace). ## Step 1: Prepare the Subflow or Action in ServiceNow Every Subflow or Action must pass three checks before MCP Server Console lets you add it as a tool: **security**, **data types**, and **execution behavior**. > **ServiceNow reference** > > [Create an AI ACL for a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/create-ai-acl.html) and [Check the compatibility of a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/check-compatibility-of-subflow.html) ### Publish the Subflow or Action 1. In ServiceNow, open **Workflow Studio**. 2. Open the Subflow or Action you want to expose. 3. Select **Test** and confirm it returns the expected outputs. 4. Select **Publish**. Publishing triggers ServiceNow's compatibility check, and you need the published internal name to create the ACL in the next step. ### Create an AI ACL ServiceNow uses a deny-by-default model for AI access. Each Subflow or Action needs an **AI ACL** with the **Invoked from AI** operation. A standard record ACL won't work. Follow ServiceNow's [Create an AI ACL for a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/create-ai-acl.html) for the current field values; the summary below reflects that page at the time of writing. 1. Elevate your role to **security\_admin** from the profile menu. 2. Make sure your application scope matches the scope of the Subflow or Action. 3. Open the Subflow or Action in Workflow Studio and select **Manage Security** in the upper right. You can also go to **All > Access Control (ACL)**. 4. Select **New** and fill in the fields below. 5. Select **Submit**. | Field | Value | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Type** | `flow_action` | | **Operation** | **Invoked from AI** (`invoke_from_ai`) | | **Name** | The scope-qualified internal name of your Subflow or Action, for example `global.check_supplier_risk`. You can find it from the three-dot menu in Workflow Studio after publishing. | | **Active** | Selected | | **Requires role** | A role held by the employees who should be able to use this tool. | > **Pick the ACL role carefully** > > With per-user OAuth, tools run as the signed-in employee. The ACL role you choose decides who can call the tool. If you require an admin-only role, regular employees will get empty results or errors. For how tool calls are authorized for human users versus autonomous agents, see the access control section of ServiceNow's [Creating tools for a Model Context Protocol server](https://www.servicenow.com/docs/r/intelligent-experiences/creating-tools-mcp-server.html). ### Check Compatibility After you publish and add the ACL, ServiceNow evaluates the Subflow or Action and records the result in a compatibility staging table. Follow the steps in ServiceNow's [Check the compatibility of a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/check-compatibility-of-subflow.html) to find your component. All three columns must be `true`: * `security_compatible` * `data_compatible` * `execution_compatible` ServiceNow checks security first. If `security_compatible` is `false`, the other two columns show N/A. Fix the ACL, then republish so the component is re-evaluated. ## Step 2: Create Tools and an MCP Server in ServiceNow > **ServiceNow reference** > > [Create a Model Context Protocol server](https://www.servicenow.com/docs/r/XRgEFx7nPN6ciT_BBIvnbg/a2CY_8UaP1y3J_5_ry5NCQ), [Creating tools for a Model Context Protocol server](https://www.servicenow.com/docs/r/intelligent-experiences/creating-tools-mcp-server.html), [Create a tool from a Subflow](https://www.servicenow.com/docs/r/intelligent-experiences/create-subflow-tool.html), and [Create a tool from an Action](https://www.servicenow.com/docs/r/intelligent-experiences/create-action-tool.html) ### Create the MCP Server 1. Go to **Admin > MCP Server Console**. 2. On the **Configuration** tab, select **Servers**, then select **Create server**. 3. Fill in the fields below. For the full field list, see ServiceNow's [Create a Model Context Protocol server](https://www.servicenow.com/docs/r/XRgEFx7nPN6ciT_BBIvnbg/a2CY_8UaP1y3J_5_ry5NCQ). | Field | Value | | --------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **Label** | A clear name, for example `HR Workflows`. The **Name** field is generated from this and becomes part of the server URL. | | **Application** | Your current application scope. Tools must be in the same scope as the server. | | **Short description** | What the server does and what kinds of tools it contains. | ### Add Tools from Your Subflows and Actions 1. In the **Tools** section of the server form, select **Add tools**. 2. Select **Create tool**, then choose **Subflow** or **Action**. 3. Fill in the tool fields below. ServiceNow documents these fields in [Create a tool from a Subflow](https://www.servicenow.com/docs/r/intelligent-experiences/create-subflow-tool.html) and [Create a tool from an Action](https://www.servicenow.com/docs/r/intelligent-experiences/create-action-tool.html). 4. Optional: In the **Tool inputs** section, turn off any inputs you don't want the assistant to set. Some required inputs can't be turned off. 5. Select **Create**. 6. Repeat for each Subflow or Action, then select the tools and select **Add**. 7. Back on the server form, select **Create** to activate the server. 8. Copy the **Server URL**. It looks like `https://.service-now.com/sncapps/mcp-server/mcp/`. You'll need it in Step 4. | Field | Value | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Subflow** or **Action** | The published Subflow or Action. It only appears here if it passed the compatibility checks in Step 1. | | **Label** | A short name for the tool. | | **Description** | What the tool does and when to use it. The assistant relies on this to pick the right tool. Be specific and action oriented. | | **Annotations** | Mark the tool as **read-only**, **idempotent**, **destructive**, or **open world** as appropriate. Moveworks uses these to decide whether to ask the employee before running the tool. | | **Required roles** | Optional. Roles allowed to use the tool. | > **Write descriptions for the assistant, not for admins** > > * ❌ "Supplier risk subflow" > * ✅ "Checks whether a supplier passes the company's risk compliance policy using its DUNS number. Returns pass or fail and the risk score. Use when someone asks if a supplier can be onboarded." > **Tools can be shared across servers** > > Editing a tool's name, description, or inputs changes it on every server that uses it. See [Creating tools for a Model Context Protocol server](https://www.servicenow.com/docs/r/intelligent-experiences/creating-tools-mcp-server.html). ## Step 3: Create an OAuth Inbound Integration in ServiceNow Moveworks connects to your ServiceNow MCP server with OAuth 2.0 Authorization Code. Each employee signs in with their own ServiceNow account, so their existing permissions apply. > **ServiceNow reference** > > [Create an OAuth inbound integration for an MCP client](https://www.servicenow.com/docs/r/intelligent-experiences/create-oauth-inbound-integration-mcp-client.html) 1. In **MCP Server Console**, select **Set up OAuth** in the banner. You can also go to **All > Machine Identity Console** and open the **Inbound integrations** tab. 2. Select **New integration**, then choose **OAuth - Authorization code grant**. 3. Fill in the fields below. 4. Select **Save**. If prompted to assign an auth scope, select **Skip for now**. 5. Copy the **Client ID** and **Client Secret** and store them securely. | Field | Value | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | For example, `Moveworks MCP OAuth` | | **Redirect URLs** | Your Moveworks callback URL. For the US data center, use `https://.moveworks.com/auth/oauthCallback`. For other data centers, see [OAuth 2.0 Authorization Code](/agent-studio/connectors/http-connectors/oauth-20-authorization-code). | | **Auth scope > Allow access only to APIs in selected scope** | Leave **cleared**. If selected, Moveworks can't fetch tools from the server. | | **Advanced options > Token Format** | **JWT** | | **Active** | Selected | > **Token Format must be JWT** > > ServiceNow MCP servers reject opaque tokens. This is the most common cause of authentication errors. > > Also, don't reuse integrations that share a server's name (with underscores). ServiceNow creates those for AI Control Tower monitoring. Both requirements come from ServiceNow's [Create an OAuth inbound integration for an MCP client](https://www.servicenow.com/docs/r/intelligent-experiences/create-oauth-inbound-integration-mcp-client.html). ## Step 4: Connect the Server in Moveworks > **Moveworks reference** > > [Connect and Manage Servers](/agent-studio/mcp-workspace/connect-and-manage-servers#connect-a-custom-server) ### Create an HTTP Connector 1. In **Agent Studio**, open **Connectors** and select **Create**. 2. Fill in the fields below, then select **Save**. | Field | Value | | ---------------------------------- | --------------------------------------------------------------- | | **Connector Name** | For example, `servicenow_mcp`. This can't be changed later. | | **Base URL** | `https://.service-now.com` | | **Auth Config** | OAuth2 | | **OAuth2 Grant Type** | Authorization Code Grant | | **Authorization URL** | `https://.service-now.com/oauth_auth.do` | | **Client ID** / **Client Secret** | From Step 3 | | **OAuth2 Token URL** | `https://.service-now.com/oauth_token.do` | | **PKCE** | PKCE using SHA256 code challenge | | **Authorization Code Grant Scope** | Leave blank unless your security team requires specific scopes. | ### Add the MCP Server 1. In **Agent Studio**, open **MCP Servers** and select **Create**. 2. Select **Custom Server**. 3. Enter a **name** and **description**. Use words employees would naturally say, and describe what the server can and can't do. The assistant uses these to decide when to use the server. 4. In the URL field, enter `https://.service-now.com` with no trailing slash. 5. In the **Path** field, enter `/sncapps/mcp-server/mcp/` from the Server URL you copied in Step 2. 6. Under the connector section, choose **Inherit from existing connector** and select the connector you just created. 7. Select **Authenticate** and sign in to ServiceNow. Select **Allow** when prompted. 8. In the **Tools** section, select **Preview Tools**. You should see the tools you created in Step 2. ### Set the Tool Approval Policy Moveworks applies one approval policy to all tools on a server: * **Follow server guidance** (default): Tools marked read-only, non-destructive, and not open world run without asking. Everything else asks the employee first. This is why the **Annotations** you set in Step 2 matter. * **Always ask user**: Every call asks first. Recommended for servers with tools that create or update records. * **Always allowed**: No approval prompts. Use only for trusted, read-only servers. ### Publish and Launch 1. Select **Publish**. 2. Make sure the server is **Enabled**. 3. In **Launch Configuration**, start with a small pilot audience. The first time an employee uses a ServiceNow tool, the assistant asks them to sign in to ServiceNow in the conversation. After that, it won't ask again. For more detail, see [Connect and Manage Servers](/agent-studio/mcp-workspace/connect-and-manage-servers). ## Step 5: Test End to End 1. Open the assistant as a user in your pilot audience. 2. Ask a request that should trigger one of your tools, for example: *"Can we onboard the supplier with DUNS number 123456789? Check if it passes our risk policy."* 3. The user should be asked to authenticate to ServiceNow. 4. Confirm the assistant calls the right tool, passes the right inputs, and returns the result. 5. Try a request that should **not** use the tool and confirm the assistant doesn't call it. 6. Review [MCP tool call logs](/agent-studio/mcp-workspace/view-mcp-tool-call-logs) to see the inputs and outputs of each call. > **Tip** > > When you change tools in ServiceNow (add, remove, or edit descriptions), select **Preview Tools** again in Agent Studio to refresh the list. ## Troubleshooting | Symptom | What to check | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Subflow or Action doesn't appear when creating a tool | Confirm it's published, has an AI ACL with the **Invoked from AI** operation, and shows `true` for all three compatibility columns. Confirm it's in the same application scope as the server. If it uses wait steps, approvals, or unsupported input types, it can't be used. See ServiceNow's [Check the compatibility of a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/check-compatibility-of-subflow.html) and [Create an AI ACL for a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/create-ai-acl.html). | | Authentication fails or Preview Tools returns an auth error | Confirm **Token Format** is **JWT** on the OAuth integration, the redirect URL matches your Moveworks data center exactly, and **PKCE using SHA256 code challenge** is selected on the connector. See ServiceNow's [Create an OAuth inbound integration for an MCP client](https://www.servicenow.com/docs/r/intelligent-experiences/create-oauth-inbound-integration-mcp-client.html). | | Preview Tools returns no tools | Confirm the OAuth integration is **not** limited to a selected API scope, the **Path** matches the server name exactly, and the server is active (not a draft). | | Tool works for admins but returns empty results for employees | Check the **Requires role** on the AI ACL and the tool's **Required roles**. Employees need those roles in ServiceNow. Denied calls can return empty results instead of an error. See the access control section of ServiceNow's [Creating tools for a Model Context Protocol server](https://www.servicenow.com/docs/r/intelligent-experiences/creating-tools-mcp-server.html). | | Tool call times out | Tool calls are limited to about 60 seconds. Simplify the Subflow or move slow steps out of it. | | Assistant picks a different plugin or tool | Sharpen the tool description in ServiceNow and remove overlap with existing plugins. See [Configure and Test MCP Workspace](/agent-studio/mcp-workspace/configure-and-test-mcp-workspace). | For more, see [Limitations and Troubleshooting](/agent-studio/mcp-workspace/limitations-and-troubleshooting). ## Related ServiceNow Docs * [Creating tools for a Model Context Protocol server](https://www.servicenow.com/docs/r/intelligent-experiences/creating-tools-mcp-server.html) * [Create a Model Context Protocol server](https://www.servicenow.com/docs/r/XRgEFx7nPN6ciT_BBIvnbg/a2CY_8UaP1y3J_5_ry5NCQ) * [Create a tool from a Subflow](https://www.servicenow.com/docs/r/intelligent-experiences/create-subflow-tool.html) * [Create a tool from an Action](https://www.servicenow.com/docs/r/intelligent-experiences/create-action-tool.html) * [Create an AI ACL for a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/create-ai-acl.html) * [Check the compatibility of a Subflow or Action](https://www.servicenow.com/docs/r/intelligent-experiences/check-compatibility-of-subflow.html) * [Create an OAuth inbound integration for an MCP client](https://www.servicenow.com/docs/r/intelligent-experiences/create-oauth-inbound-integration-mcp-client.html)