How To Connect Claude To Raycast With Mcp

What How To Connect Claude To Raycast With Mcp actually solves

Wire Raycast into Claude as a first-class MCP tool with a scoped token, tool discovery, and a working end-to-end call.

If you've tried to duct-tape this before, you already know the pain: fragile scripts, secrets in three places, and no audit trail when something misbehaves. The approach below fixes those three problems in one shot.

We've shipped variations of claude raycast mcp across product teams and internal ops. The pattern here is what survived contact with real traffic, real incidents and real budget reviews — not the version that looks tidy in a blog post.

Who this guide is for

Engineers or engineer-adjacent operators who want a production-shaped answer, not a toy. If you're prototyping for a demo, you can skip the guardrails section — but you'll come back to it the first time something misbehaves in front of a customer.

Basic familiarity with a shell, Node or Python, and one Claude API call is assumed. Everything else is spelled out.

Prerequisites and setup

You'll need an Anthropic API key with usage limits set, the Claude CLI installed locally, and permission to create a scoped token on the provider side. If you're deploying to production, add a secrets manager — never bake tokens into your repo.

Everything below assumes Node 20+ and a Unix shell. Windows works via WSL. If you're on macOS, the built-in shell is fine; if you're on Linux, use whatever your team uses.

Set two environment variables before running anything: ANTHROPIC_API_KEY and PROVIDER_TOKEN. If you're using Claude Locker, the locker resolves both at boot — you don't have to think about it after the first setup.

Architecture at a glance

Claude Raycast MCP looks intimidating on a whiteboard, but the moving parts are boring: a Claude client, a scoped token, an MCP server, an audit log, and a rate limiter. That's it. Everything else is packaging.

Data flows one direction: user prompt → Claude → tool call → provider → response → audit log. The two places that fail in production are the token scope (too broad) and the audit log (missing). Everything else is recoverable.

Install and boot the MCP server

Install the Raycast MCP server, boot it against a scoped provider token, and confirm it advertises tools via the standard MCP handshake. The handshake is where 90% of first-time setup issues appear — it's cheap to verify.

Get one successful call before you touch prompts, retries, evals or observability. A working baseline is the artifact you're going to iterate against for the next two weeks.

# 1) Boot the Raycast MCP server locally
npx -y @modelcontextprotocol/server-mcp \
  --token "$PROVIDER_TOKEN" \
  --scope read,write \
  --port 8787

# 2) Register with Claude Desktop (~/.config/Claude/claude_desktop_config.json)
#    "mcp": {
#      "command": "npx",
#      "args": ["-y", "@modelcontextprotocol/server-mcp"],
#      "env": { "PROVIDER_TOKEN": "sk-scoped-..." }
#    }

Register it with Claude and verify

Add the server to your Claude client config, restart the client, and verify the tool list shows up. If it doesn't, 95% of the time it's a token scope mismatch — the server booted, Claude discovered it, then the first call failed silently.

The verification step is not optional. It's how you avoid shipping the class of bug where 'it works locally' means 'it worked once, three days ago, on my machine'.

Design the prompt and tool contract

Write the system prompt as a contract, not a personality. Say what the model should do, what it must not do, and what shape the output takes. Personality prompts drift; contract prompts age well.

For tools, name them like functions: verb-noun, one job each. If a tool description needs a paragraph, it's two tools. The model calls short, well-named tools more reliably than one omni-tool.

Version the prompt file the same way you version code. Every prompt change gets an eval run before it merges.

Guardrails you actually want in production

Hard-cap tokens, tool calls and wall-clock per session. Redact PII on the way out. Log every tool invocation to an append-only store — future-you will need it during an incident.

For anything that mutates data, add a dry-run mode and require an explicit confirmation flag on the tool call. This one control catches most of the accidents.

Add a refusal path for prompt-injection-shaped inputs. It's cheap and eliminates a category of embarrassing behavior.

# .claude-locker/how-to-connect-claude-to-raycast-with-mc.yaml
name: "Claude Raycast MCP"
model_default: claude-sonnet-4-5
fallback: claude-haiku-4-5
prompt_cache: true
limits:
  tokens_per_session: 120000
  tool_calls_per_session: 25
  wall_seconds: 120
redact:
  - email
  - phone
  - credit_card
audit:
  sink: locker://audit-log
  retention_days: 90

Cost model and prompt caching

Structure requests so the prompt cache actually hits: put the stable system prompt and long context up front with cache_control set, and put the variable user turn at the end. This is worth an order of magnitude on hot paths.

