How to Configure Raycast AI Tools for Third-Party Extensions and Local Apps on macOS

For macOS power users, software engineers, and technical product managers, keyboard launchers like Raycast serve as the primary nerve center for daily workflows. However, many users still interact with Raycast AI as a standard conversational chatbot, confining it to isolated text generation while manually switching across GitHub, Linear, Notion, the terminal, and the filesystem to complete their work.

Raycast bridges this gap through AI Tools (often termed AI Extensions). By implementing native function calling and tool execution directly inside Raycast Chat and Quick AI, Raycast allows modern large language models—such as Claude 3.5 Sonnet and GPT-4o—to autonomously discover, inspect, and invoke actions across local system utilities and third-party SaaS extensions.

This guide details how to install tool-enabled extensions, trigger and chain multi-extension queries in AI Chat, establish safe permission and auto-review boundaries, fine-tune tool behavior with custom instructions, and integrate custom Model Context Protocol (MCP) servers to turn your Mac into an agentic desktop command center.

1. Prerequisites and Architectural Foundations

Before configuring AI Tools, ensure your desktop setup meets the necessary runtime requirements:

• Raycast Version & Pro Subscription: AI Tools and AI Chat require a Raycast Pro subscription. Pro unlocks access to advanced frontier models (such as Claude 3.5 Sonnet and GPT-4o), extended context windows, and tool-calling execution engines.
• Tool-Calling Model Selection: Tool interactions depend on underlying models that support native function calling. In Raycast, verify that your active model in AI Chat or Settings → AI → Models supports tool use.
• Separation of Standard Commands vs. AI Tools: Standard Raycast commands run within the main launcher interface to present user-facing views (such as list views or detail screens). In contrast, AI Tools are invisible background functions declared by extensions that the AI model calls programmatically to fetch data or trigger actions on your behalf.

2. Discovering and Installing Tool-Enabled Extensions

Raycast ships with essential built-in system tools, while third-party integrations can be installed directly from the Raycast Store.

Native Built-in System Tools

Raycast includes built-in tools ready to use without extra setup:

• @finder: Searches, inspects, and manages local files and directories on macOS.
• @file-search: Fast local file discovery powered by indexed file search.
• @terminal: Executes shell commands and evaluates terminal outputs directly from chat.
• @clipboard: Searches clipboard history, inspects clipboard snippets, and replaces clipboard contents.
• @browser: Reads and analyzes DOM contents of the currently active browser tab (requires the free Raycast Browser Companion extension).
• @screen-awareness: Captures window context, selected text, and visual screenshots of the focused frontmost application.
• @calendar: Inspects upcoming meetings, agenda items, and schedule availability.
• @raycast-notes: Reads, searches, and appends notes to your local Raycast Notes workspace.

Installing Third-Party Extensions via Store Filters

To connect Raycast AI with cloud collaboration services like GitHub, Linear, Jira, or Notion:

1. Press your Raycast hotkey (e.g., ⌥ Space or ⌘ Space) to open Root Search.
2. Type Store and press Return.
3. Press ⌘ P to open the category filter dropdown in the navigation bar.
4. Select the AI Extensions filter. This isolates extensions that implement background tool endpoints rather than standalone UI commands.
5. Highlight your desired extension (e.g., GitHub, Linear, Notion, Todoist, Spotify) and press Return to install.
6. Complete extension authentication. When first opened, extensions will prompt you to connect via OAuth or supply an API token or Personal Access Token (PAT).

3. Triggering and Chaining Tools in AI Chat

Once installed, extensions expose their tools to both AI Chat (AI Chat command or ⌘ J from Quick AI) and Quick AI.

The @ Mention Syntax

In the AI Chat composer, type @. A dropdown appears displaying all active tools and extensions installed on your Mac. Select an extension from the list or continue typing its handle:

@github Find open pull requests where my review is requested and summarize blocking comments.

@linear Create an issue titled "Implement rate limiting for webhook ingestion" in the Infrastructure team with high priority.

@browser Summarize the API documentation page currently open in Arc and highlight breaking endpoint changes.

When you hit Return, the model determines whether it needs to fetch preliminary information, constructs the appropriate parameter payload, and invokes the extension tool in the background. The chat transcript displays a collapsible execution card showing tool inputs and returned data.

Multi-Tool Chaining in Single Prompts

Power users can orchestrate multi-step automations across independent applications by referencing multiple tools in a single query:

@calendar @linear What meetings do I have scheduled this afternoon, and are there any Linear tickets in current sprint assigned to me that need updates before standup?

@terminal @github Check git status in my current repo directory, summarize recent commits, and draft a pull request description for GitHub.

The model plans intermediate steps sequentially: it first queries the calendar and git status, aggregates the outputs into context, and subsequently executes the follow-up tasks without requiring manual copy-pasting.

4. Configuring Permissions, Auto-Review Rules, and Security

