Skip to main content

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.

  1. Open the Administrator Directory for your hosting server site:

    https://<server>:6443/arcgis/admin
    

    Replace <server> with the fully qualified domain name of a machine in your hosting server site.

  2. Sign in as an administrator.

  3. Open logs, and then open query.

  4. Select a logging level and a time range that covers the failed action.

  5. Submit the query.

  6. Find the entries associated with MCP_SERVER.

  7. 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.