Skip to main content

Expose a web tool as a custom MCP tool

You can extend the GIS capabilities available to AI applications by exposing a web tool, which is a geoprocessing (GP) service shared to your portal, as a custom MCP tool.

Each web tool item in your portal that is tagged for MCP appears as one custom MCP tool in the default catalog. The tool is named after the service and provides access to its tasks. A service that contains multiple tasks is represented by a single custom MCP tool. The default catalog always includes the supporting Get GP Task Definition and Get GP Task Job Status tools, whether or not any web tool items are tagged for MCP. Starting with ArcGIS Enterprise 12.2, an administrator can also include the web tool in a custom catalog.

This approach allows AI applications to use your organization's geospatial workflows without custom MCP code.

Both synchronous and asynchronous execution are supported.

Before you begin

Verify the following:

  • The GP service is published and shared to your portal as a web tool.

  • You have the required privileges to update the web tool item.

  • MCP Services for ArcGIS Enterprise are installed. For ArcGIS Enterprise 12.2 and later, external AI client access is also enabled.

  • The intended user or credential has permission to access and run the web tool.

Test the web tool on its own before you expose it through MCP. Use representative inputs, and confirm that its outputs match the intended workflow.

Describe the web tool and its tasks

Clear descriptions help an AI application decide whether a web tool is appropriate and build valid requests.

Prepare descriptions at three levels:

Level Information to provide
Service Its purpose, the tasks it contains, and what each task does.
Task Its behavior, expected results, and appropriate uses.
Parameter Its meaning and examples of valid values.

Also explain units, accepted coordinate systems, required and optional inputs, and any limits that affect execution. Identify operations that create or modify data, so that users understand the effect of running them.

For example, if a numeric parameter represents a measurement but does not include its own units, state the unit that the task assumes. If a task accepts a category code, describe the valid codes instead of relying on the application to infer their meaning.

Keep descriptions consistent with the published service definition. For broader guidance, see Prepare your content for use with MCP.

Tag the web tool

To expose the web tool as a custom MCP tool, add the mcp tag to the web tool item in your portal. For instructions on adding tags, see Configure item details and settings.

Note:

The default catalog includes up to 20 web tools. If more web tool items are tagged for MCP, only the 20 most recently modified items are included. Custom catalogs have no limit on web tools, so for workflows that need a specific web tool, include it in a custom catalog.

Verify the custom MCP tool

Web tool items tagged for MCP are cached, so a newly tagged web tool may take up to one minute to appear.

Connect an MCP client to the default catalog and review the available tools. If the client requires it, refresh its tool list or reconnect.

Confirm that a tool named after the web tool's GP service appears. The tool name is the service name with leading and trailing spaces removed and the remaining spaces replaced with underscores (_). If another tool in the catalog has the same name, the web tool may be hidden. For details, see Tool name conflicts.

Then test a request that matches the service's purpose, using inputs with known expected results.

For example, if your service identifies facilities within a specified distance, test it with a known location and distance. Compare the output of the MCP workflow with the output of running the same web tool directly.

Where the client shows tool activity, review it.

Note:

A natural-language response alone does not prove that the intended service ran successfully.

Understand task execution

An application uses Get GP Task Definition to inspect a task's schema. It then calls the custom MCP tool with the following arguments:

  • taskUrl—The URL of the task to run.

  • inputs—An object that contains the task's input parameter values.

  • inputSchemaField—The name of a field from the task's input schema. This confirms that the application called Get GP Task Definition before it ran the task.

The task runs in one of the following ways:

  • Synchronous execution—Returns results in the response.

  • Asynchronous execution—Returns a jobId. The application does not monitor the job on its own. To check progress or get the results, prompt the application to check the job status. It then uses Get GP Task Job Status with the jobId. Results are available only after the job completes.

Include the tool in a custom catalog

Starting with ArcGIS Enterprise 12.2, an administrator can include web tools tagged for MCP as custom MCP tools in a custom catalog for a particular workflow.

When you add the web tool to a custom catalog, the supporting Get GP Task Definition and Get GP Task Job Status tools are included automatically. Test the complete workflow through the custom catalog before you share it with its intended users.

For instructions, see Manage MCP catalogs.

Remove the tool from a catalog

A web tool is removed from the default catalog automatically when either of the following happens:

  • The mcp tag is removed from the web tool item.

  • The web tool item is deleted from your portal.

The change may take up to one minute to be reflected.

The default catalog continues to include Get GP Task Definition and Get GP Task Job Status. In a custom catalog, these tools are included only while the catalog contains at least one custom MCP tool from a web tool.

Custom catalogs are managed separately. To remove the web tool from a custom catalog, an administrator must edit the catalog and remove the tool. For instructions, see Edit a custom catalog.

Maintain and troubleshoot the tool

Retest the MCP workflow after you change task parameters, outputs, or service behavior. Update the descriptions to reflect those changes.

If the tool is unavailable or execution fails, check the following:

  • Whether the web tool item has the mcp tag

  • Whether the client is connected to the intended catalog

  • Whether the user or credential has permission to run the web tool

  • Whether the GP service is available

  • Whether another tool in the catalog has the same name

  • Whether the submitted inputs match the task definition

For diagnostic guidance, see Troubleshoot MCP for ArcGIS Enterprise.