Which integrations are available for this server?

Bridges locally installed Raycast extensions to the Model Context Protocol, enabling AI agents to discover and execute tools from extensions headlessly, including those requiring OAuth authentication and configuration preferences.

How do I use RayBridge?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@RayBridge search for my pending tasks in Notion" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

RayBridge

MCP server that bridges Raycast extensions to any MCP-compatible client.

Discovers locally installed Raycast extensions, loads their tool definitions, and serves them over the Model Context Protocol via stdio or HTTP.

RayBridge TUI

How it works

Scans ~/.config/raycast/extensions/ for installed extensions with tools definitions
Loads OAuth tokens from Raycast's encrypted SQLite database
Registers tools as MCP tools accessible to any MCP client

Extensions that use Raycast UI APIs (List, Detail, Form, etc.) are supported — the UI components are shimmed to no-ops so the underlying tool logic can execute headlessly. Extensions whose tools perform background work (API calls, data lookups, transformations) work best.

Setup

Prerequisites

Bun
Raycast installed with extensions
sqlcipher CLI (for OAuth token access): brew install sqlcipher

Install

bun install

Configure MCP client

Claude Code (~/.claude/settings.json):

{ "mcpServers": { "raybridge": { "command": "bun", "args": ["run", "src/index.ts"], "cwd": "/path/to/raybridge" } } }

Cursor (~/.cursor/mcp.json):

{ "mcpServers": { "raybridge": { "command": "bun", "args": ["run", "src/index.ts"], "cwd": "/path/to/raybridge" } } }

HTTP Transport

The server can also run as an HTTP server for remote MCP clients.

Start the server:

# Default: http://0.0.0.0:3000 bun run start:http # Custom host/port MCP_PORT=8080 MCP_HOST=0.0.0.0 bun run start:http # With API key authentication MCP_API_KEY=your-secret-key bun run start:http # CLI flags also work bun run src/index.ts --http --port 8080 --host 0.0.0.0

Endpoints:

Endpoint	Method	Description
`/health`	GET	Health check (no auth required)
`/mcp`	POST	MCP requests (requires auth if `MCP_API_KEY` set)
`/mcp`	DELETE	Terminate session

Authentication:

When MCP_API_KEY is set, requests to /mcp must include a Bearer token (per MCP spec):

Authorization: Bearer your-secret-key

Example session:

# 1. Initialize session (capture session ID from response header) curl -X POST http://127.0.0.1:3000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer your-secret-key" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{ "protocolVersion":"2024-11-05", "capabilities":{}, "clientInfo":{"name":"my-client","version":"1.0"} }}' # Response includes: mcp-session-id header # 2. List available tools curl -X POST http://127.0.0.1:3000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer your-secret-key" \ -H "mcp-session-id: <session-id-from-step-1>" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' # 3. Call a tool curl -X POST http://127.0.0.1:3000/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer your-secret-key" \ -H "mcp-session-id: <session-id-from-step-1>" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{ "name":"web", "arguments":{"tool_name":"read_page","input":{"url":"https://example.com"}} }}'

Sessions auto-expire after 30 minutes of inactivity.

CLI

RayBridge includes a CLI for managing which extensions and tools are exposed:

bun link # Register the raybridge command (one-time setup) raybridge # Launch interactive TUI raybridge config # Launch interactive TUI raybridge list # List all extensions and their status raybridge help # Show help

The TUI allows you to:

Toggle extensions on/off
Expand extensions to toggle individual tools
Switch between blocklist mode (all enabled by default) and allowlist mode
Save configuration to ~/.config/raybridge/tools.json

Configuration

Tools configuration

Control which extensions and tools are exposed via ~/.config/raybridge/tools.json:

{ "mode": "blocklist", "extensions": { "extension-name": { "enabled": false }, "another-extension": { "enabled": true, "tools": ["specific-tool-1", "specific-tool-2"] } } }

blocklist mode (default): All extensions enabled unless explicitly disabled
allowlist mode: All extensions disabled unless explicitly enabled

Extension preferences

Extensions that require configuration (API keys, personal access tokens, etc.) read from:

~/.config/ray-ai-tools/preferences.json

{ "extension-name": { "personalAccessToken": "your-token", "apiKey": "your-key" } }

The extension name matches the name field in the extension's package.json.

Architecture

src/ ├── index.ts # MCP server, tool registration, request dispatch ├── http-server.ts # HTTP transport with session management ├── cli.ts # CLI entry point (config, list, help commands) ├── tui.tsx # Interactive TUI for extension configuration ├── config.ts # Tools configuration (blocklist/allowlist) ├── discovery.ts # Scans ~/.config/raycast/extensions/ for tool definitions ├── loader.ts # Executes local tools with Raycast API shims ├── shims.ts # Fake @raycast/api, react, react/jsx-runtime modules ├── auth.ts # Keychain access, SQLcipher DB decryption, OAuth tokens └── watcher.ts # Watches extension directories for changes, triggers reloads

Tool discovery

Local extensions are discovered from ~/.config/raycast/extensions/. Each extension's package.json must have a tools array defining available tools with names, descriptions, and input schemas. Compiled tool code lives at tools/{toolName}.js within each extension directory.

When duplicates exist (same extension name in multiple directories), the most recently modified version wins.

Tool execution

Tools are loaded by installing Raycast API shims into Node's module system, then requiring the tool's compiled JS file and calling its default export with the provided input.

Raycast API shims

The following @raycast/api features are shimmed:

Feature	Behavior
`OAuth.PKCEClient`	Returns tokens from Raycast's encrypted DB
`getPreferenceValues()`	Returns values from `preferences.json`
`environment`	Provides extension name, paths, version info
`Cache`	In-memory key-value store
`showToast`, `showHUD`	No-op (logs to stderr in some cases)
`open`, `closeMainWindow`, `popToRoot`	No-op
`confirmAlert`	Returns `undefined`
UI components (`List`, `Detail`, `Form`, etc.)	Return `null`
`LocalStorage`	No-op
`Clipboard`	No-op

React and JSX runtime are also shimmed with minimal mocks (createElement → null, hooks are no-ops).

Authentication

OAuth tokens are read from Raycast's encrypted SQLite database at:

~/Library/Application Support/com.raycast.macos/raycast-enc.sqlite

The database key is retrieved from macOS Keychain and derived with a salt via SHA256. Tokens are extracted per-extension and provided to tools through the OAuth.PKCEClient shim.

MCP tool schema

Extensions are grouped — each extension becomes one MCP tool. The input schema follows this pattern:

{ "tool_name": "which-tool-to-run", "input": { "param": "value" } }

Tool descriptions include per-tool documentation, parameter details, and any extension-wide AI instructions from the extension's ai.instructions field.

Limitations

No interactive UI — extensions that depend on rendering Lists, Forms, or other visual components to the user won't behave meaningfully
No persistent LocalStorage — shimmed as no-op; extensions relying on it lose state between calls
OAuth tokens are not refreshed — expired tokens will cause failures until Raycast refreshes them
macOS only — depends on macOS Keychain and Raycast's macOS app paths

RayBridge

RayBridge

How it works

Setup

Prerequisites

Install

Configure MCP client

HTTP Transport

CLI

Configuration

Tools configuration

Extension preferences

Architecture

Tool discovery

Tool execution

Raycast API shims

Authentication

MCP tool schema

Limitations

Resources

New MCP Servers

Latest Blog Posts

MCP directory API