From 46e4c556367ea7637908fc778376699731557e59 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Sat, 29 Aug 2026 21:52:17 +0000 Subject: [PATCH 1/6] Add fx integration guide and document headless MCP auth Verified end-to-end: fx connects to Kernel's MCP server, creates a browser session, runs execute_playwright_code, and cleans up. OAuth (the CLI-installed default) only works in an interactive session, so document the bearer_token_env path for fx ask/fx acp/CI. --- docs.json | 3 +- integrations/overview.mdx | 1 + integrations/vercel/fx.mdx | 45 +++++++++++++++++++++++++++++ integrations/vercel/overview.mdx | 6 ++++ reference/mcp-server/clients/fx.mdx | 26 +++++++++++++++++ 5 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 integrations/vercel/fx.mdx diff --git a/docs.json b/docs.json index 45148ed..fddad90 100644 --- a/docs.json +++ b/docs.json @@ -227,7 +227,8 @@ "integrations/vercel/ai-sdk", "integrations/vercel/marketplace", "integrations/vercel/eve-extension", - "integrations/vercel/foreman" + "integrations/vercel/foreman", + "integrations/vercel/fx" ] }, "integrations/vibium", diff --git a/integrations/overview.mdx b/integrations/overview.mdx index 5efd385..b009657 100644 --- a/integrations/overview.mdx +++ b/integrations/overview.mdx @@ -28,6 +28,7 @@ This approach works with any computer use model, including Anthropic Claude, Ope Kernel provides detailed guides for popular agent frameworks: - **[Agent Browser](/integrations/vercel/agent-browser)** - Browser automation CLI for AI agents +- **[fx](/integrations/vercel/fx)** - Give Vercel's fx coding agent a Kernel cloud browser via MCP - **[Browser Use](/integrations/browser-use)** - AI browser agent framework - **[Hermes Agent](/integrations/hermes-agent)** - Run Hermes browser tools on Kernel cloud browsers - **[Claude Code and Desktop](/integrations/claude/claude-code-and-desktop)** - Give the Claude apps a Kernel browser via the marketplace plugin or MCP diff --git a/integrations/vercel/fx.mdx b/integrations/vercel/fx.mdx new file mode 100644 index 0000000..69cb961 --- /dev/null +++ b/integrations/vercel/fx.mdx @@ -0,0 +1,45 @@ +--- +title: "fx" +description: "Give Vercel's fx coding agent a Kernel cloud browser via MCP" +--- + +## Overview + +[fx](https://github.com/vercel-labs/fx) is Vercel Labs' native CLI coding agent — a minimalist, terminal-first agent with a small built-in tool surface and first-class MCP support. Instead of loading every connected server's full tool list up front, fx searches for the right capability on demand and only pulls in the tool it needs, which keeps context usage low even with several MCP servers connected. + +Connecting Kernel's [MCP server](/reference/mcp-server) gives fx a real cloud browser: it can create a session, drive it with Playwright via [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code), and tear it down — the same toolset described in the [MCP server reference](/reference/mcp-server), including managed auth, profiles, proxies, and replays. + +## Setup + +Follow the [fx client guide](/reference/mcp-server/clients/fx) to add Kernel to `~/.fx/mcp.json`. Two paths, depending on how you run fx: + +- **Interactive session (recommended)** — `kernel mcp install --target fx`, then `/mcp reload` and `/mcp auth kernel --open` to authorize via OAuth in a browser. +- **Headless or scripted (`fx ask`, `fx acp`, CI)** — OAuth needs a browser, so it doesn't work outside an interactive session. Use a Kernel API key with `bearer_token_env` instead; see [Headless and scripted use](/reference/mcp-server/clients/fx#headless-and-scripted-use) for the config. + +## Example + +With Kernel connected, fx can drive a browser from a single prompt: + +```bash +fx ask "Using the kernel MCP server, create a browser session, navigate to https://example.com, return the page title, then delete the session." +``` + +fx searches its connected servers for the right capability, calls `manage_browsers` to create the session, `execute_playwright_code` to read the title, and `manage_browsers` again to delete it: + +``` +Example Domain +``` + +## Related + + + + Full setup steps, including headless auth + + + All tools the Kernel MCP server exposes + + + Run Playwright against a session + + diff --git a/integrations/vercel/overview.mdx b/integrations/vercel/overview.mdx index a1a524d..b42b31a 100644 --- a/integrations/vercel/overview.mdx +++ b/integrations/vercel/overview.mdx @@ -13,6 +13,12 @@ Kernel and Vercel have partnered to provide seamless browser automation capabili [Learn more about Agent Browser →](/integrations/vercel/agent-browser) +### fx + +[fx](https://github.com/vercel-labs/fx) is Vercel Labs' native CLI coding agent. Connect it to Kernel's MCP server and it can create a cloud browser session, drive it with Playwright, and tear it down as part of its normal tool use. + +[Learn more about fx →](/integrations/vercel/fx) + ### AI SDK Tool for Browser Automation The `@onkernel/ai-sdk` package provides a Vercel AI SDK-compatible tool that enables AI agents to execute Playwright code on Kernel remote browsers. This tool integrates seamlessly with: diff --git a/reference/mcp-server/clients/fx.mdx b/reference/mcp-server/clients/fx.mdx index 2740185..9cc5ae8 100644 --- a/reference/mcp-server/clients/fx.mdx +++ b/reference/mcp-server/clients/fx.mdx @@ -42,3 +42,29 @@ Then authenticate with Kernel: ``` Authorize access in the browser window that opens. You can then run `/mcp list` to verify that Kernel is connected. + +## Headless and scripted use + +`/mcp auth` needs a browser, so it only works in an interactive `fx` session. Non-interactive runs — `fx ask`, `fx acp`, CI — can't complete it: fx returns `Run /mcp auth for this server in an interactive fx session` and the Kernel tools aren't discoverable. + +For these, authenticate with a Kernel API key instead of OAuth. Get one from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys), export it, and reference it from `~/.fx/mcp.json` with `bearer_token_env`: + +```bash +export KERNEL_API_KEY="sk_..." +``` + +```json +{ + "mcp": { + "kernel": { + "type": "http", + "url": "https://mcp.onkernel.com/mcp", + "bearer_token_env": "KERNEL_API_KEY" + } + } +} +``` + +fx rejects a literal `Authorization` header in a static `headers` field (the format other MCP clients use for API-key auth) to keep credentials out of the profile file. `bearer_token_env` is the fx-specific equivalent — it points at an environment variable instead of embedding the token. + +Running `kernel mcp install --target fx` always writes the OAuth config above, so switch to `bearer_token_env` by hand for headless use. From 47f61904a350168a7df147b4ef483e78a71d8640 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Mon, 31 Aug 2026 16:13:45 +0000 Subject: [PATCH 2/6] Trim fx guide to point at the MCP client doc instead of duplicating it Keep the fx page focused on why to connect Kernel and a working example; setup steps live in one place (the client reference page) instead of two. --- integrations/vercel/fx.mdx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/integrations/vercel/fx.mdx b/integrations/vercel/fx.mdx index 69cb961..3025eff 100644 --- a/integrations/vercel/fx.mdx +++ b/integrations/vercel/fx.mdx @@ -9,12 +9,7 @@ description: "Give Vercel's fx coding agent a Kernel cloud browser via MCP" Connecting Kernel's [MCP server](/reference/mcp-server) gives fx a real cloud browser: it can create a session, drive it with Playwright via [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code), and tear it down — the same toolset described in the [MCP server reference](/reference/mcp-server), including managed auth, profiles, proxies, and replays. -## Setup - -Follow the [fx client guide](/reference/mcp-server/clients/fx) to add Kernel to `~/.fx/mcp.json`. Two paths, depending on how you run fx: - -- **Interactive session (recommended)** — `kernel mcp install --target fx`, then `/mcp reload` and `/mcp auth kernel --open` to authorize via OAuth in a browser. -- **Headless or scripted (`fx ask`, `fx acp`, CI)** — OAuth needs a browser, so it doesn't work outside an interactive session. Use a Kernel API key with `bearer_token_env` instead; see [Headless and scripted use](/reference/mcp-server/clients/fx#headless-and-scripted-use) for the config. +For setup, follow the [fx client guide](/reference/mcp-server/clients/fx) — it covers both the interactive OAuth path and the API-key path needed for headless runs (`fx ask`, `fx acp`, CI). ## Example From 79ee9a281ea3bf29538ad5ffb84a7bbd162f71e6 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 1 Sep 2026 14:23:49 +0000 Subject: [PATCH 3/6] Document fx OAuth issuer-mismatch bug and API-key workaround OAuth currently fails for fx (interactively, not just headless) with an RFC 9207 issuer mismatch: Kernel's /authorize redirects straight to Clerk without restamping the issuer, so Clerk's response carries iss=clerk.onkernel.com instead of the advertised mcp.onkernel.com. fx verifies this strictly and rejects the flow before token exchange. Note it on the fx client page with the current error text and the bearer_token_env workaround, and add a general troubleshooting entry so other clients that start doing strict issuer verification have somewhere to land on the same fix. --- reference/mcp-server/clients/fx.mdx | 31 +++++++++++++++++------- reference/mcp-server/troubleshooting.mdx | 8 ++++++ 2 files changed, 30 insertions(+), 9 deletions(-) diff --git a/reference/mcp-server/clients/fx.mdx b/reference/mcp-server/clients/fx.mdx index 9cc5ae8..94288ff 100644 --- a/reference/mcp-server/clients/fx.mdx +++ b/reference/mcp-server/clients/fx.mdx @@ -3,6 +3,18 @@ title: "fx" description: "Connect fx to the Kernel MCP server" --- + +OAuth currently fails for fx, interactively or otherwise, with: + +```text +MCP authentication for 'kernel' was rejected: expected issuer "https://mcp.onkernel.com" but +the authorization response returned issuer "https://clerk.onkernel.com". fx stopped before token +exchange. +``` + +This is a known server-side issue — see [Troubleshooting](/reference/mcp-server/troubleshooting#oauth-issuer-mismatch-on-strict-clients) — not something to fix client-side. Until it's resolved, [connect with an API key](#connect-with-an-api-key-workaround) instead of OAuth. + + ## Install with the Kernel CLI Run the following command: @@ -43,15 +55,11 @@ Then authenticate with Kernel: Authorize access in the browser window that opens. You can then run `/mcp list` to verify that Kernel is connected. -## Headless and scripted use +This is also the path that would otherwise be needed for headless or scripted use — `/mcp auth` needs a browser, so `fx ask`, `fx acp`, and CI can't complete it even once the OAuth issuer bug above is fixed. Use the API-key workaround below for those regardless. -`/mcp auth` needs a browser, so it only works in an interactive `fx` session. Non-interactive runs — `fx ask`, `fx acp`, CI — can't complete it: fx returns `Run /mcp auth for this server in an interactive fx session` and the Kernel tools aren't discoverable. +## Connect with an API key (workaround) -For these, authenticate with a Kernel API key instead of OAuth. Get one from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys), export it, and reference it from `~/.fx/mcp.json` with `bearer_token_env`: - -```bash -export KERNEL_API_KEY="sk_..." -``` +Get a project-scoped Kernel API key from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys), export it, and reference it from `~/.fx/mcp.json` with `bearer_token_env` instead of `oauth`: ```json { @@ -65,6 +73,11 @@ export KERNEL_API_KEY="sk_..." } ``` -fx rejects a literal `Authorization` header in a static `headers` field (the format other MCP clients use for API-key auth) to keep credentials out of the profile file. `bearer_token_env` is the fx-specific equivalent — it points at an environment variable instead of embedding the token. +```bash +export KERNEL_API_KEY='' +fx +``` + +This works for both interactive and headless/scripted sessions (`fx ask`, `fx acp`, CI). `kernel mcp install --target fx` always writes the OAuth config, so switch to `bearer_token_env` by hand. -Running `kernel mcp install --target fx` always writes the OAuth config above, so switch to `bearer_token_env` by hand for headless use. +fx rejects a literal `Authorization` header in a static `headers` field (the format other MCP clients use for API-key auth) to keep credentials out of the profile file. `bearer_token_env` is the fx-specific equivalent — it points at an environment variable instead of embedding the token. diff --git a/reference/mcp-server/troubleshooting.mdx b/reference/mcp-server/troubleshooting.mdx index 61b5702..acb82f6 100644 --- a/reference/mcp-server/troubleshooting.mdx +++ b/reference/mcp-server/troubleshooting.mdx @@ -7,3 +7,11 @@ description: "Fix connection and authentication issues with the Kernel MCP serve - **Clear saved auth and retry:** `rm -rf ~/.mcp-auth` - **Node.js version:** Ensure a recent Node.js version when using `npx mcp-remote`. - **Strict networks:** If behind strict networks, try stdio via `mcp-remote`, or explicitly set the transport your client supports. + +## OAuth issuer mismatch on strict clients + +The Kernel MCP server's OAuth discovery metadata advertises `issuer: https://mcp.onkernel.com`, but `/authorize` currently redirects straight to Clerk without an intermediate callback that re-stamps the issuer. Clerk completes the flow directly, so the authorization response carries `iss: https://clerk.onkernel.com` instead — a mismatch per [RFC 9207](https://www.rfc-editor.org/rfc/rfc9207). + +Most clients (Cursor, Claude, VS Code, Zed, goose) don't check this and are unaffected. Clients that do strict RFC 9207 issuer verification — currently [fx](/reference/mcp-server/clients/fx) — reject the OAuth flow outright with an issuer-mismatch error and stop before token exchange. This is a server-side bug, not a client misconfiguration; don't change a client's `oauth.issuer` to work around it. + +**Workaround:** connect with an API key instead of OAuth. Get a project-scoped key from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys) and configure it the way your client expects a bearer token (e.g. fx's [`bearer_token_env`](/reference/mcp-server/clients/fx#connect-with-an-api-key-workaround)). See [Authentication](/reference/mcp-server/authentication#api-key-authentication) for the general API-key format. From 6ba5e365dfc590cb0ce96084288be2e297699421 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 1 Sep 2026 14:37:41 +0000 Subject: [PATCH 4/6] Lead troubleshooting entry with the fix, not the root cause Symptom and workaround first so it reads generically for any client that hits strict OAuth issuer verification, not just fx; root cause follows as supporting detail. --- reference/mcp-server/troubleshooting.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/reference/mcp-server/troubleshooting.mdx b/reference/mcp-server/troubleshooting.mdx index acb82f6..2a5f185 100644 --- a/reference/mcp-server/troubleshooting.mdx +++ b/reference/mcp-server/troubleshooting.mdx @@ -10,8 +10,6 @@ description: "Fix connection and authentication issues with the Kernel MCP serve ## OAuth issuer mismatch on strict clients -The Kernel MCP server's OAuth discovery metadata advertises `issuer: https://mcp.onkernel.com`, but `/authorize` currently redirects straight to Clerk without an intermediate callback that re-stamps the issuer. Clerk completes the flow directly, so the authorization response carries `iss: https://clerk.onkernel.com` instead — a mismatch per [RFC 9207](https://www.rfc-editor.org/rfc/rfc9207). +If you have issues connecting with OAuth on a client that does strict [RFC 9207](https://www.rfc-editor.org/rfc/rfc9207) issuer verification — an error rejecting the flow before token exchange because the returned issuer doesn't match what discovery advertised — connect with an API key instead of OAuth. Get a project-scoped key from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys) and configure it the way your client expects a bearer token (e.g. fx's [`bearer_token_env`](/reference/mcp-server/clients/fx#connect-with-an-api-key-workaround)). See [Authentication](/reference/mcp-server/authentication#api-key-authentication) for the general API-key format. -Most clients (Cursor, Claude, VS Code, Zed, goose) don't check this and are unaffected. Clients that do strict RFC 9207 issuer verification — currently [fx](/reference/mcp-server/clients/fx) — reject the OAuth flow outright with an issuer-mismatch error and stop before token exchange. This is a server-side bug, not a client misconfiguration; don't change a client's `oauth.issuer` to work around it. - -**Workaround:** connect with an API key instead of OAuth. Get a project-scoped key from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys) and configure it the way your client expects a bearer token (e.g. fx's [`bearer_token_env`](/reference/mcp-server/clients/fx#connect-with-an-api-key-workaround)). See [Authentication](/reference/mcp-server/authentication#api-key-authentication) for the general API-key format. +This happens because the Kernel MCP server's OAuth discovery metadata advertises `issuer: https://mcp.onkernel.com`, but `/authorize` currently redirects straight to Clerk without an intermediate callback that re-stamps the issuer, so the authorization response carries `iss: https://clerk.onkernel.com` instead. Most clients (Cursor, Claude, VS Code, Zed, goose) don't check this and are unaffected; clients that do — currently [fx](/reference/mcp-server/clients/fx) — reject the flow outright. This is a server-side bug, not a client misconfiguration; don't change a client's `oauth.issuer` to work around it. From 4f3edd8300577d25b6ce9968bc646e431a13ed68 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 1 Sep 2026 15:08:05 +0000 Subject: [PATCH 5/6] Drop root-cause detail from OAuth workaround docs Keep the symptom and fix; leave out the issuer-mismatch mechanics. --- reference/mcp-server/clients/fx.mdx | 2 +- reference/mcp-server/troubleshooting.mdx | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/reference/mcp-server/clients/fx.mdx b/reference/mcp-server/clients/fx.mdx index 94288ff..a03ed85 100644 --- a/reference/mcp-server/clients/fx.mdx +++ b/reference/mcp-server/clients/fx.mdx @@ -12,7 +12,7 @@ the authorization response returned issuer "https://clerk.onkernel.com". fx stop exchange. ``` -This is a known server-side issue — see [Troubleshooting](/reference/mcp-server/troubleshooting#oauth-issuer-mismatch-on-strict-clients) — not something to fix client-side. Until it's resolved, [connect with an API key](#connect-with-an-api-key-workaround) instead of OAuth. +Until it's resolved, [connect with an API key](#connect-with-an-api-key-workaround) instead of OAuth. ## Install with the Kernel CLI diff --git a/reference/mcp-server/troubleshooting.mdx b/reference/mcp-server/troubleshooting.mdx index 2a5f185..7316e2f 100644 --- a/reference/mcp-server/troubleshooting.mdx +++ b/reference/mcp-server/troubleshooting.mdx @@ -11,5 +11,3 @@ description: "Fix connection and authentication issues with the Kernel MCP serve ## OAuth issuer mismatch on strict clients If you have issues connecting with OAuth on a client that does strict [RFC 9207](https://www.rfc-editor.org/rfc/rfc9207) issuer verification — an error rejecting the flow before token exchange because the returned issuer doesn't match what discovery advertised — connect with an API key instead of OAuth. Get a project-scoped key from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys) and configure it the way your client expects a bearer token (e.g. fx's [`bearer_token_env`](/reference/mcp-server/clients/fx#connect-with-an-api-key-workaround)). See [Authentication](/reference/mcp-server/authentication#api-key-authentication) for the general API-key format. - -This happens because the Kernel MCP server's OAuth discovery metadata advertises `issuer: https://mcp.onkernel.com`, but `/authorize` currently redirects straight to Clerk without an intermediate callback that re-stamps the issuer, so the authorization response carries `iss: https://clerk.onkernel.com` instead. Most clients (Cursor, Claude, VS Code, Zed, goose) don't check this and are unaffected; clients that do — currently [fx](/reference/mcp-server/clients/fx) — reject the flow outright. This is a server-side bug, not a client misconfiguration; don't change a client's `oauth.issuer` to work around it. From af82a3934d7e95dff72bd66a2f19057f72feda31 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 1 Sep 2026 15:31:02 +0000 Subject: [PATCH 6/6] Swap fx example to a Hacker News top-5 scrape More illustrative than a static title fetch; verified end-to-end via fx ask against the real Kernel MCP server. --- integrations/vercel/fx.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/integrations/vercel/fx.mdx b/integrations/vercel/fx.mdx index 3025eff..939055e 100644 --- a/integrations/vercel/fx.mdx +++ b/integrations/vercel/fx.mdx @@ -16,13 +16,17 @@ For setup, follow the [fx client guide](/reference/mcp-server/clients/fx) — it With Kernel connected, fx can drive a browser from a single prompt: ```bash -fx ask "Using the kernel MCP server, create a browser session, navigate to https://example.com, return the page title, then delete the session." +fx ask "Using the kernel MCP server, create a browser session, navigate to https://news.ycombinator.com, return the titles of the top 5 articles, then delete the session." ``` -fx searches its connected servers for the right capability, calls `manage_browsers` to create the session, `execute_playwright_code` to read the title, and `manage_browsers` again to delete it: +fx searches its connected servers for the right capability, calls `manage_browsers` to create the session, `execute_playwright_code` to scrape the titles, and `manage_browsers` again to delete it. A run looked like this (front page changes, so yours will differ): ``` -Example Domain +1. AnkiDroid: Google Play no longer allowing Open Collective donation link +2. Ask HN: Who is hiring? (September 2026) +3. Urban Congestion Pricing and the Response Times of Emergency Medical Services +4. 44% on ARC-AGI-1 in 67 cents +5. Io_uring Without Readahead ``` ## Related