Relay Setup

Connect to the Relay platform for secure access to all integrated services. MCP tools use OAuth automatically via mcp-remote. An optional script config stores the Relay URL for local health checks.

Prerequisites

• A Relay account (provided by your IT admin or Revtelligent)
• Your organization's Relay base URL

Environment Prerequisite (Required)

Before running /setup, Relay MCP must already be configured in the current agent. /setup saves URL/config for diagnostics, but it does not create connectors by itself.

Environment	Required MCP setup	Quick test
Claude Code / Claude Desktop	Install relay-connect from marketplace. If Relay tools still do not appear, add a Relay custom connector to <base-url>/mcp.	Ask the agent to run list_workflows.
Codex	Run ./deploy/install.sh --plugin relay-connect --agents codex (or add [mcp_servers.relay] manually).	Run list_workflows.
Gemini CLI	Run ./deploy/install.sh --plugin relay-connect --agents gemini-cli (or add mcpServers.relay manually).	Run list_workflows.

Setup Flow

Step 1: Check existing saved configuration

Run the setup script to check for saved configuration:

${CLAUDE_PLUGIN_ROOT:-$HOME/.agents}/skills/setup/scripts/relay-setup.sh check

If configured, the output includes url, mcpUrl, and connection status. If not configured, proceed to Step 2.

Step 2: Guide the user to save their Relay URL

Tell the user:

Relay MCP tools authenticate automatically via OAuth when first used. We just need to save your organization's Relay URL for health checks and diagnostics.

Ask your IT admin for the Relay base URL if you don't have it.

Step 3: Save Relay configuration

Once the user provides the base URL:

${CLAUDE_PLUGIN_ROOT:-$HOME/.agents}/skills/setup/scripts/relay-setup.sh save <base-url>

This saves configuration to ~/.config/revtelligent/relay.env containing:

Variable	Purpose	Example
RELAY_URL	Base URL	https://relay.acme-corp.revtelligent.com
RELAY_MCP_URL	MCP server endpoint	https://relay.acme-corp.revtelligent.com/mcp

The file is stored with chmod 600 (owner-only access).

Step 4: Verify connection

Run the health check to confirm the Relay MCP server is reachable:

${CLAUDE_PLUGIN_ROOT:-$HOME/.agents}/skills/setup/scripts/relay-setup.sh health

Expected output when healthy:

{
  "healthy": true,
  "mcp": { "reachable": true, "status": 200 }
}

If the endpoint fails, load references/troubleshooting.md for diagnostic steps.

If health check fails but list_workflows succeeds, treat MCP connectivity as working. In restricted/sandboxed environments, the health script may not have the same network path as MCP tool calls.

Step 5: Confirm success

If healthy, tell the user:

All set! Your Relay connection is active.

MCP tools (workflow queries, approvals, task management, etc.) connect through OAuth automatically. Available tools are documented in references/relay-api.md.

All Revtelligent skills are now ready to use.

Available MCP Tools

Once connected, these tools are available through the Relay MCP server:

Tool	Description
list_workflows	List available workflow types
start_workflow	Start a new workflow execution
get_workflow_status	Check workflow execution status
send_message	Send a message to the AI agent for routing
approve_workflow	Approve or reject a workflow
create_approval_request	Create a new approval request
query_workflow_history	Search past workflow executions

See references/relay-api.md for full details on each tool.

Troubleshooting

Symptom	Cause	Fix
configured: false	No config file	Run setup (Steps 2-3)
MCP unreachable	Server down or URL wrong	Check URL with IT admin
OAuth login loop	Browser cookie issue	Clear cookies, retry
401 / 403 errors	Insufficient permissions	Contact admin for access

See references/troubleshooting.md for detailed diagnostics.