OAuth over SSH / Remote Hosts

Some Mibyan providers — Spotify and remote MCP servers (Linear, Sentry, Atlassian, Asana, Figma, …) — use a loopback redirect OAuth flow. The auth server redirects your browser to http://127.0.0.1:<port>/callback so a tiny HTTP listener started by Mibyan can grab the authorization code. This works perfectly when Mibyan and your browser are on the same machine. It breaks the moment they aren’t: your laptop’s browser tries to reach 127.0.0.1 on your laptop, but the listener is bound to 127.0.0.1 on the remote server. The fix is a one-line SSH local-forward. For MCP servers on an interactive terminal, you can often paste the redirect URL back instead (no tunnel). xAI Grok OAuth (xai-oauth) uses OAuth device code, not a loopback callback — open the printed verification URL in any browser and Mibyan polls until approval. No SSH tunnel is required. See xAI Grok OAuth.

TL;DR

# On your local machine (laptop), in a separate terminal:
ssh -N -L 43827:127.0.0.1:43827 user@remote-host

# In your existing SSH session on the remote machine:
mibyan auth spotify --no-browser
# → Mibyan prints an authorize URL. Open it in a browser on your laptop.
# → Your browser redirects to 127.0.0.1:43827/callback, the tunnel forwards
#   the request to the remote listener, login completes.

Mibyan prints the exact port it bound to on the Waiting for callback on ... line — copy it from there. Spotify defaults to port 43827.

Which Providers Need This

Provider	Loopback port	Tunnel needed?
Spotify	`43827` (default)	Yes, when Mibyan is remote
MCP servers (`auth: oauth`)	auto-picked per server	Yes, when Mibyan is remote (or paste redirect URL)
`xai-oauth` (Grok SuperGrok)	n/a	No — device code flow
`anthropic` (Claude Pro/Max)	n/a	No — paste-the-code flow
`openai-codex` (ChatGPT Plus/Pro)	n/a (default device code); `1455` with `--browser` / `auth.codex_login_flow: browser`	Only for the opt-in browser PKCE flow, when Mibyan is remote
`minimax`, `nous-portal`	n/a	No — device code flow
`openrouter` (`mibyan auth add openrouter --type oauth`)	OS-assigned, local only	No — over SSH Mibyan switches to OpenRouter’s headless flow and asks you to paste the code shown in the browser

If your provider isn’t in the table, you don’t need a tunnel.

MCP Servers

Desktop Skills → MCP: the native app receives the callback on your computer and relays it to the selected connection and profile, so this flow does not need an SSH callback tunnel or dashboard.public_url. Tokens stay on the owning backend profile. Leaving the MCP tab or changing its scope cancels pending sign-in. If Desktop asks you to update the backend, update it before retrying; it does not fall back to a remote HTTP callback. The terminal workflows below are unchanged. Remote MCP servers (Linear, Sentry, Atlassian, Asana, Figma, etc.) use the same loopback redirect flow. Mibyan auto-picks a free port per server and prints the authorize URL when the OAuth flow kicks off — either at startup (when a new server appears in mcp_servers:) or when you run mibyan mcp login <server>. You have two ways to complete it from a remote host: Option 1 — paste the redirect URL back (no setup, works anywhere). On an interactive terminal, Mibyan prompts you to paste the redirect URL alongside running the local listener. After approving in your browser, the redirect to http://127.0.0.1:<port>/callback will show a connection error — that’s expected. Copy the full URL from the browser’s address bar and paste it at the Mibyan prompt:

  MCP OAuth: authorization required.
  Open this URL in your browser:

    https://mcp.linear.app/authorize?response_type=code&...

  Or paste the redirect URL here (or the ?code=...&state=... portion) and press Enter:
> https://mcp.linear.app/callback?code=abc123&state=xyz
  Got authorization code from paste — completing flow.

A bare ?code=...&state=... query string is accepted too. This works for any MCP server with auth: oauth and requires no SSH config changes. Option 2 — SSH port forward (same as Spotify). Mibyan prints the exact port it bound to in the SSH-session hint. Open a separate terminal on your laptop:

ssh -N -L <port>:127.0.0.1:<port> user@remote-host

Then open the authorize URL in your browser as normal; the redirect tunnels through and the listener picks it up. Use this when you need the flow to complete unattended (e.g. scripted re-auth where you can’t paste interactively). Pitfall — the 30s config-reload race. If you edit ~/.mibyan/config.yaml to add an OAuth MCP server from inside a running Mibyan session, the CLI auto-reloads MCP connections with a 30s timeout. That’s not enough time to complete an interactive OAuth flow, and the reload will give up. Use mibyan mcp login <server> from a fresh terminal instead — it has no such cap and waits the full 5 min for you to paste back.

Why the listener can’t just bind 0.0.0.0

