ArcGIS Enterprise MCP API Reference (ArcGIS Enterprise 11.1, 11.3, 11.5, 12.1 and 12.2)

The ArcGIS Enterprise MCP API lets you build custom Model Context Protocol (MCP) tools in Java and host them in ArcGIS Enterprise, where MCP clients and AI agents can discover and call them.

A custom tool is a class that implements IMCPTool. It is packaged with its dependencies into a .mcp file and deployed to ArcGIS Enterprise.

Supported releases

The public API is the same in all supported releases. Build each tool with the JDK of the release you deploy it to.

ArcGIS Enterprise releases and JDK versions
ArcGIS EnterpriseMaven artifact versionJDK
12.212.2.021
12.112.1.017
11.511.5.017
11.311.3.017
11.111.1.011

All releases apply to ArcGIS Enterprise on Windows and Linux. ArcGIS Enterprise on Kubernetes supports custom MCP tools in 12.2 and later only.

Getting started

  1. Install the mcp-api and mcp-api-archetype artifacts for your release into your local Maven repository with the install-maven-artifacts script from the arcgis-enterprise-mcp-resources repository.
  2. Generate a tool project from mcp-api-archetype. The project contains a tool class, a test, and the build configuration that produces the .mcp file.
  3. Implement the tool: set its name, title, summary and description, define its input and output schemas, and write execute.
  4. Build the project with mvn package to create the .mcp file.
  5. Deploy the .mcp file. The steps differ between ArcGIS Enterprise 12.2 and later and earlier releases; see docs/deploy-mcp-tools.md in the arcgis-enterprise-mcp-resources repository. Deployed tools are available in the default MCP catalog. In ArcGIS Enterprise 12.2 and later, administrators can also add them to custom catalogs; see Manage MCP catalogs.

A .mcp file must contain exactly one tool. If META-INF/services/com.esri.arcgis.mcp.catalog.mcp.api.tools.IMCPTool lists more than one class, the build fails.

Tool lifecycle

  1. init is called once, after the tool is loaded and before it handles any request.
  2. activate is called for every tools/list request and before every tools/call request. If it returns false, the tool is hidden from the calling user and cannot be run. Portal administrators can always see the tool.
  3. execute runs the tool for a tools/call request. If it throws, it is retried up to getMaxRetries() times (0 to 3, inclusive; the default is 0). activate is not called again for a retry.
  4. destroy is called once, when the tool is unloaded.

Thread safety

The server creates one instance of each tool and shares it across all concurrent requests. Do not keep per-call state in instance fields; use local variables and the IMCPToolCallContext passed to each call. Create shared, thread-safe resources such as an HTTP client in init and release them in destroy.

Returning results

  • Return a MCPToolCallResult to control the content items, structured output, error flag and metadata.
  • Return any other ISerializableToJsonObject to send it as the structured output of the call.
  • For errors the agent can act on, return a result with isError set to true and a message that explains the problem. Throw only for unexpected failures.
  • Provide an output schema with getOutputSchema() whenever the tool returns structured output, so agents can parse it.

Security

  • IMCPToolCallContext.getPortalToken() returns the calling user's portal token. Send it only to the portal and its federated servers, in the body of a POST request, never in a URL.
  • Do not log tokens or include them in error messages or results.
  • Use the calling user's token, not a stored account, so that the tool can only do what the user is allowed to do.

Class loading and dependencies

The server provides these packages, so do not bundle them in the .mcp file: java.*, javax.*, jakarta.servlet.*, org.json.* and com.esri.arcgis.*. The project generated from the archetype already declares mcp-api and org.json as provided.

All other classes are loaded from the tool's own JAR first, and from the server only if the tool does not contain them. A bundled library that the server also uses can therefore conflict with the server's copy; for example, an unrelocated slf4j-api causes a LinkageError. Relocate such libraries with the Maven Shade plugin, or leave them out.

Certificates

If calls from a tool to the portal or a federated server fail with a PKIX certificate error, import the root and intermediate certificates into both Portal for ArcGIS and ArcGIS Server.

Related documentation

Packages
Package
Description
Core types shared by the API, such as ISerializableToJsonObject.
Logging for custom MCP tools.
The server-wide context passed to every tool method: logger, portal URL and server version.
The tool contract: implement IMCPTool to create a custom MCP tool.
Content items, such as text, images and resource links, that make up a tool result.
Tool results returned from IMCPTool.execute, such as MCPToolCallResult.