> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sessionbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> The SessionBase MCP server enables you to push and manage AI agent sessions directly from Claude Code, Gemini CLI, and Amazon Q Chat without breaking your workflow.

## Quick Setup

### 1. Install

```bash theme={null}
npm install -g @sessionbase/cli
```

This single package provides both the CLI and MCP server.

### 2. Authenticate

```bash theme={null}
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](https://www.anthropic.com/claude-code), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Amazon Q Chat](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html), and [OpenAI Codex CLI](https://developers.openai.com/codex/cli).

#### Claude Code

Use the built-in MCP management command:

```bash theme={null}
claude mcp add sessionbase sessionbase-mcp --scope user
```

#### Gemini CLI

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

```json theme={null}
{
  "mcpServers": {
    "sessionbase": {
      "command": "sessionbase-mcp"
    }
  }
}
```

#### Amazon Q Chat

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

```json theme={null}
{
  "mcpServers": {
    "sessionbase": {
      "command": "sessionbase-mcp"
    }
  }
}
```

#### OpenAI Codex CLI

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

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

```bash theme={null}
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](https://docs.anthropic.com/en/docs/claude-code/slash-commands#personal-commands).

##### Gemini CLI

```bash theme={null}
mkdir -p ~/.gemini/commands 
touch ~/.gemini/commands/upload.toml
```

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

```toml theme={null}
# ~/.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](https://cloud.google.com/blog/topics/developers-practitioners/gemini-cli-custom-slash-commands).

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:

```bash theme={null}
npm install -g @sessionbase/cli
which sessionbase-mcp  # Should show the binary path
```

### Authentication Issues

Verify you're logged in:

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