# Session Relay MCP server

> Enables teams to share coding-agent sessions, decisions, and conversation history across different AI clients like Claude Code and Cursor.

- Repository: https://github.com/Ryrahul/session-relay
- Page: https://hostedmcp.org/servers/ryrahul/session-relay
- Transport: stdio
- Stars: 8
- License: AGPL-3.0
- Latest version: 0.7.0

## Install

### Claude Code

```sh
claude mcp add --env 'RELAY_TOKEN=<YOUR_RELAY_TOKEN>' session-relay -- npx -y session-relay
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "session-relay": {
      "command": "npx",
      "args": [
        "-y",
        "session-relay"
      ],
      "env": {
        "RELAY_TOKEN": "<YOUR_RELAY_TOKEN>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "session-relay": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "session-relay"
      ],
      "env": {
        "RELAY_TOKEN": "<YOUR_RELAY_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"session-relay","type":"stdio","command":"npx","args":["-y","session-relay"],"env":{"RELAY_TOKEN":"<YOUR_RELAY_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "session-relay": {
      "command": "npx",
      "args": [
        "-y",
        "session-relay"
      ],
      "env": {
        "RELAY_TOKEN": "<YOUR_RELAY_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add session-relay --env 'RELAY_TOKEN=<YOUR_RELAY_TOKEN>' -- npx -y session-relay
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.session-relay]
command = "npx"
args = ["-y", "session-relay"]

[mcp_servers.session-relay.env]
RELAY_TOKEN = "<YOUR_RELAY_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'RELAY_TOKEN=<YOUR_RELAY_TOKEN>' session-relay npx -- -y session-relay
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "session-relay": {
      "command": "npx",
      "args": [
        "-y",
        "session-relay"
      ],
      "env": {
        "RELAY_TOKEN": "<YOUR_RELAY_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `RELAY_TOKEN` | no | yes | Personal access token (srk_...) from Settings → Tokens. Optional if you ran relay login. |
| `RELAY_SERVER` | no | no | URL of your team's Session Relay server. Optional if you ran relay login. |

## Tools (15)

- `list_sessions`: List sessions teammates have shared. Defaults to the current repo; pass all_repos to see everything. for_me lists handoffs assigned to you (from any repo). (read-only)
- `search_sessions`: Full-text search over shared sessions (titles, summaries, messages). The query can include "file:<path>" and "branch:<name>" filters. (read-only)
- `get_session`: Load a shared session as a handoff: summary, decisions, next steps, files and conversation. mode "tail" (default) = summary + recent messages; "summary" = summary only; "full" = full transcript, paged with offset. (read-only)
- `share_current_session`: Share the session you are in right now with the team. Write the summary yourself from the conversation: it is what teammates read first. Never include secrets.
- `get_session_diff`: The uncommitted changes a teammate attached to a shared session, as a unified diff. Use it to see exact code state; to apply it, write it to a file and run `git apply`. (read-only)
- `share_template`: The handoff template for the current repo: extra sections (some required) and instructions to follow when sharing. Call it before share_current_session. (read-only)
- `team_activity`: What the team did recently: new shares by repo, handoffs for you, who picked up what, and new comments. (read-only)
- `comment_on_session`: Leave a short note on a shared session for the team: a question, a finding, or that you picked it up. Never include secrets.
- `update_session`: Change a share you made (or any share, if you're an admin): title, summary fields, who it's for, the PR link or visibility. Summary lists you pass replace the old ones; use add_next to append next steps.
- `start_live`: Start working live in this repo: teammates see what you're working on and which files you touch, and their messages reach you between steps. Lists who else is live here.
- `live_status`: Who is working live right now: repo, branch, what they're doing, files they touched recently, and whether this session is live. (read-only)
- `send_live_message`: Send a short message to a teammate who is working live: it reaches their agent between steps. Use it to tell them about a change that affects them, ask a question, or answer theirs. Never include secrets.
- `check_live_inbox`: Take new messages from teammates sent to this live session (they are marked as read).
- `update_live`: Change what teammates see about this live session (title, current status), or whether this agent may act on their messages without asking.
- `stop_live`: End this session's live session: teammates stop seeing it and messages stop arriving.

## FAQ

### How do I share a session with a teammate?

You can use the `/share` command in your agent to share a session, and your teammate can use `/pickup` in their agent to continue the work.

### Can I work on the same session at the same time as a teammate?

Yes, the `/live` command allows you to see who is working on what and message their session.

### Is my private data safe when sharing sessions?

Nothing is uploaded unless you explicitly share it, and sensitive information like API keys and passwords are removed locally before upload.

### How can I see exactly what data will be sent before sharing?

You can use the `--dry-run` flag with the share command to preview the content.