Because AI Tools can execute shell commands, alter file trees, or create and delete remote SaaS records, Raycast provides granular security controls to prevent unintended side effects.

Global Permission Levels

Navigate to Settings → AI → Tools to choose your system-wide security posture:

What the "Auto" Mode Approves Automatically

Raycast's Auto engine uses intelligent heuristics:

• Approved without prompts: Read-only queries (e.g., fetching issues, checking calendars, reading files), file edits restricted within the chat's selected working directory, and standard developer inspection commands (such as git status, git log, npm test).
• Always paused for confirmation: Destructive actions (deleting files, dropping database records, closing tickets), shell commands containing mutation flags, and attempts to read sensitive system paths or credentials (such as .env files, SSH keys, or AWS credential files).

Approval Prompts and Hotkeys

When a tool call requires confirmation, AI Chat suspends execution and displays an action card:

• Press Return: Allow the tool to execute once.
• Press ⌘ Return: Always Allow this specific tool. Raycast registers it to Globally Allowed Tools under Settings → AI → Tools, bypassing future confirmation prompts.
• Press Esc: Deny execution. The AI is informed of the rejection and will continue the conversation without calling that tool.
• For shell commands executed via @terminal, click Show Command to inspect the raw CLI script before granting permission.

Conversation-Level Overrides

You do not have to apply global security policies universally. Open the settings sidebar inside any active AI Chat window (or press ⌘ K and choose Change Permissions…) to set that conversation to Inherited, Ask, Auto, or Always Allow.

5. Steering Behavior with Extension Custom Instructions

When working with tools like Linear or GitHub, LLMs may lack workspace-specific context, such as default team identifiers, project cycles, or timezone constraints. Raycast solves this by providing per-extension custom instructions.

1. Navigate to Raycast Settings → Extensions.
2. Select your installed extension in the sidebar (for example, Linear or Calendar).
3. In the right panel, find the tool configuration listed alongside extension commands (typically labeled the Ask tool).
4. Locate the Custom Instructions text field.
5. Input contextual guidelines that the model must follow whenever evaluating that extension's tools.

Production-Tested Instruction Examples

For Linear:

Always scope ticket queries to the "Platform Engineering" team. When creating new issues, default the priority to "Medium" unless explicitly stated as urgent, and assign issues to the current active cycle.

For Calendar:

Never schedule or propose meeting slots before 10:00 AM or after 5:30 PM Eastern Time. Always ensure a minimum 15-minute buffer between back-to-back calendar events.

For GitHub:

Focus exclusively on repositories within the "octocorp-dev" organization. Ignore automated dependabot pull requests when listing items awaiting my review.

Whenever you mention @linear or @calendar in chat, Raycast injects these instructions into the prompt payload, eliminating repetitive manual constraints in your everyday queries.

6. Advanced Expansion: Model Context Protocol (MCP)

When public Store extensions do not cover proprietary internal infrastructure, databases, or niche developer tools, macOS power users can connect Model Context Protocol (MCP) servers to Raycast AI.

1. Open Raycast Root Search and execute the Install MCP Server command (or open Manage MCP Servers → Install New Server).
2. Configure the server parameters:
   • Name & Icon: The identifier used in chat @-mentions.
   • Transport: Choose Standard Input/Output (stdio) for local processes or HTTP for remote endpoints.
   • Command & Arguments: For local CLI tools, specify binaries or runtime commands (e.g., npx, python3, or local binaries like uvx).
   • Environment: Provide necessary environment variables, database connection strings, or internal API tokens.
3. Save with ⌘ Return. Raycast initiates the background process, reads the exposed tool schema over JSON-RPC, and integrates the server's tools into AI Chat.

Once registered, custom MCP servers behave identically to native extensions. You can invoke @postgres SELECT count(*) FROM users or query internal microservices with native permission management.

7. Optimizing Power User Workflows

To maximize efficiency with Raycast AI Tools on macOS, implement these best practices:

• Assign Global Hotkeys: Set a dedicated global hotkey for AI Chat under Settings → Extensions → AI → AI Chat (e.g., ⌥ C or ⌃ Space) to summon your conversational tool dashboard instantly from any desktop workspace.
• Leverage Focused Window & Selected Text: Combine tools with Screen Awareness. Highlight code in your IDE or an error in Terminal, trigger Quick AI, and prompt @github search issues matching selected text to connect local context with external SaaS tools without manual copying.
• Audit Allowed Tools Periodically: Inspect Settings → AI → Tools → See Allow List. If an extension has been updated or your security posture changes, click Reset All to restore standard confirmation prompts across all tools.

By connecting third-party store extensions, local Finder and Terminal capabilities, and custom MCP endpoints through Raycast AI Tools, macOS users transform a standard desktop search bar into an autonomous, keyboard-driven productivity hub.

References

• AI Extensions | Raycast Manual
• AI Chat | Raycast Manual
• Model Context Protocol | Raycast Manual
• AI | Raycast Manual