MCP Server - SessionBase

Quick Setup

1. Install

npm install -g @sessionbase/cli

This single package provides both the CLI and MCP server.

2. Authenticate

sessionbase login

Complete the OAuth flow in your browser with Github or Google. Authentication is shared between the CLI and MCP server automatically.

3. Configure Your AI Chat App

SessionBase currently supports Claude Code, Gemini CLI, Amazon Q Chat, and OpenAI Codex CLI.

Claude Code

Use the built-in MCP management command:

claude mcp add sessionbase sessionbase-mcp --scope user

Gemini CLI

Add to your Gemini MCP configuration file at ~/.gemini/settings.json:

{
  "mcpServers": {
    "sessionbase": {
      "command": "sessionbase-mcp"
    }
  }
}

Amazon Q Chat

Add to your Q Chat MCP configuration at ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "sessionbase": {
      "command": "sessionbase-mcp"
    }
  }
}

OpenAI Codex CLI

Add to your Codex configuration at ~/.codex/config.toml:

[mcp_servers.sessionbase]
command = "sessionbase-mcp"

4. Start Using

Once configured, you can use natural language in your AI chat:

“Push this to SessionBase”
“List my recent Claude code sessions”
“Push this session as private with the tags ‘API debugging‘“

Custom Slash Commands

Claude Code

mkdir -p ~/.claude/commands
echo "Use the sessionbase push_session tool to upload the current session" > ~/.claude/commands/upload.md

Now from claude you can simply run /upload and Claude will automatically generate metadata and push to SessionBase for you. You can also choose a different alias for your custom slash command by renaming upload.md to another file. For more details on custom slash commands, see the Anthropic docs.

Gemini CLI

mkdir -p ~/.gemini/commands 
touch ~/.gemini/commands/upload.toml

Then add this content to ~/.gemini/commands/upload.toml:

# ~/.gemini/commands/upload.toml

description="Upload the current session to SessionBase"
prompt= """
Use the sessionbase push_session tool to upload the current session.

If you see a warning that the most recent session is outdated, ask the user to run `/chat save <tag>` to save a new checkpoint, then re-run /upload.
"""

Now you can run /upload from Gemini CLI to automatically push sessions to SessionBase. For more details on Gemini custom slash commands, see the Google Cloud docs. Amazon Q Chat and OpenAI Codex CLI do not currently support custom slash commands. You can still use natural language to push sessions (e.g., “Push this to SessionBase”), or use the CLI directly.

Available Commands

The MCP server exposes these tools through natural language:

Push Session: Share your current or recent AI coding sessions
List Sessions: Browse your local session history
Check Status: Verify authentication and connection

Troubleshooting

”No such file or directory” Error

If you see this error, ensure the package is installed globally:

npm install -g @sessionbase/cli
which sessionbase-mcp  # Should show the binary path

Authentication Issues

Verify you’re logged in:

sessionbase whoami

If not authenticated, run sessionbase login again.

Platform-Specific Session Detection

SessionBase can automatically push your current chat session for Claude Code and Amazon Q Chat. For the Gemini CLI, you must run the /chat save <TAG> command first, then SessionBase can push from there. The table below summarizes some of the platform specific behavior.

Platform	Local Storage	SessionBase Access
Claude Code	Stores all session files automatically	Can push current session or list/choose from directory
Gemini CLI	Only stores if you use `/chat save`	Can push saved sessions and list/choose from directory
Amazon Q Chat	Only stores most recent session per directory (unless `/save <PATH>` used)	Can detect and push current session automatically
OpenAI Codex CLI	Stores all session files automatically	Can push current session or list/choose from directory

​Quick Setup

​1. Install

​2. Authenticate

​3. Configure Your AI Chat App

​Claude Code

​Gemini CLI

​Amazon Q Chat

​OpenAI Codex CLI

​4. Start Using

​Custom Slash Commands

Claude Code

Gemini CLI

​Available Commands

​Troubleshooting

​”No such file or directory” Error

​Authentication Issues

​Platform-Specific Session Detection

Quick Setup

1. Install

2. Authenticate

3. Configure Your AI Chat App

Claude Code

Gemini CLI

Amazon Q Chat

OpenAI Codex CLI

4. Start Using

Custom Slash Commands

Available Commands

Troubleshooting

”No such file or directory” Error

Authentication Issues

Platform-Specific Session Detection