Connect any MCP server or API that isn't in the catalog. Every agent that uses runelay sees it.
The catalog is a shortcut, not a limit. A custom connector adds anything else: a public MCP server that isn't listed, an internal server on your network or your own API. Once added it works like any other connection: one login, stored encrypted, shared by every agent in the organization.
Open Connectors in the panel, add a custom connection and pick the Connection type:
Type
What you give
Use it for
Remote MCP
The server URL
Any MCP server reachable over HTTP
Local command
A command, arguments and env vars
MCP servers that run as a process, like npx packages
The Name becomes the tool prefix: a connection named billing exposes tools like billing.list_invoices. Names are lowercased and anything other than letters and numbers becomes _. Agents find the tools with search_tools and run them with call_tool. You can rename a connection later; the login stays the same.
Paste the URL of the MCP server. When you leave the field, runelay probes it and tells you what kind of sign-in it expects:
Detected
What the panel does
OAuth
Shows OAuth sign-in: the login window opens when you save. Headers fold behind Add headers.
Key in a header
Shows This server asks for a key in a header. Fill in the headers.
No sign-in
Nothing extra. Save and the tools load.
Detection reads the server's WWW-Authenticate challenge and its OAuth protected resource metadata (/.well-known/oauth-protected-resource). If it can't tell, nothing is shown and you can still add headers or sign in after saving.
Headers go one per line as Name: value, for example Authorization: Bearer sk-.... They are stored encrypted with RUNELAY_SECRET, and agents never see them: requests made with an API key and the list_connections tool show the values as ••••••.
When the server requires OAuth, runelay runs the flow when you save, stores the tokens encrypted and refreshes them. Most servers support automatic client registration, so there's nothing to set up.
Some services have no automatic client registration (Google is one), so runelay can't create its own OAuth client there. For those:
In the service, create an OAuth client with this redirect URL:
PUBLIC_URL/v1/oauth/callback
The panel shows the exact address under Use my own OAuth client. PUBLIC_URL must be the public address of your server.
In runelay, open Use my own OAuth client while adding or editing the connection.
Paste the Client ID and the Client secret (leave it blank if the client has none), then save.
The secret is stored encrypted and is never returned. When editing, a blank secret keeps the current one, and clearing the Client ID removes your client. Changing or removing the client signs the connection out.
runelay tries these in order and stops at the first one that works:
Automatic client registration with your server's own redirect URL, PUBLIC_URL/v1/oauth/callback. This is what Linear, Notion, Atlassian, Stripe and most servers use.
Client ID Metadata Document, only when the provider refused that redirect URL and its authorization server advertises client_id_metadata_document_supported. runelay skips registration and uses https://auth.runelay.com/mcp/client.json as its client ID; the provider reads runelay's name, logo and redirect URL from that document. Vercel (https://mcp.vercel.com) works this way.
Automatic client registration through the relay, for providers that refused the redirect URL and don't support metadata documents, with https://auth.runelay.com/mcp/callback as the redirect URL. The provider still has to approve that address.
Your own OAuth client (Use my own OAuth client, described above), when everything else is refused. A client you configure always wins over steps 1 to 3.
A refused redirect URL shows up as a message like The provided redirect URIs are not approved for use by this authorization server. Self-hosted servers each have their own PUBLIC_URL, so providers that only accept approved addresses refuse step 1.
Steps 2 and 3 return through the runelay OAuth broker at https://auth.runelay.com/mcp/callback. The broker only relays the result: it reads where to send you back from the login state, shows a confirmation page when your server isn't on localhost, and redirects to PUBLIC_URL/v1/oauth/callback. It never sees a client secret or a token. These are public clients with PKCE, so your server keeps the verifier and exchanges the code with the provider itself.
If RUNELAY_OAUTH_BROKER_URL points to a broker without the /mcp/callback and /mcp/client.json routes, or isn't https, steps 2 and 3 don't work and you need your own OAuth client.
A command that starts an MCP server on the runelay machine itself (stdio), for example npx -y @modelcontextprotocol/server-everything. Add environment variables one per line as KEY=value; they are stored encrypted.
Local commands are off by default on a server. They need RUNELAY_ENABLE_STDIO=true, and even then only an owner or admin can create them from the panel. The process gets a minimal environment, without server secrets. The Docker image ships without Node, so commands like npx need the desktop app, where local commands are on and use the tools installed on your computer, or a custom image.
Point runelay at an OpenAPI spec, in JSON or YAML, by URL (for example https://api.example.com/openapi.json). Each operation in the spec becomes a tool.
Field
Notes
Spec
The spec URL.
Base URL
Optional. Without it, the spec's own URL is used.
Headers
One per line, Name: value. Stored encrypted. Use them for the API key.
Query parameters
Sent with every request, for APIs that take the key in the query string. Set them as config.query through the REST API (POST /v1/sources).
Outgoing requests to private, loopback, link-local and CGNAT addresses are blocked, to protect cloud metadata and other services on the host. To reach an internal server, set RUNELAY_ALLOW_PRIVATE_URLS=true on the runelay server. See Security.
Each connection shows its tool count and a status: Connected, Error, Needs sign-in or Not tested. After editing, Save and test checks it again, and Test connection does the same at any time. A connection that needs sign-in can be reconnected from its page or from /connectors/reconnect.
If the OAuth window doesn't open or the sign-in never finishes, see OAuth window not opening. The most common cause is a PUBLIC_URL that doesn't match the address you open the panel at.
If the server is already configured in an agent, import it instead of typing it again:
In the panel, Import takes your ~/.claude.json, ~/.codex/config.toml, ~/.grok/config.toml or ~/.cursor/mcp.json.
On your computer, runelay import turns the MCP servers configured in your agents into connections, and runelay migrate brings them along with logins, memories and skills. See CLI and Migrate.
Servers that use headers arrive connected. Importing through the API never expands ${VARS} from the server environment.