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 | Maven artifact version | JDK |
|---|---|---|
| 12.2 | 12.2.0 | 21 |
| 12.1 | 12.1.0 | 17 |
| 11.5 | 11.5.0 | 17 |
| 11.3 | 11.3.0 | 17 |
| 11.1 | 11.1.0 | 11 |
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
- Install the
mcp-apiandmcp-api-archetypeartifacts for your release into your local Maven repository with theinstall-maven-artifactsscript from thearcgis-enterprise-mcp-resourcesrepository. - Generate a tool project from
mcp-api-archetype. The project contains a tool class, a test, and the build configuration that produces the.mcpfile. - Implement the tool: set its name, title, summary and description, define its input and
output schemas, and write
execute. - Build the project with
mvn packageto create the.mcpfile. - Deploy the
.mcpfile. The steps differ between ArcGIS Enterprise 12.2 and later and earlier releases; seedocs/deploy-mcp-tools.mdin thearcgis-enterprise-mcp-resourcesrepository. 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
initis called once, after the tool is loaded and before it handles any request.activateis called for everytools/listrequest and before everytools/callrequest. If it returnsfalse, the tool is hidden from the calling user and cannot be run. Portal administrators can always see the tool.executeruns the tool for atools/callrequest. If it throws, it is retried up togetMaxRetries()times (0 to 3, inclusive; the default is 0).activateis not called again for a retry.destroyis 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
MCPToolCallResultto control the content items, structured output, error flag and metadata. - Return any other
ISerializableToJsonObjectto send it as the structured output of the call. - For errors the agent can act on, return a result with
isErrorset totrueand 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
- Install MCP Services for ArcGIS Enterprise
- Enable MCP for ArcGIS Enterprise (ArcGIS Enterprise 12.2 and later)
- MCP catalogs
- Manage MCP catalogs (custom catalogs, ArcGIS Enterprise 12.2 and later)
- Extend MCP for ArcGIS Enterprise
- Expose a web tool as a custom MCP tool
- Default MCP catalog overview
- Connect from MCP clients
- Troubleshoot MCP for ArcGIS Enterprise
ISerializableToJsonObject.IMCPTool to create a custom MCP tool.IMCPTool.execute, such as MCPToolCallResult.