macOS onboarding guide for the Runlayer MCP Gateway platform. Use this skill when a user needs help getting started with Runlayer, setting up MCP clients (Claude Code, Claude Desktop, VS Code, JetBrains, ChatGPT), connecting to the Runlayer gateway, authorizing connectors (GitHub, Atlassian, Snowflake, Slack, Datadog), or troubleshooting MCP connection issues. Also trigger when users mention onboarding new team members to Runlayer, setting up AI tooling, or connecting AI clients to enterprise MCP servers.
dgruber-nydig0 스타2026. 4. 7.
직업
카테고리
클라우드
스킬 내용
This guide walks new users through getting set up on the Runlayer MCP Gateway at stoneridge.runlayer.com. It applies to all personas (developers, business users, agentic systems) and covers everything from first login to verified connectivity.
macOS (any recent version — Ventura 13+ recommended)
A modern browser (Chrome, Safari, Firefox, or Edge)
An Okta account — the org uses Okta for SSO. The user should already have Okta credentials and see the Runlayer tile in their Okta dashboard. If they don't, they need to contact IT to be provisioned.
At least one AI client installed — see the client list below
Click Sign in with SSO (or the Okta tile if redirected)
Authenticate with Okta credentials + MFA
On first login, Runlayer creates a user profile automatically. The user lands on their dashboard showing available connectors (MCPs).
If the user doesn't see the Runlayer app in Okta, an admin needs to assign them to the Runlayer application in the Okta admin console.
Step 2: Connect AI Clients to Runlayer
Runlayer acts as a gateway — AI clients connect to Runlayer's proxy URLs instead of directly to backend services. Each MCP server in Runlayer has a proxy URL that the client uses.
Option A: Auto-Provisioning (recommended for org-wide rollout)
If an admin has enabled auto-sync on servers, the Runlayer CLI can push configs to all supported clients at once:
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Log in to Runlayer
uvx runlayer login --host https://stoneridge.runlayer.com
# Sync all auto-synced servers to your local clients
uvx runlayer setup sync -y
Supported clients for auto-provisioning: Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, Goose, Zed.
Option B: Per-Client Manual Setup
For each MCP the user needs, go to https://stoneridge.runlayer.com, click the MCP server, and select the target AI client from the dropdown. Runlayer shows tailored instructions per client:
Claude Code (CLI)
Setup type: CLI command
Runlayer provides a claude mcp add command with the proxy URL
Run the command in terminal, then restart Claude Code
Claude Desktop (macOS app)
Setup type: Configuration file
Runlayer provides JSON to add to ~/Library/Application Support/Claude/claude_desktop_config.json
Add the server entry under "mcpServers", then restart Claude Desktop
For VS Code: click the deeplink button in Runlayer's UI — it opens VS Code and adds the MCP automatically
For JetBrains: copy the config snippet into the IDE's MCP settings
ChatGPT Desktop & Web
Setup type: Web UI connector
Follow the ChatGPT-specific instructions shown in Runlayer's UI
Using the OneLayer Plugin (all connectors in one)
If the org has the OneLayer dynamic plugin configured, users can connect a single plugin URL that automatically includes all connectors they have access to, instead of adding each MCP server individually. Go to https://stoneridge.runlayer.com/plugins and follow the install instructions for your client.
Step 3: Authorize Each Connector
After adding MCP servers to your client, each connector that uses OAuth needs a one-time authorization:
In Runlayer's web UI, go to Connectors in the left sidebar
Find the connector (e.g., GitHub, Atlassian, Snowflake)
Click Connect and complete the OAuth flow for that service
Each user authorizes with their own credentials — queries run with that user's individual permissions
Connector-specific notes
GitHub: Authorizes via GitHub OAuth. Select which repos/orgs to grant access to.
Atlassian: Authorizes via Atlassian OAuth. Grants access to Jira + Confluence based on your Atlassian permissions.
Snowflake: Authorizes via Snowflake OAuth. Each user logs in with their Snowflake credentials — queries run with that user's role and warehouse permissions.
Slack: Requires a Slack app to be set up by an admin first. Users authorize via Slack OAuth.
Datadog: Follow the Datadog-specific setup in Runlayer's catalog.
Step 4: Verify Connectivity
After setup, verify everything works.
Quick smoke tests per client
Ask your AI client any of these:
GitHub: "List my GitHub repositories" or "Show my recent PRs"
Atlassian: "Show me my Jira tickets" or "Search Confluence for <topic>"
Snowflake: "Show me who am I using the Snowflake MCP"
Slack: "List my Slack channels"
Datadog: "Show recent Datadog alerts"
If the Runlayer MCP (self-MCP) is connected, you can also verify programmatically. Use the mcp__runlayer__whoami tool to confirm your identity and org, and mcp__runlayer__list_servers to see which connectors are active.
What success looks like
mcp__runlayer__whoami returns your name, email, and organization ID
mcp__runlayer__list_servers shows the connectors you expect (GitHub, Atlassian, etc.) with "status": "active"
Smoke test queries return real data from the connected services
Step 5: Troubleshooting
Common issues
Symptom
Likely cause
Fix
401 Unauthorized / "Token expired"
OAuth token expired or revoked
In Runlayer web UI: Connectors > find the MCP > Revoke access > Reconnect
403 Forbidden / "Policy denied"
You don't have access to this tool/server
Contact your admin to request access via an access rule
Connection timeout / "Server unreachable"
Network issue or server downtime
Check if there's a known outage; try again in a few minutes
MCP error -32603 / 500 Server Error
Server-side error
Check audit logs; retry with different parameters; contact admin
429 Too Many Requests
Rate limit hit
Wait a few minutes and retry
"Security violation" on normal requests
Security scanner false positive
Rephrase request; contact admin to review and adjust scanner sensitivity
Tools not showing in AI client
Config not loaded or client not restarted
Restart the AI client; verify the MCP config file is correct
Connector missing from Runlayer
Server not installed or you lack access
Ask admin to check server status and your access policies