Troubleshooting and Limitations
Known limitations, current behaviours, and troubleshooting guidance for Tray Agent Gateway.
This page covers known limitations of Agent Gateway, expected behaviours that may require explanation, and guidance for resolving common issues.
Current limitations
Access and authentication
MCP users must have a Tray account within your organisation All users who execute MCP tools must have an active Tray account within your organisation. Support for users outside of Tray is on the roadmap.
OAuth2 client support OAuth2 authentication currently supports Claude Desktop. Support for additional MCP clients is expanding — contact your Customer Success representative if you have a specific client requirement.
API token users and user-provided authentication API token users cannot use user-provided authentication. They have no personal credentials in Tray and can only execute tools configured with service account authentication. See Authentication and Access for details on user types.
Authentication mapping reset Once a user maps their credentials during the elicitation flow, the mapping is valid for 7 days. The only way to reset it before expiry is to disconnect and reconnect the MCP server. A dedicated API endpoint for manual reset is planned for a future release.
Callable limits
Agent Gateway enforces the following limits on callable workflows usage within workflow tools:
| Limit | Value |
|---|---|
| Maximum callable depth | 5 levels |
| Maximum total callables across all levels | 20 (cumulative) |
When either limit is exceeded:
- Tool execution fails immediately
- The authentication elicitation flow does not trigger
- The Authentication Management tab returns an error and cannot be loaded
- An error message is returned identifying the tool ID responsible
The error does not indicate which callable or which depth level caused the failure. To resolve, manually inspect the affected workflow and reduce either the callable depth or the total number of callables used.
The tool ID in the error message can be used to identify the workflow in your Tray workspace. Navigate to the workflow and review its callable chain to locate where the limit is exceeded.
Insights and execution counts
Callables counted as separate executions In the Insights dashboard, callable workflows triggered by an MCP tool are counted as individual executions. A workflow tool that calls one callable will appear as two executions in the dashboard totals. This affects task run counts but does not impact execution logs or billing. This behaviour is being reviewed.
Connector tool execution logs Detailed step-level execution logs are not currently available for connector tools. Execution data for connector tools is visible in the Insights dashboard at an aggregate level. Step-level logging for connector tools is planned for a future release.
Tool limits
There is no hard technical limit on the number of tools per MCP server, however performance degrades noticeably beyond 15–20 tools. Above this threshold, AI clients take longer to select the correct tool, tool selection accuracy decreases, and the risk of incorrect tool invocation increases. If you need more tools, use separate MCP servers for different use cases or teams. See Getting Started for multi-server strategy guidance.
Troubleshooting
MCP server and connectivity
Server cannot be enabled
- Verify that Agent Gateway has been enabled at the organisation level by an Organisation Administrator
- Confirm you have Workspace Administrator permissions for this workspace
- Contact your Customer Success representative if the option is not visible in your workspace settings
Tools not appearing in AI client after connection
- Confirm the MCP server is enabled in Workspace Settings
- Confirm at least one tool is enabled (green status indicator) in the Workflow tools or Connector tools tab
- Disconnect and reconnect the MCP server in your AI client to refresh the tool list
- Restart the AI client completely
- If using API token authentication, verify the token has the necessary permissions for this workspace
Connection refused or timeout
- Verify the Workspace ID in your client configuration is correct
- Check the API token is valid and has not expired
- Confirm the MCP server URL is reachable from your network
Authentication
OAuth2 authorisation fails
- Verify your Tray account credentials are correct
- Ensure you have been added as a user in the Access Management tab for this MCP server
- Try the authorisation flow again — transient failures can occur during OAuth handshakes
- Contact support if the issue persists
403 Forbidden errors
- The user has not been added to the MCP server via the Access Management tab
- If using an API token, verify the token is valid and has not expired
- Review the Access Management tab and confirm the correct user type has been added
User-provided authentication prompt not appearing
- Confirm the connector or workflow step is configured to use user-provided authentication, not service account
- Confirm the user is connecting via OAuth2 — API token users cannot be prompted for their own credentials
- Check whether callable limits have been exceeded — if they have, the elicitation flow will not trigger (see callable limits above)
- If your MCP client does not support URL-based elicitation, the authentication prompt may not surface correctly. In this case, check whether your client returned a fallback message containing the authentication URL — you can navigate to this URL directly to complete the authentication mapping
User is prompted for authentication again before 7 days
- The MCP server connection was disconnected and reconnected, which resets all authentication mappings
- The user will need to complete the mapping flow again
Authentication Management tab returns an error
- This is most likely caused by callable limits being exceeded in one or more workflow tools
- Review your workflows and reduce callable depth or total callable count
- See callable limits above for resolution steps
Tool execution
Workflow tool execution fails
- Check the workflow is published and enabled
- Review execution logs for the specific step that failed
- Verify input parameters match the schema defined in the Agent Tool Trigger
- Test the workflow manually in the Tray platform to isolate whether the issue is MCP-specific
Connector tool operation fails
- Verify the connector authentication is valid and has not expired
- If using user-provided authentication, check that the user's selected authentication has sufficient scopes — a scope mismatch warning at mapping time indicates this risk
- For token-based authentications, the token is accepted as provided at mapping time and scope issues only surface at runtime — the user should recreate the authentication with a valid token
- Test the operation manually in a Tray workflow to confirm the connector is functioning correctly
Tool is invoked incorrectly or with wrong parameters
- Review the tool description — unclear descriptions are the most common cause of incorrect tool invocation by AI agents
- Add input validation within the workflow to catch unexpected values
- Consider whether the tool scope is too broad and should be split into more focused tools
Getting help
If you are unable to resolve an issue using this guide, contact your Customer Success representative or reach out via the Tray support portal. When reporting an issue, include the MCP server URL, the tool name, and any error messages or execution IDs from the workflow logs.