Spotify and most MCP OAuth servers validate the redirect_uri parameter against an allowlist. Both require the loopback form (http://127.0.0.1:<exact-port>/callback). Binding the listener to 0.0.0.0 or a different port would cause the auth server to reject the request as a redirect_uri mismatch. The SSH tunnel keeps the loopback URI intact end-to-end.

Step-by-step: single SSH hop

1. Start the tunnel from your local machine

# Spotify (port 43827)
ssh -N -L 43827:127.0.0.1:43827 user@remote-host

-N means “don’t open a remote shell, just hold the tunnel open.” Keep this terminal running for the duration of the login.

2. In a separate SSH session, run the auth command

ssh user@remote-host
mibyan auth spotify --no-browser

Mibyan detects the SSH session, skips the browser auto-open, and prints an authorize URL plus a Waiting for callback on http://127.0.0.1:<port>/callback line.

3. Open the URL in your local browser

Copy the authorize URL from the remote terminal and paste it into the browser on your laptop. Approve the consent screen. The auth server redirects to http://127.0.0.1:<port>/callback. Your browser hits the tunnel, the request is forwarded to the remote listener, and Mibyan prints Login successful!. You can tear down the tunnel (Ctrl+C in the first terminal) once you see the success line.

Step-by-step: through a jump box

If you reach Mibyan through a bastion / jump host, use SSH’s built-in -J (ProxyJump):

ssh -N -L 43827:127.0.0.1:43827 -J jump-user@jump-host user@final-host

This chains a SSH connection through the jump host without putting the loopback port on the jump box itself. The local 127.0.0.1:43827 on your laptop tunnels straight through to 127.0.0.1:43827 on the final remote host. For older OpenSSH that doesn’t support -J, the long form is:

ssh -N \
    -o "ProxyCommand=ssh -W %h:%p jump-user@jump-host" \
    -L 43827:127.0.0.1:43827 \
    user@final-host

Mosh, tmux, ssh ControlMaster

The tunnel is a property of the underlying SSH connection. If you’re running Mibyan inside tmux over a mosh session, the mosh roaming doesn’t carry the -L forwarding. Open a separate plain SSH session only for the -L tunnel — that’s the connection that has to stay alive during the auth flow. Your interactive mosh/tmux session can keep running Mibyan normally. If you use ssh -o ControlMaster=auto, port forwards on a multiplexed connection share the master’s lifetime. Restart the master if the tunnel doesn’t come up:

ssh -O exit user@remote-host
ssh -N -L 43827:127.0.0.1:43827 user@remote-host

Troubleshooting

`bind [127.0.0.1]:43827: Address already in use`

Something on your laptop is already using that port. Either the previous tunnel didn’t shut down cleanly, or a local Mibyan is also listening on it. Find and kill the offender:

# macOS / Linux
lsof -iTCP:43827 -sTCP:LISTEN
kill <PID>

Then retry the ssh -L command.

Authorization timed out waiting for the local callback

The redirect never made it back to the remote listener. Check the tunnel is still alive (ssh -N doesn’t show output, so look at the terminal you started it from), confirm you used the port from the latest Waiting for callback on ... line (Mibyan may auto-bump if the preferred port is busy), restart the tunnel if needed, and re-run the auth command.

Tokens land in the wrong `~/.mibyan`

The tokens are written under the Linux user that ran mibyan auth add .... If your gateway / systemd service runs as a different user (e.g. root or a dedicated mibyan user), authenticate as that user so the tokens land in their ~/.mibyan/auth.json. sudo -u mibyan -i or equivalent.

تطبيق ديسكتوب

البداية

استخدام مبيان

الميزات

منصات المراسلة

التكاملات

الأدلة والدروس

دليل المطوّر

المرجع

OAuth over SSH / Remote Hosts

TL;DR

Which Providers Need This

MCP Servers

Why the listener can’t just bind 0.0.0.0

Step-by-step: single SSH hop

1. Start the tunnel from your local machine

2. In a separate SSH session, run the auth command

3. Open the URL in your local browser

Step-by-step: through a jump box

Mosh, tmux, ssh ControlMaster

Troubleshooting

`bind [127.0.0.1]:43827: Address already in use`

Authorization timed out waiting for the local callback

Tokens land in the wrong `~/.mibyan`

See Also

​TL;DR

​Which Providers Need This

​MCP Servers

​Why the listener can’t just bind 0.0.0.0

​Step-by-step: single SSH hop

​1. Start the tunnel from your local machine

​2. In a separate SSH session, run the auth command

​3. Open the URL in your local browser

​Step-by-step: through a jump box

​Mosh, tmux, ssh ControlMaster

​Troubleshooting

​bind [127.0.0.1]:43827: Address already in use

​Authorization timed out waiting for the local callback

​Tokens land in the wrong ~/.mibyan

​See Also

TL;DR

Which Providers Need This

MCP Servers

Why the listener can’t just bind 0.0.0.0

Step-by-step: single SSH hop

1. Start the tunnel from your local machine

2. In a separate SSH session, run the auth command

3. Open the URL in your local browser

Step-by-step: through a jump box

Mosh, tmux, ssh ControlMaster

Troubleshooting

`bind [127.0.0.1]:43827: Address already in use`

Authorization timed out waiting for the local callback

Tokens land in the wrong `~/.mibyan`

See Also