Troubleshoot MCP for ArcGIS Enterprise
When an MCP client cannot connect to a catalog, a tool fails, or a response is unexpected, review the connection settings and ArcGIS Server logs to identify the cause.
MCP for ArcGIS Enterprise writes diagnostic messages to the ArcGIS Server logs on your hosting server site. These messages help you distinguish problems with MCP for ArcGIS Enterprise from issues with authentication, network connectivity, or the underlying GIS services. For answers to common questions, see the FAQ.
Check the deployment and connection
Before you collect detailed logs, verify the following:
Installation—MCP Services for ArcGIS Enterprise are installed on every machine in the hosting server site.
Enablement—For ArcGIS Enterprise 12.2 and later, External AI client access is turned on in the organization's AI settings.
Catalog URL—The client uses the correct default or custom catalog endpoint.
Authentication—The credential is valid and configured using a technique that the client supports.
Permissions—The user or credential can access the catalog and the resources that the workflow requires.
Network access—The environment that makes the MCP connection can reach your deployment.
For configuration guidance, see Enable MCP for ArcGIS Enterprise, Select an authentication technique, and Connect from MCP clients.
Identify MCP log messages
To access MCP diagnostics, review the server logs of your hosting server site.
Look for MCP_SERVER in the log entry's target or source information. Review the timestamp, severity, machine, and full message to understand what happened.
MCP diagnostic messages include the following:
| Severity or category | Examples |
|---|---|
| Severe | Failure to start the MCP application, or failure to register a Java-based custom MCP tool. |
| Warning | Failure to establish an outbound connection, including certificate trust problems. |
| Informational audit entries | Requests made to the catalog. |
| Debug | Invalid tool parameters, malformed requests, or errors returned by ArcGIS services. |
Java-based tools are loaded separately from the administrative action that deploys them, so a registration failure is not reported by that action. These failures are logged as Severe so that they are visible in the logs.
Note:
The configured logging level determines which messages are recorded. Selecting Debug when you query the logs does not recover messages that were not recorded.
If the existing messages do not explain the issue, temporarily increase the logging level and reproduce the problem. Because debug logging produces a large volume of messages, use it only while you are actively troubleshooting. Restore the previous setting when you finish.
For general logging information, see Server logs.
Query logs in the Administrator Directory
You can also inspect logs through the ArcGIS Server Administrator Directory.
Open the Administrator Directory for your hosting server site:
https://<server>:6443/arcgis/adminReplace
<server>with the fully qualified domain name of a machine in your hosting server site.Sign in as an administrator.
Open logs, and then open query.
Select a logging level and a time range that covers the failed action.
Submit the query.
Find the entries associated with
MCP_SERVER.Open the full message to see details that may be truncated in the results table.
Start with Warning to review warning and severe messages. Use Debug to include all recorded levels.
For a site with multiple machines, check entries across the site, and use the machine information to identify where a failure occurred.
You can automate log queries through the ArcGIS Server Administrator API. For supported filters and parameters, see Query Logs.
Interpret common messages and errors
Use the complete message and related entries to investigate the cause. A single error may describe a symptom rather than the original failure.
MCP is not enabled for this organization
In ArcGIS Enterprise 12.2 and later, a client that connects to any MCP catalog may get the following error:
{"error":{"message":"com.esri.arcgis.mcp.catalog.mcp.exceptions.McpNotEnabledException: MCP is not enabled for this organization.","data":null,"code":-32603},"id":null,"jsonrpc":"2.0"}
MCP Services for ArcGIS Enterprise are installed, but External AI client access is not turned on. An administrator must turn on this setting. For details, see Enable MCP for ArcGIS Enterprise.
Requirements missing in AI settings
In ArcGIS Enterprise 12.2 and later, Requirements missing appears next to the External AI client access setting when MCP Services for ArcGIS Enterprise are not installed. Selecting it shows the message MCP Services for ArcGIS Enterprise must be configured.
Install MCP Services for ArcGIS Enterprise on every machine in the hosting server site, and then turn on the setting. For details, see Install MCP Services for ArcGIS Enterprise.
Portal information cannot be retrieved
A failure to retrieve portal information indicates a problem with communication with the portal or with obtaining a valid response from it.
Check portal availability, connectivity from the hosting server, and authentication. If needed, review the portal logs for the same time period.
Certificate trust fails
A certificate chain validation failure indicates that the target certificate is not trusted.
Review the target certificate and its issuing chain with your administrator. Correct the trust configuration using the supported ArcGIS Enterprise certificate management procedures.
A tool parameter is not recognized
An unrecognized field error indicates that a request contains an unsupported parameter.
Compare the submitted arguments with the parameters described on the tool's reference page. For the list of tools, see Default MCP catalog overview. Correct the parameter names and values, and then retry the request.
Recent changes do not appear yet
MCP for ArcGIS Enterprise caches some information to improve performance, so changes are not reflected immediately. Wait for the cache to refresh before you test a change. Then refresh the tool list or reconnect the MCP client, as that client requires.
| Change | Time before the change is reflected |
|---|---|
| A custom catalog's tools, name, or description | A few minutes |
Web tool items tagged for MCP, such as adding or removing the mcp tag, or updating the item |
Up to one minute |
| Organization settings and utility services configured in your portal | Up to one minute |
Troubleshoot common symptoms
| Symptom | What to check |
|---|---|
| The client cannot connect. | Verify the endpoint, network access, authentication, and whether External AI client access is turned on. If the error states that MCP is not enabled, see MCP is not enabled for this organization. |
| Authentication fails. | Check credential expiration and client configuration. For portal tokens, verify that the token was generated by the portal, not the ArcGIS Server administration endpoint. |
| OAuth configuration cannot be completed. | Verify that the client supports manual configuration, and that the authorization endpoint, client ID, and redirect URI are correct. |
| The connection exists, but tools are unavailable. | Check whether the connection and tools must be enabled for the current conversation, workspace, or agent. |
| A custom catalog is unavailable. | Verify that the catalog item still exists, the endpoint contains the correct item ID, and the item is shared appropriately. |
| An expected tool is missing. | Review the catalog's tool selection. For a web tool, verify that the item has the mcp tag. The default catalog includes only the 20 most recently modified web tools. Check whether another tool has the same name. For details, see Tool name conflicts. If the client keeps an earlier tool list, refresh or reconnect it. For details, see Recent changes do not appear yet. |
| A search does not return an expected item. | Verify the item's mcp tag, sharing settings, and descriptive information. ArcGIS Living Atlas of the World content is not returned. |
| A tool cannot access a layer or service. | Check the resource's availability and the permissions associated with the connection. |
| The application responds without using an ArcGIS tool. | Check the client's tool-selection and approval settings. Use a specific request that requires your organization's GIS content. |
| A request completes, but the results are unexpected. | Inspect the selected item, tool arguments, filters, and source data before you evaluate the AI-generated explanation. |
| No relevant MCP entries appear in the logs. | Verify the site, time range, and configured logging level. Check the client's diagnostics to find out whether the request reached the server. |
For client-specific errors and configuration requirements, see the client provider's documentation. For content discovery guidance, see Prepare your content for use with MCP.
Collect information for further investigation
If the issue persists, collect the following information:
The ArcGIS Enterprise version and the MCP Services for ArcGIS Enterprise version
The MCP client name and version
Whether the issue affects the default catalog, a custom catalog, or both
The authentication technique used, without the credentials
The time of the failure, including the time zone
Steps to reproduce the issue
The affected tool name, relevant arguments, and expected result
The complete relevant log messages and any client-side error details
Important:
Remove tokens, API keys, passwords, and sensitive data before you share diagnostic information.
Provide the collected details to your administrator or Esri Support.