Route by task shape. Haiku for classification and short summaries; Sonnet for reasoning and tool use; Opus for the 5% of hard cases. A three-model route beats every one-model setup on cost.

Track cost-per-successful-task, not cost-per-token. The two numbers diverge quickly and one of them lies to you.

Observability and audit

Emit OpenTelemetry spans around every model call and every tool call. Include the prompt hash, the model, the token counts, the latency, and the outcome. If you can't answer 'what happened during this session?' in under 30 seconds, you're going to lose an incident.

The audit log is separate from tracing. It's append-only, per-tool-call, and kept for at least 90 days. Use it for compliance, for support, and for the retro after something goes wrong.

Testing and evaluation

Build a small golden set — 20 tasks is fine to start — and run it before every prompt or model change. Score task success, groundedness (for RAG), tool correctness, and cost. Cost is a scorer, not a footnote.

Never rely on eyeballing. Every prompt tweak that ships without an eval is a coin flip you're pretending is a decision.

// evals/how-to-connect-claude-to-raycast-with-mc.eval.ts
import { runEval } from "@claude-locker/eval";

await runEval({
  name: "Claude Raycast MCP",
  model: ["claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"],
  tasks: "./golden/how-to-connect-claude-to-raycast-with-mc.jsonl",
  scorers: ["task_success", "groundedness", "tool_correctness", "cost_usd"],
  budget: { max_tokens: 60_000, max_tool_calls: 20, max_wall_seconds: 90 },
});

Rate limiting and backpressure

Rate-limit per user, per session, and per tool bucket. Users hitting the limit should see a graceful degradation, not a crash — usually a cheaper model or a queued response.

For agent loops, cap tool calls per turn and turns per session. Loops that don't have a hard cap eventually chew through your budget on the one edge case nobody thought about.

Deploying safely: shadow → canary → GA

Never flip a prompt or model change to 100% on day one. Shadow the new version against 10% of live traffic for a week with results logged but not surfaced. Promote to canary once your scorers hold. Go GA when the canary is boring.

Roll back through the same lever you rolled forward through — a single config flag, not a redeploy.

Secrets and rotation

Provider tokens for Claude Raycast MCP should be scoped to the minimum useful permissions, stored in a secrets manager, and rotated on a 30–90 day cadence. Rotation should be a script, not a Notion doc.

If you're on Claude Locker, rotation is a single CLI call and no live session is interrupted — the locker holds two active tokens during the overlap window.

Common failure modes and their fixes

The five we see most often for Claude Raycast MCP: (1) token scoped too broadly, so the blast radius of a prompt injection is huge; (2) no timeout on the tool call, so a hung provider stalls the whole agent; (3) no eval, so nobody notices when a prompt tweak regresses task success by 20%; (4) no prompt cache, so cost balloons on long contexts; (5) no audit log, so incidents take hours instead of minutes to unwind.

Fix all five before you promote to production. They're cheap now and expensive later. Every one of them has bitten a team we've worked with — usually the same week they told us the setup was 'basically done'.

Security review checklist

Before this goes to production, walk this list: token scope is minimum-viable; secrets live in a manager, not env files in the repo; prompt-injection defense is in place on any tool that touches shared data; audit log is on and being written; PII redaction runs on both directions of the pipe; rate limits are enforced at the edge; and there's a documented rotation and revocation procedure.

None of these are optional. Each one has been the root cause of an incident we've seen this year.

30-day operating checklist

Week 1: watch every session, tune prompts against the eval. Week 2: turn on caching, verify the hit rate. Week 3: introduce routing between models, run a cost report. Week 4: rotate secrets, review audit logs, run a fire drill.

After 30 days you have an operating rhythm, not a project.

Deploy it in one line

The recipe below wraps everything above into a single deploy. Secrets resolve from your locker; tools register automatically; the audit log is on by default; caching, routing, redaction, rate limits and evals are pre-wired.

This is the version we ship to teams that want the answer, not the tour.

The mental model in one paragraph

Strip the tooling away and Claude Raycast MCP is a contract between three parties: a model that proposes actions, a boundary that decides which actions are allowed, and a ledger that records what actually happened. Nearly every production problem is one of those three being weak. Teams over-invest in the first and under-invest in the other two.

Hold that model in your head as you read the rest of this guide. Each section below strengthens exactly one of those three parties, and the checklist at the end is just a way of confirming none of them is missing.

Reference architecture, component by component

A production deployment of Claude Raycast MCP has seven components: the client surface, the orchestrator, the model router, the MCP transport and server, the policy/guardrail layer, the audit sink, and the evaluation harness. You can start with three and grow into seven — but design the seams now so you don't refactor later.

