Documentation Index
Fetch the complete documentation index at: https://docs.raysurfer.com/llms.txt
Use this file to discover all available pages before exploring further.
The Raysurfer MCP server exposes code caching as native tools inside Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, and any MCP-compatible client.
No install required — runs via npx.
Setup
Get your API key from the dashboard.
Claude Code
claude mcp add raysurfer -e RAYSURFER_API_KEY=YOUR_API_KEY -- npx -y raysurfer-code-caching-mcp
--scope user to make it available across all projects:
claude mcp add raysurfer --scope user -e RAYSURFER_API_KEY=YOUR_API_KEY -- npx -y raysurfer-code-caching-mcp
Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"raysurfer": {
"command": "npx",
"args": ["-y", "raysurfer-code-caching-mcp"],
"env": {
"RAYSURFER_API_KEY": "YOUR_API_KEY"
}
}
}
}
Cursor
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):
{
"mcpServers": {
"raysurfer": {
"command": "npx",
"args": ["-y", "raysurfer-code-caching-mcp"],
"env": {
"RAYSURFER_API_KEY": "YOUR_API_KEY"
}
}
}
}
VS Code
Add to .vscode/mcp.json:
{
"inputs": [
{
"password": true,
"id": "raysurfer-api-key",
"type": "promptString",
"description": "Raysurfer API Key"
}
],
"servers": {
"raysurfer": {
"command": "npx",
"args": ["-y", "raysurfer-code-caching-mcp"],
"env": {
"RAYSURFER_API_KEY": "${input:raysurfer-api-key}"
}
}
}
}
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"raysurfer": {
"command": "npx",
"args": ["-y", "raysurfer-code-caching-mcp"],
"env": {
"RAYSURFER_API_KEY": "YOUR_API_KEY"
}
}
}
}
Project-Level (.mcp.json)
Add to your project root to share with your team:
{
"mcpServers": {
"raysurfer": {
"command": "npx",
"args": ["-y", "raysurfer-code-caching-mcp"],
"env": {
"RAYSURFER_API_KEY": "${RAYSURFER_API_KEY}"
}
}
}
}
Verify Installation
For Claude Code, check the server is running:
You should see raysurfer listed. Then ask Claude:
Search the Raysurfer cache for code that generates a quarterly report.
Claude will call raysurfer_search and show you the results.
The server exposes 4 tools that Claude can call directly:
raysurfer_search
Search for cached code matching a task description.
| Parameter | Type | Required | Default | Description |
|---|
task | string | Yes | — | Natural language task description |
top_k | number | No | 5 | Maximum results (1-100) |
min_score | number | No | 0.3 | Minimum verdict score (0-1) |
public_snips | boolean | No | false | Include community public snippets in results |
raysurfer_upload
Upload code from a successful execution.
| Parameter | Type | Required | Default | Description |
|---|
task | string | Yes | — | What the code accomplishes |
file | object | Yes | — | File with path and content keys |
succeeded | boolean | No | true | Whether the execution succeeded |
raysurfer_vote
Vote on cached code usefulness.
| Parameter | Type | Required | Default | Description |
|---|
code_block_id | string | Yes | — | ID of the code block |
up | boolean | No | true | Upvote (true) or downvote (false) |
task | string | No | — | Original task for context |
raysurfer_patterns
Get proven task-to-code mappings.
| Parameter | Type | Required | Default | Description |
|---|
task | string | No | — | Filter patterns by task |
top_k | number | No | 10 | Maximum results |
Resources
| URI | Description |
|---|
raysurfer://help | Help text about tools and recommended workflow |
raysurfer://status | Connection status and API reachability |
