- 3 minutes to read

Troubleshooting MCP Endpoint

Use this guide when the IIS-hosted MCP Endpoint doesn't start, clients can't connect, or the tools return no data. Work from the server outwards: the problem is usually in the first layer that fails.

Diagnostic Approach

graph LR A["fa:fa-globe 1. IIS site starts"] --> B["fa:fa-network-wired 2. Port reachable"] B --> C["fa:fa-key 3. Token accepted"] C --> D["fa:fa-toolbox 4. Tools load"] D --> E["fa:fa-comments 5. Answers make sense"]

Diagram: Check each layer in order: IIS hosting, network path, authentication, MCP tools, and finally the client or AI provider configuration.

  1. IIS site and app pool health
  2. Port binding and network reachability
  3. Authentication: OAuth audiences, scopes, and the canonical URL
  4. Tool discovery and feature flags
  5. Client and AI provider configuration

Common Issues

The MCP Endpoint site does not start in IIS

Note

An MCP Endpoint whose application pool is stopped right after an install or update is not necessarily broken. When Keep the MCP Server stopped is selected in the Portal, the installer deploys the site and files but leaves the application pool stopped, also after an IIS reset or a server restart. See Keep the MCP Server Stopped.

If the option is cleared, check the app pool identity, the binding, and the Windows Application event log. An HTTP 500.30 error means the ASP.NET Core app failed at startup, often because of invalid configuration. Confirm that no other site owns the port, and compare the port with the MCP Server value in Servers → Core platform services. If the values in the Portal are wrong, correct them there and run the package again instead of editing IIS by hand.

The endpoint port is unreachable

Confirm the inbound firewall rules and routing for the MCP Server port, and test from the same network segment as your MCP clients. In cloud and proxy setups, check that the port is forwarded; see External Access Requirements.

Sign-in works, but calls return 401 or the client loops

The token audience or the advertised resource URL doesn't match. Check the MCP Server Audiences in Auth → MCP Server and the canonical URL in Choose One Canonical URL. The full symptom table is in MCP Endpoint External Access – Troubleshooting.

The AI Assistant opens but shows no tools

In OAuth installations, the Web Client app registration needs admin consent for the MCP scopes; an AADSTS65001 error points to missing consent. See Connect the Web Client AI Assistant. Also confirm that EnableMcpChat is true in the AI System Parameter and that an AI provider is configured in the AI Assistant.

Repository questions work, but BizTalk tools are missing

BizTalk tools also need EnableAiForBizTalk in the AI System Parameter and administrator access. See BizTalk and MCP Endpoint.

The update completed, but MCP requests fail

If you updated from a version before 7.4.0, check that the MCP Server port was entered in the Portal before the package was downloaded, and that the firewall rule exists. See Update MCP Endpoint.

The client loads but gives no usable answers

When the technical checks pass, continue with the client checks in the AI documentation:

I need to remove the MCP Endpoint

See Uninstall MCP Endpoint.

Next Steps