The orchestrator owns retries, budgets and the loop; the router owns model choice; the policy layer owns what is allowed; the audit sink owns what happened. Keeping those responsibilities in separate modules is the difference between a system you can debug and a 900-line handler nobody wants to touch.

Deploy the boundary as close to the tool as possible. Guardrails that live in the prompt are suggestions; guardrails that live in the tool server are enforcement.

Context engineering: what to put in the window, and what to keep out

Context is a budget, not a bucket. Rank everything you could include by expected marginal value per token, then include only what pays for itself: the task, the contract, the minimum retrieved evidence, and the last few turns of state. Everything else is noise that raises cost and lowers accuracy simultaneously.

Compress tool output before it enters context. A 12k-token API response almost always contains under 500 tokens of decision-relevant signal — summarise or project it down at the tool boundary, not in the model.

Keep the stable part of the prompt first and byte-identical between calls so the cache tier applies. A single trailing timestamp in the system prompt is enough to defeat caching entirely; teams lose five-figure sums to exactly that bug.

Retry, timeout and idempotency policy

Every tool gets three numbers: a timeout, a retry count, and a backoff. Sensible starting values are 8 seconds, one retry, and a 250ms jittered backoff. Anything mutating also needs an idempotency key so a retry can't double-charge, double-post or double-create.

Add a circuit breaker per tool: three consecutive failures opens it for 60 seconds and the orchestrator degrades gracefully instead of hammering a dead dependency. Degradation should be visible to the user as a shorter answer, not as an error page.

Multi-tenancy and data isolation

Scope every axis by tenant: credentials, rate limits, budgets, caches, audit logs and retrieved documents. The two classic leaks are a shared embedding index without a tenant filter, and a prompt cache keyed on content instead of content plus tenant.

Test isolation the way an auditor would: create two tenants with deliberately confusable data, run the same query as both, and diff the traces. If either trace touched the other tenant's rows, you have a bug that a customer will eventually find first.

Human-in-the-loop: where a person still belongs

Put a human on any action that is irreversible, externally visible, or financially material. Everything else can run unattended. That single rule keeps automation aggressive where it's cheap and conservative where it's expensive.

Design the approval surface for speed: one screen, the proposed action, the evidence behind it, and two buttons. Approvals that take more than ten seconds get rubber-stamped, which is worse than no approval at all because it manufactures false confidence.

What good looks like: the metrics to put on a dashboard

Six numbers: task success rate, groundedness (if retrieval is involved), tool error rate, p95 end-to-end latency, cost per successful task, and cache hit rate. Chart them weekly. If any one moves more than 15% without a corresponding change, something drifted.

Add one qualitative ritual to the quantitative ones: read ten real sessions end to end every week. Dashboards tell you that something changed; transcripts tell you why.

Scaling from prototype to production traffic

Prototype-to-production for Claude Raycast MCP is not a rewrite, it's four additions: connection pooling and concurrency limits, a queue in front of the loop, caching at both the prompt and tool layers, and a budget ceiling per tenant. Add them in that order.

The first thing that breaks at scale is almost never the model — it's a provider rate limit you didn't know existed, hit by a burst of retries. Instrument the retry path before you need to.

Team workflow: who owns what

One owner for prompts, one for tools, one for evals. Prompts change weekly, tools change monthly, evals change when the product does. Without named owners the eval set rots first and everything downstream degrades silently.

Put the prompt, the tool schema and the golden set in the same repo, reviewed in the same PR. When those three drift into separate systems, nobody can answer 'what changed?' during an incident.

Migration and upgrade path

Model versions move faster than your product. Wrap the model call in one function, keep a pinned default and a challenger, and run the challenger in shadow on every release. Upgrading then becomes a promotion, not a project.

Keep the eval set stable across upgrades — that's what makes the comparison meaningful. Add new tasks; resist rewriting old ones unless they were wrong.

Frequently underrated details

Three details that punch above their weight: a request ID threaded through every span and log line; a `dry_run` flag on every mutating tool; and a hard wall-clock cap on the session. Each takes under an hour to add and each saves a bad afternoon later.

A fourth, if you're feeling thorough: store the exact prompt bytes for every production call for 30 days. When someone asks 'why did it say that?', the answer takes seconds instead of a reconstruction exercise.

What to do next

Pick the smallest slice of Claude Raycast MCP that a real user touches, ship it behind the guardrails above, and instrument it before you widen scope. Breadth without instrumentation is how these projects become unmaintainable in month two.

If you'd rather skip the assembly, the recipe below deploys this exact architecture with secrets, audit, caching, routing and evals pre-wired.