Skip to Content
runelay

Custom connectors

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:

TypeWhat you giveUse it for
Remote MCPThe server URLAny MCP server reachable over HTTP
Local commandA command, arguments and env varsMCP servers that run as a process, like npx packages
OpenAPIA spec in JSON or YAMLA REST API with no MCP server

Name and tool prefix

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.

Remote MCP

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:

DetectedWhat the panel does
OAuthShows OAuth sign-in: the login window opens when you save. Headers fold behind Add headers.
Key in a headerShows This server asks for a key in a header. Fill in the headers.
No sign-inNothing 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 and API keys

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 ••••••.

OAuth

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:

  1. 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.
  2. In runelay, open Use my own OAuth client while adding or editing the connection.
  3. 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.

How runelay gets an OAuth client

runelay tries these in order and stops at the first one that works:

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Local command

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.

OpenAPI

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.

FieldNotes
SpecThe spec URL.
Base URLOptional. Without it, the spec's own URL is used.
HeadersOne per line, Name: value. Stored encrypted. Use them for the API key.
Query parametersSent 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).

Private network addresses

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.

Status and troubleshooting

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.

Import from your agents

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.

On this page