Overview

This document describes common set of issues and resolutions to those issues.

The first section identifies various issues that are common to all MCP Server integrations. These are divided into Authentication and Authorization, Rate Limiting, and API Execution errors.

The second section addresses client-specific issues. In general, most issues can be traced back to the initial configuration of the client with the Platform MCP Server. Integrations between the MCP Server and MCP client and managed differently in each client application and, consequently, unique client-specific issues may occur.

Authentication and Authorization Errors

The Platform MCP Server returns the 401 Unauthorized and 403 Forbidden HTTP response code to identify authentication and authorization issues.

These occur when the Platform MCP Server does not recognize the client (401 Unauthorized) or recognizes the client, but does not allow the client to connect (403:Forbidden). The Platform MCP Server may return custom error messages to help you diagnose and solve these issues.

The following authentication and authorization errors may be returned to Claude, Cursor, and Visual Studio Code clients.

Unauthorized

Issue

The MCP client fails to connect to the Platform MCP Server and returns 401 Unauthorized and a Missing Authorization error message.

Possible Cause

No Authorization header has been passed to Platform MCP Server.

Resolution

Validate Platform MCP Server Integration.

Invalid API Key

Issue

The MCP client fails to connect to the Platform MCP Server and returns 401: Unautorized with an Invalid API key error message.

Possible Cause

The API key or bearer token may be mistyped in client configuration.
The API key may have been revoked.
A Bearer prefix may have been added to bearer token in the client configuration.
The incorrect MCP Server endpoint is specified in the client configuration. The Platform MCP Server endpoint must match the tenant's Intelligent Risk Platform host.

Resolution

Validate Platform MCP Server Integration.
Ensure that the correct API key is set.
Ask your tenant administrator to verify the API key in Admin Center.
Specify the raw API key or bearer token only without a prefix.
Ensure that the MCP Server endpoint is the correct domain for your tenant. The Platform MCP Server endpoint must match the tenant's Intelligent Risk Platform host.

Token Expired

Issue

The MCP client fails to connect to the Platform MCP Server and returns the 401 Unauthorized status code with the error message:

Token Expired

Possible Cause

The bearer token specified in the client configuration has expired.

Resolution

Reconnect to Platform MCP Server.
In chat clients (i.e. Claude Desktop), start a new conversation or toggle the connector.

Session Auth Expired or Missing

Issue

The MCP client fails to connect to the Platform MCP Server and returns the 401 Unauthorized status code with the error message:

Session auth expired or missing. Re-initialize.

Possible Cause

Resolution

Reconnect to Platform MCP Server.
In chat clients (e.g. Claude Desktop), start a new conversation or toggle the connector.

Session Principal Mismatch

Issue

The MCP client fails to connect to the Platform MCP Server and returns the 401 Unauthorized status code with the error message:

Session principal mismatch. Re-initialize.

Possible Cause

The session was created by a different principal than the one issuing the current request.

Resolution

Reconnect to Platform MCP Server using the correct security credential.

Session Burned

Issue

The MCP client fails to connect to the Platform MCP Server and returns the 401 Unauthorized status code with the error message:

Session burned. Re-initialize for a new sessionId.

Possible Cause

A session ID is stale or has been reused.

Resolution

Reconnect to Platform MCP Server.
Restart the MCP client

Missing Entitlement

Issue

The MCP client fails to connect to the Platform MCP Server and returns the 403 Forbidden status code with the error message:

Missing required entitlement: Access IRP MCP Server

Possible Cause

The API key specified in the client configuration has not been assigned the IRP Agentic Tools User role.
The bearer token specified in the client configuration belongs to a user account that has not been assigned the IRP Agentic Tools User role.

Resolution

Ask the tenant administrator to assign the IRP Agentic Tools User role to the API key.

MCP Server Not Enabled

Issue

The MCP client fails to connect to the Platform MCP Server and returns 403 Forbidden status code with the error message:

MCP server is not enabled for this tenant.

Possible Cause

The tenant does not have access to the Platform MCP Server.

Resolution

Contact Moody's Customer Support.

Rate Limiting

Too Many Requests

Issue

The MCP Server returns an HTTP 429 Too Many Requests status code.

Possible Cause

The client has sent too many requests to the Platform MCP Server in a given amount of time. MCP client has been rate-limited.

The Platform MCP Server restricts the maximum number of requests allowed to prevent crashes, abuse, or distributed denial-of-service (DDoS) attacks.

Resolution

Wait and retry.
Reduce the number of parallel clients.

API Execution Errors

The execute-api tool runs a Platform API operation. In operationId mode it looks up the OpenAPI spec; in raw mode it accepts a rawUrl and method.

The execute-api tool requires that credentials be set in the session for outbound API authentication. The MCP client must pass an authorization in the form of an API key (IRP_AUTH) or the combination of a bearer token (IRP_AUTH) and host name (IRP_TENANT) in order to run Platform API operations.

The following authentication and authorization errors may be returned to Claude, Cursor, and Visual Studio Code clients.

Auth Token Not Configured

Issue
The MCP client fails to connect to the Platform MCP Server and returns the following message:

Auth token not configured. Set it via the set-variable MCP tool (IRP_AUTH) or the IRP_AUTH environment variable.``

Possible Cause

The execution credential is not set in the session. The execution-tool requires that the client authenticate with an API key.

Resolution

