Raycast MCP Server Setup 2026: Pro-Only Config Guide
Raycast MCP server setup for 2026: it's a Raycast Pro–only feature, the mcp-config.json file it writes, stdio vs HTTP transports, and the @server-name mention syntax that scopes a chat to one connected tool.
Raycast is a macOS (and, as of 2026, iOS) launcher with a built-in AI layer, and since it added Model Context Protocol support, that AI layer can call the same MCP servers you'd otherwise only wire into an IDE. This guide is not a Cursor, VS Code, or JetBrains setup — it's the launcher-and-command-palette side of the MCP ecosystem, for people who want their MCP-connected tools reachable outside the editor entirely.
One thing to check before anything else: MCP in Raycast is a Pro-exclusive feature. If you're on the free tier, the Install MCP Server command won't do anything useful for you — upgrading is a prerequisite, not an optional nice-to-have, and no config trick works around it.
What you get, in plain terms
| Requires | Raycast Pro subscription |
| Config location | mcp-config.json, in the extension's support directory |
| Transports supported | Standard I/O (local process) and HTTP (remote endpoint) |
| Invocation | @server-name mention inside AI Chat, Quick AI, or AI Commands |
| iOS | Supported since 2026, HTTP transport only — Raycast can't spawn a local stdio process on iOS |
| Auth on HTTP servers | Dynamic or static OAuth, configured per-server in the install form |
Why someone would want MCP in a launcher instead of an IDE
If your MCP-connected workflow is "ask about my Linear issues" or "search my GitHub notifications," you don't necessarily want to open an IDE to do it. Raycast's pitch is that the same MCP tools you'd configure in Cursor become reachable from a global keyboard shortcut, without a code editor in the loop at all. It's a genuinely different use case from the Cursor/VS Code/Windsurf setups covered elsewhere on this site — those are for an agent that edits your code; this is for an agent that answers questions and triggers actions from anywhere on your desktop.
The trade-off is that Raycast's MCP surface is newer and smaller than Cursor's. If a workflow depends on deep codebase context — reading a diff, editing a file, running a build — that belongs in the editor, not the launcher. Raycast is a strong fit for the class of MCP servers that are mostly API calls: issue trackers, calendars, search, docs lookups.
Step 1: Confirm you're on Raycast Pro
Open Raycast, go to your account settings, and confirm an active Pro subscription. AI features generally, and MCP specifically, sit behind that paywall — this isn't a case of a free tier with a reduced MCP feature set, it's not available at all below Pro.
Step 2: Open the install command
Two equivalent paths get you to the same form:
1. Search Raycast's command palette for Install MCP Server, or
2. Run Manage MCP Servers, then choose Install New Server from that list.
Either one opens a form asking for a name, an icon, a transport type, and connection details.
Step 3: Fill in the server details
What you fill in depends on the transport:
Standard I/O (local process). Raycast launches a local process and pipes JSON-RPC over stdin/stdout — the same shape as a command + args MCP entry in Cursor's mcp.json. You'll provide the command, its arguments, and any environment variables the server needs. This is the right choice for an npx-launched server you'd otherwise run locally, and it is not available on iOS, since iOS can't spawn arbitrary local processes.
HTTP (remote endpoint). You provide a URL, optional headers, and an OAuth type — Dynamic or Static — if the server requires auth. This is the only transport iOS supports, and it's the shape you'd use for a hosted MCP endpoint the same way you'd point Cursor at a url-based mcpServers entry rather than a local command.
Raycast's documentation doesn't list SSE as a separate supported transport — stdio and HTTP cover the documented options.
Example: pointing Raycast at a GitLab-style remote server would mean choosing HTTP, entering the /api/v4/mcp-style URL, and letting Raycast walk you through whatever OAuth flow that server expects — conceptually the same authorization step as the GitLab MCP Server Cursor IDE Setup guide covers for Cursor, just initiated from Raycast's install form instead of a JSON file you hand-edit.
Once you press Install MCP Server, Raycast saves the configuration to mcp-config.json in the extension's support directory, starts the connection, and pulls in that server's tool list automatically — there's no separate "verify connection" step to run by hand.
Step 4: Use it with the @ mention
MCP tools in Raycast don't sit in a separate mode — they're reachable from AI Chat, Quick AI, and AI Commands via an @server-name mention. Typing @ and a server name scopes the assistant to that server's tools for the request, similar in spirit to Slack's app-mention syntax:
@linear what's assigned to me this week?
@github summarize the open PRs on my repo
Without the @mention, Raycast AI still has access to every connected server and picks tools it judges relevant — the mention is a way to force the choice rather than let the model guess, which matters more as you connect additional servers and their tool names start to overlap.
Managing servers after install
Return to Manage MCP Servers to see everything you've connected, edit a server's config, or remove one. There's no separate global vs. project-scoped config split the way Cursor has ~/.cursor/mcp.json versus .cursor/mcp.json — Raycast's MCP servers are account-level, available across every context you use Raycast AI in, not scoped to a specific folder or project you happen to have open.
iOS specifics
Raycast added AI Extensions and external MCP server support to its iOS app in 2026. The constraint carries over directly from the transport limitation above: iOS supports HTTP-based remote MCP servers only, since there's no way for a sandboxed iOS app to spawn and manage a local stdio subprocess the way the macOS app can. If a server you rely on only ships a local/stdio configuration, it simply isn't available from the iPhone or iPad app until (or unless) a hosted HTTP version exists.
Where this differs from an IDE-side MCP setup
If you've already configured the same server in Cursor or another IDE, don't expect Raycast to read that configuration — they're entirely separate config surfaces (mcp-config.json in Raycast's extension support directory versus ~/.cursor/mcp.json for Cursor), so a remote HTTP server needs its own OAuth grant and a local stdio server needs its own process launch, one per client. This is normal for MCP generally: authorization and process lifecycle are per-client, not shared system-wide, and it's covered in more general terms in the Local vs Remote MCP Servers guide.
Troubleshooting
Install MCP Server command does nothing useful, or MCP options are missing. Almost always the Pro subscription check. Confirm your account status before troubleshooting the server config itself.
Local stdio server won't start. Check that the command Raycast is trying to run is actually on the PATH Raycast's process sees, which is not guaranteed to be identical to your terminal's PATH — a common cross-client gotcha, not unique to Raycast. If you installed a tool via a version manager (nvm, pyenv), Raycast launching the raw command name without a full path is a frequent failure mode.
HTTP server won't authorize. Confirm you selected the OAuth type — Dynamic or Static — that matches what the server actually documents for its own clients. A server that expects Dynamic Client Registration won't authorize correctly against a Static config expecting a fixed client ID, and vice versa.
@server-name mention doesn't find the server. Confirm the server shows as connected in Manage MCP Servers first — a server stuck mid-authorization won't appear as a mentionable target even though it's listed as installed.
Works on Mac, not on iPhone. Check whether the server is stdio-based. If so, that's the expected iOS limitation, not a bug — it needs an HTTP-transport equivalent to work from the iOS app.
Frequently Asked Questions
Do I need Raycast Pro to use MCP servers? Yes. MCP support in Raycast is a Pro-exclusive feature as of this writing — there's no free-tier path to it.
What transports does Raycast support for MCP servers? Standard I/O (a local process Raycast launches and pipes JSON-RPC over stdin/stdout) and HTTP (a remote endpoint with optional OAuth). SSE isn't listed as a separate supported option in Raycast's own documentation.
Where does Raycast store MCP server configuration? In mcp-config.json, inside the Raycast AI extension's support directory — a single file covering all non-development MCP servers you've installed, distinct from a project-scoped config file.
Can I use the same MCP server in both Raycast and Cursor? Yes, but you configure it twice. Raycast and Cursor each read their own config file and manage their own OAuth grant or local process for that server — there's no shared MCP registry between different clients on the same machine.
Does MCP work in the Raycast iOS app? Yes, added in 2026, but only for HTTP-transport servers. Local stdio servers can't run inside the iOS sandbox, so they're macOS-only.
How do I choose which MCP tool Raycast uses for a request? Use the @server-name mention to scope a chat to one server explicitly. Without it, Raycast AI has access to every connected server's tools and picks based on relevance to your prompt.