Troubleshoot FlowMCP Gateway

Platform 6.5+ Gateway 5.5+

Use this guide to diagnose and resolve common FlowMCP Gateway issues. All MCP-backed gateway service failures surface errors in standard Itential Gateway error formats—no MCP-specific error handling is required.

MCP server connectivity failures

Symptoms

A registered MCP server shows a connectivity error in Itential Gateway.
Tools from the server are not visible in Gateway Manager after registration.

Checks

Verify the server’s endpoint URL or command is correct. Inspect the server configuration using iagctl mcp server inspect <name> or the Gateway UI and confirm the value matches the running server.
Confirm the MCP server is running and reachable from the host running Itential Gateway:
- For HTTP transport servers, verify the URL is accessible from the Gateway host and that no firewall rules are blocking the connection.
- For stdio transport servers, verify the command is available and executable on the Gateway host.
Check that any credentials the server requires are valid and correctly stored in Itential Gateway’s secrets management. Credentials are never returned in inspection output—if a credential may have changed or expired, re-enter it.
Review the Gateway logs for connectivity error details. If the server can’t be reached, subsequent attempts to call its tools return the following error:
```
Error: rpc error: code = Internal desc = tool call failed: MCP error -32602: Input validation error: Invalid arguments
```

Tools not appearing in Gateway Manager after registration

Symptoms

An MCP server registers successfully, but some or all of its tools are not visible as gateway services in Gateway Manager.
Tools that previously appeared in Gateway Manager are no longer visible after changes were made to the MCP server.

Checks

Confirm that the MCP server is actively exposing the expected tools. Use iagctl mcp tool list <name> to query the server directly:
```
$ iagctl mcp tool list <name>
```
If the expected tools don’t appear in the output, the issue is with the MCP server itself, not with Itential Gateway.
If tools were added to the MCP server after initial registration, they won’t be available in Gateway Manager until Itential Gateway runs tool discovery again. Update the server configuration to trigger a new discovery.
If the server was recently updated, allow time for discovery to complete before verifying tool availability in Gateway Manager.

Tools available to an agent are determined at the start of each run based on the agent’s associated agent project. Tools added to a registered MCP server after an agent has already started running won’t be available to that agent until its next run.

MCP tool invocation failures

Symptoms

A workflow or agent receives an error when invoking an MCP-backed gateway service.
An invocation that previously succeeded begins returning errors.

Checks

Confirm that the user or automation invoking the service has the required Gateway Manager RBAC permissions. MCP-backed gateway services use the same Gateway Manager permission model as all other gateway services—check permissions the same way you would for any other service.
Verify that the inputs being passed to the tool are valid. Use iagctl mcp tool list <name> --raw to view the tool’s full input schema:
```
$ iagctl mcp tool list <name> --raw
```
Determine whether the error originated in Itential Gateway or on the MCP server itself. Review the error code to identify the source:
- NotFound — the MCP server name is not registered in Itential Gateway.
```
Error: rpc error: code = NotFound desc = mcp server not found
```
- Internal with an MCP error code — the error originated on the MCP server. Error -32602 indicates an input validation failure; check that the parameters passed to the tool match its expected schema.
```
Error: rpc error: code = Internal desc = tool call failed: MCP error -32602: Input validation error: Invalid arguments
```
- Internal without an MCP error code — the error originated in Itential Gateway. Review the Gateway logs for details.
If the MCP server returned an error, check the server’s own logs for diagnostic information.

MCP server definitions missing or misconfigured after import

Symptoms

MCP server definitions are absent after importing a database into a new Itential Gateway instance.
MCP server definitions are present after import, but connectivity fails due to missing credentials. Checks

Confirm that the database export you imported included MCP server configurations. MCP server definitions are included in Itential Gateway database exports by default.
If server definitions are present but connectivity fails, check whether the credentials an MCP server’s transport configuration depends on exist on the destination instance. Exported configurations reference credentials by alias ($GATEWAYSECRET_<alias>) rather than including the credential values themselves, so importing a database doesn’t create or transfer the underlying secrets. If the alias doesn’t resolve to an existing secret on the destination instance, add the missing secret in Itential Gateway’s secrets management.