The IRP_AUTH and IRP_TENANT_NAME variables can be set using the set-variable tool. See Session Management Tools.
Session credentials can be defined as an environmental variable and this environmental variable can be specified in the client configuration.

Not Authorized to Execute APIs

Issue
The MCP client fails to connect to the Platform MCP Server and returns the following message:

Error: not authorized to execute APIs (missing entitlement).

Possible Cause
The API key or user account has not be assigned the IRP Agentic Tools User role.

Resolution
Ask tenant administrator to assign IRP Agentic Tools User role to the API key or the user account behind the bearer token.

Blocked

Issue

The MCP Server returns the following error:

Blocked: target host <host> is not in the allowed IRP host list

Possible Cause

The request accesses a system or systems rather than the Platform MCP Server and Intelligent Risk Platform.

Resolution

Rephrase the request to target Intelligent Risk Platform APIs.

Not Found

Issue

The MCP Server returns a 404: Not Found Error.

Possible Cause

The incorrect Platform MCP Server endpoint is specified in the client configuration. The host domain of the Platform MCP Server endpoint and the host domain of the Intelligent Risk Platform endpoint must match.

Resolution

Set IRP_API_HOST to tenant's region's public API host. One of api-use1.rms.com (US) or api-euw1.rms.com (EU).

Various Permission Errors

Issue

The principal can only perform actions using execute-api MCP Server tool if only perform actions

Probable Cause

The MCP client cannot perform an action.

In the Intelligent Risk Platform, API keys can be granted access rights and role-based permissions based on group membership. A MCP client can only perform actions that are explicitly assigned the API key it uses. See Platform MCP Server Access Controls.

Resolution

Ask a tenant administrator to assign the API key or user account to a user group that has been assigned the appropriate role.

MCP Host Application-Specific Issues

Supported MCP host applications include Claude Code, Cursor, and Visual Studio Code.

Visual Studio Code

To configure Visual Studio Code integration with the Platform MCP Server, see Visual Studio Code Integration.

Browser Window Opens

Issue
Connecting to the Platform MCP Server opens a window in web browser.

Probable Cause
The Visual Studio Code assumes OAuth because the client configuration is missing the Authorization header.

Resolution

Reconfigure the Platform MCP Server connection using the one-click button.

Manually configure specify static headers the headers block to use a token- or key-based authenticated server:

{
  "servers": {
    "irp-integration-mcp": {
      "type": "http",
      "url": "https://api-use1.rms.com/platform/integration/v1/mcp",
      "headers": {
        "Authorization": "${input:irp_api_key}"
      }
    }
  }
}

Authentication Required Prompt

Issue

Probable Cause
Visual Studio Code assumes OAuth because the Authorization header is undefined in the client configuration.

Resolution

Reinstall using the one-click button.
Add input and headers block

Can't Reach This Page Error

Issue
When using the one-click buttons, the following error message on vscode.dev:

can't reach this page / ERR_FAILED

Probable Cause
Network blocks the vscode.dev domains the one-click buttons route through.

Resolution

Configure a connection to Platform MCP Server using the URL protocol handler or by editing the client configuration file manually.

Paste the vscode:mcp/install?… protocol URL into address bar of the browser.
Configure the connection to the Platform MCP Server manually. To learn more, see https://code.visualstudio.com/docs/agent-customization/mcp-servers

Mistyped API Key

Issue
The incorrect security credential (e.g. API key) is entered in the chat client.

Possible Cause

Visual Studio Code stores MCP input parameters in its internal Secret Storage, bound to the unique inputs[].id defined in your configuration file (e.g. mcp.json).

Resolution

In Command Palette (CTRL+SHIFT+P or CMD+SHIFT+P) > MCP:List Servers > irp-integration-mcp > Clear Cached Inputs.
In Command Palette > Developer: Reload Window.
Reconnect to the Platform MCP Server.

Clear saved inputs and restart the Visual Studio Code application. Select Command Palette > MCP: List Servers > irp-integration-mcp > Clear Saved Inputs, then restart the server

Claude Desktop

Unlike Claude Code, Claude Desktop does not natively support connecting to remote MCP Servers.

mcp-remote is an open-source utility distributed as an npm package that allows Claude Desktop to connect to a remote MCP server such as the Platform MCP Server. Issues may occur if the Node.js prerequisites are not installed correctly.

Server Does Not Start

Issue
The MCP client cannot connect to the Platform MCP Server.

Possible Cause
Node.js missing or npm registry unreachable.

Resolution

The mcp-remote utility is an npm package that requires Node.js version 18.0. Confirm that Node has been installed. See https://nodejs.org/en/download.

Cursor

To configure Cursor integration with the Platform MCP Server, see Cursor Integration.

Unauthorized

Issue
The MCP client cannot connect to the MCP Server and returns a 401 Authorized status code. The connection has been configured using the IRP_API_KEY environmental variable.

Possible Cause
The IRP_API_KEY environmental variable is not visible to Cursor.

Resolution

Confirm that the IRP_KEY environmental variable is visible to Cursor. On MacOS, applications do not read dot files (e.g. bash_profile). Launch Cursor from the Terminal or run the launchctl setenv command to set a temporary environmental variable.
Validate the client configuration in the mcp.json file. Ensure your JSON syntax is correct, environment variables or API keys are provided, and required runtimes (like Node or Python/uvx) are installed.