Archestra Logo
Star us on GitHub ⭐

Browser-Based Authentication

3 min read

Security Consideration

Browser-based authentication is a way to extract a user's API token by asking the user to log in through a browser window raised by Archestra. This option dramatically simplifies the initial setup, but users could be concerned with the need to enter their login/password in the window generated by Archestra. We would like to address this concern directly by providing you with comprehensive information about the mechanism involved below.

It's important to note that:

  1. Archestra is open source, meaning anyone can review the browser component.
  2. It's an optional usability feature. Users not feeling comfortable entering their credentials in a browser window raised by Archestra can always use API keys directly.

Try it Yourself

This guide covers how to add authentication to an MCP server using the built-in browser by extracting tokens and cookies from the service.

Open the app, navigate to LLM Providers → Ollama, and download gpt-oss:20b, qwen3:8b, or qwen3:14b.

Try installing an existing MCP server with browser auth:

  1. Open Connectors
  2. Find the Slack MCP server
  3. Click on "Install (Browser)"
  4. Log in with your email/password, choose a workspace, and click "use Slack in your browser"
  5. Navigate to Servers and find your installed MCP server
  6. Open "+ New chat", ensure you have a capable LLM model (either cloud-based models or Ollama's gpt-oss:20b, qwen3:8b, etc.)
  7. Prompt it with "read the last messages in #general"

Add Browser-Based Auth to a New MCP

Here's how a browser-based auth provider was added to the Slack MCP Server (https://www.archestra.ai/mcp-catalog/korotovsky__slack-mcp-server):

  1. First, follow the MCP server's README and start the MCP server locally with the MCP inspector (https://modelcontextprotocol.io/legacy/tools/inspector) to verify it works before adding it to Archestra.

  2. Find the MCP server JSON in the catalog: https://github.com/archestra-ai/website/blob/main/app/app/mcp-catalog/data/mcp-evaluations/korotovsky__slack-mcp-server.json

  3. Copy the file (or create a new one) to desktop_app/src/ui/catalog_local. The MCP server will appear on the "Connections" page with a purple "Developer" tag, allowing you to modify and work with it without running the catalog.

  4. Ensure that server is correct and matches the configuration you ran in step 1.

{
  "command": "npx",
  "args": ["-y", "slack-mcp-server@latest", "--transport", "stdio"],
  "env": {
    "SLACK_MCP_XOXC_TOKEN": "${user_config.slack_mcp_xoxc_token}",
    "SLACK_MCP_XOXD_TOKEN": "${user_config.slack_mcp_xoxd_token}",
    "SLACK_MCP_ADD_MESSAGE_TOOL": "${user_config.slack_mcp_add_message_tool}"
  }
}
  1. Find the archestra_config section and add browser_based.required: true:
  "archestra_config": {
  ...
    "oauth": {
      "provider": "slack",
      "required": true
    },
    "browser_based": {
      "required": true
    }
    ...
  }

  1. Create a Browser Provider Definition
    Create desktop_app/src/backend/server/plugins/browser-auth/providers/slack-browser.ts, following the pattern "<provider_name>-browser.ts". This defines how authentication works: where to navigate, how to extract tokens or cookies, which URLs are allowed, and which ENV variables to add to the container.

  2. (Optional) Add a utility for your browser provider if it needs complex token extraction logic. Here's an example for Slack: desktop_app/src/backend/server/plugins/browser-auth/utils/slack-token-extractor.ts

  3. Update the Provider Registry: desktop_app/src/backend/server/plugins/browser-auth/provider-registry.ts

    NOTE: Add 'slack-browser': slackBrowserProvider, to oauthProviders, and don't forget to re-export it in the end of the file

  4. After launching the app, click "Install (Browser)" and log in. Tokens will be extracted and stored in the database along with the catalog configs. You can run pnpm db:studio to view the mcp_servers table.

  5. Podman detects the new database entry and starts the container with the MCP server. Use the following commands to debug the container (make sure to use our binary, otherwise you won't be able to access it):

./desktop_app/resources/bin/mac/arm64/podman-remote-static-v5.5.2 container ls --all
./desktop_app/resources/bin/mac/arm64/podman-remote-static-v5.5.2 rm -a -f
./desktop_app/resources/bin/mac/arm64/podman-remote-static-v5.5.2 exec -it CONTAINER_ID sh
  1. You're all set! Your MCP server should now appear in Settings → Servers, and its tools should be available in chat. Verify that tool calling works as expected.