> ## 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.

# MCP Server

> Give Claude direct access to your code cache via Model Context Protocol

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`.

<Note>
  Source: [rayxc-org/raysurfer-code-caching-mcp](https://github.com/rayxc-org/raysurfer-code-caching-mcp)
</Note>

## Setup

Get your API key from the [dashboard](https://www.raysurfer.com/dashboard/api-keys).

### Claude Code

```bash theme={null}
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:

```bash theme={null}
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`

```json theme={null}
{
  "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):

```json theme={null}
{
  "mcpServers": {
    "raysurfer": {
      "command": "npx",
      "args": ["-y", "raysurfer-code-caching-mcp"],
      "env": {
        "RAYSURFER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

### 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         |