Agent Gateway

Connecting MCP Clients

Configure AI assistants to connect to your Tray MCP server using the setup utility or manual configuration.

This guide walks you through connecting MCP-compatible AI clients to your Tray MCP server. Once connected, AI assistants can discover and execute the Workflow Tools and Connector Tools you've exposed.

Prerequisites

Before connecting a client:

MCP server enabled in workspace settings
At least one Workflow Tool or Connector Tool configured
Workspace ID (UUID from workspace URL)
API token with appropriate permissions
Node.js installed on your system
Supported AI client installed

Supported AI Clients

Claude Desktop - Anthropic's desktop application
VS Code - With Claude Code extension
Cursor - AI-powered code editor
Windsurf - Codeium's AI IDE
Any other MCP-compatible client

Using the Setup Utility

The Tray MCP setup utility automates client configuration. It handles config file locations, formats, and authentication setup for all supported clients.

Interactive Setup

Run the utility:

npx @trayio/tray-mcp

Follow the prompts:

Select client type (default: claude):
Supported clients: claude, cursor, windsurf, vscode Enter client type (default: claude):
Press Enter for Claude Desktop or type the client name.
Enter Workspace ID:
Enter your Tray.ai Workspace ID (UUID from URL):
Paste your workspace UUID.
Enter API Token:
Enter your Tray.ai API Token:
Paste your API token (input is hidden).
Customize server name (optional):
Enter a name for this MCP server (default: tray-workspace):
Press Enter for default or provide custom name.

Confirm if overwriting existing config:

⚠️ Server "tray-workspace" already exists in config.
Do you want to overwrite it? (y/n):

Configuration complete:

✓ Configuration successfully updated!
📦 Server "tray-workspace" has been added to your claude config.
⚠️ Please restart claude for the changes to take effect.

CLI Mode Setup

For automation or scripting:

npx @trayio/tray-mcp --workspace-id <UUID> --api-token <TOKEN> [options]

Available options:

Option	Short	Description	Default
`--workspace-id`	`-w`	Tray.ai Workspace ID (UUID)	Required
`--api-token`	`-t`	Tray.ai API Token	Required
`--name`	`-n`	Custom MCP server name	`tray-workspace`
`--client`	`-c`	Target client (claude, cursor, windsurf, vscode)	`claude`
`--help`	`-h`	Show help information	-

Example:

npx @trayio/tray-mcp \
  --workspace-id 12345678-abcd-1234-ef56-0123456789ab \
  --api-token your-api-token-here \
  --client claude \
  --name "production-mcp"

CLI mode automatically overwrites existing configurations without prompting.

Configuration Details

Config File Locations

The setup utility writes to the appropriate config file for each client:

Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

VS Code:

Uses VS Code CLI command to register MCP server

Cursor:

macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Windsurf:

macOS: ~/.codeium/windsurf/mcp.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp.json

MCP Server URL Format

Your MCP server URL:

https://{workspace-id}.mcp.tray.ai

The setup utility constructs this URL automatically from your Workspace ID.

Verifying the Connection

After Configuration

Restart your AI client completely (quit and reopen)
Check for MCP server in client settings:
- Claude: Settings → Developer → Model Context Protocol
- VS Code: Check MCP server list
- Cursor/Windsurf: Check MCP settings
Test tool discovery:
- Ask your AI assistant "What tools do you have access to?"
- Verify your Workflow Tools and Connector Tools appear
- Try executing a simple tool

Testing Tool Execution

Simple test:

User: "What Tray tools can you use?"

AI should list your exposed tools with descriptions.

Tool execution test:

User: "Use the [tool name] tool to [do something]"

AI should recognize the tool and execute it with appropriate parameters.

Troubleshooting

Client Can't Connect

MCP server not appearing in client:

Verify config file was updated (check file location)
Ensure MCP server is enabled in workspace settings
Restart client application completely
Check for JSON syntax errors in config file

Connection refused or timeout:

Verify Workspace ID is correct
Check API token is valid and not expired
Ensure MCP server URL is accessible from your network
Test URL in browser (should return MCP protocol response)

Tools Not Visible

AI client connected but no tools appear:

Verify at least one Workflow Tool or Connector Tool is enabled
Check tools have enabled status (green indicator) in workspace settings
Refresh tool list in AI client
Try disconnecting and reconnecting MCP server

Authentication Errors

401 Unauthorized errors:

API token may be invalid or expired
Token may not have permissions for the workspace
Recreate API token and update configuration

403 Forbidden errors:

API token doesn't have required permissions
Workspace role may be insufficient (needs Contributor or higher)
Check token permissions in Account Settings

Tool Execution Failures

Tool found but execution fails:

Check workflow is published and enabled (Workflow Tools)
Verify connector authentication is valid (Connector Tools)
Review workflow/connector logs for errors
Test manual execution in Tray platform

Configuration Issues

Setup utility fails:

Ensure Node.js is installed (node --version)
Check network connectivity
Verify write permissions for config directory
Try running with elevated permissions if needed

Multiple workspaces:

Run setup utility multiple times with different server names
AI clients can connect to multiple MCP servers simultaneously
Use descriptive names to differentiate servers

Advanced Configuration

Multiple MCP Servers

Connect to multiple Tray workspaces or environments:

# Production workspace
npx @trayio/tray-mcp \
  --workspace-id <prod-uuid> \
  --api-token <prod-token> \
  --name "tray-production"

# Development workspace
npx @trayio/tray-mcp \
  --workspace-id <dev-uuid> \
  --api-token <dev-token> \
  --name "tray-development"

AI clients can access tools from both servers.

Custom Server Names

Use descriptive names for different purposes:

tray-customer-support - Customer service tools
tray-sales - Sales automation tools
tray-it-ops - IT operations tools
tray-readonly - Read-only data access

Updating Configuration

To update an existing MCP server connection:

Run setup utility with same server name
Provide updated Workspace ID or API token
Confirm overwrite when prompted
Restart AI client

Security Considerations

Protect your API tokens:

Never commit config files to version control
Use separate tokens for different environments
Rotate tokens regularly
Revoke tokens when no longer needed

Network security:

MCP connections use HTTPS encryption
API tokens are stored in client config files
Ensure client machine is secure
Use workspace isolation for sensitive operations

Next Steps

Now that your AI client is connected:

Test your Workflow Tools and Connector Tools
Monitor tool usage and agent behavior
Iterate on tool descriptions for better AI understanding
Add more tools based on usage patterns
Review logs for errors or unexpected behavior

MCP Server Configuration - Configure server settings
Workflow Tools - Design effective Composite Tools
Connector Tools - Expose connector operations
Tray MCP NPM Package - Package documentation