Skip to main content
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.
Source: rayxc-org/raysurfer-code-caching-mcp

​
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
Add --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: 
claude mcp list
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.

​
Tools

The server exposes 4 tools that Claude can call directly: Search for cached code matching a task description.
ParameterTypeRequiredDefaultDescription
taskstringYes—Natural language task description
top_knumberNo5Maximum results (1-100)
min_scorenumberNo0.3Minimum verdict score (0-1)
public_snipsbooleanNofalseInclude community public snippets in results

​
raysurfer_upload

Upload code from a successful execution.
ParameterTypeRequiredDefaultDescription
taskstringYes—What the code accomplishes
fileobjectYes—File with path and content keys
succeededbooleanNotrueWhether the execution succeeded

​
raysurfer_vote

Vote on cached code usefulness.
ParameterTypeRequiredDefaultDescription
code_block_idstringYes—ID of the code block
upbooleanNotrueUpvote (true) or downvote (false)
taskstringNo—Original task for context

​
raysurfer_patterns

Get proven task-to-code mappings.
ParameterTypeRequiredDefaultDescription
taskstringNo—Filter patterns by task
top_knumberNo10Maximum results

​
Resources

URIDescription
raysurfer://helpHelp text about tools and recommended workflow
raysurfer://statusConnection status and API reachability