# Energy Claude MCP

Use an existing Claude subscription inside Energy without changing Energy itself.

Energy's GPT agent sees one MCP tool, `ask_claude`. The tool invokes the official authenticated Claude Code CLI and keeps one Claude session per Energy thread, including across bridge restarts.

```text
Energy GPT -> localhost MCP -> Claude Code CLI -> Claude subscription
```

## Requirements

- Node.js 20 or newer
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/getting-started) installed and signed in
- An Energy version that can connect to a custom HTTP MCP server

Check Claude before starting:

```sh
claude --version
claude auth status
```

## Run

```sh
git clone https://github.com/noahljungberg/energy-claude-mcp.git
cd energy-claude-mcp
npm ci
npm run build
npm start
```

The bridge listens at `http://127.0.0.1:4379/mcp`.

In Energy:

1. Open the profile menu and choose **Connect Tools**.
2. Open **MCP**, choose **Add MCP server**, and paste `http://127.0.0.1:4379/mcp`.
3. Connect it and start a new task.

Keep the bridge process running while using it.

## Options

```sh
npm start -- \
  --claude /path/to/claude \
  --data-dir ~/.energy-claude-mcp \
  --port 4379
```

The defaults are `claude`, `~/.energy-claude-mcp`, and port `4379`. Claude Code uses its configured default model.

## Boundaries

- The server binds only to `127.0.0.1` and uses the MCP SDK's localhost host validation.
- It invokes Claude Code in safe mode with Claude-side tools disabled.
- It never reads or copies Claude OAuth credentials.
- Energy-thread mappings are stored in `~/.energy-claude-mcp/sessions.json` with owner-only permissions.
- GPT remains Energy's outer coordinator. The tool description tells it to delegate and return Claude's answer verbatim, but this is not a direct model-provider replacement: GPT can still decide how to use the tool, consumes its own allowance, and may rewrite the result.

## Verify

```sh
npm test
npm run typecheck
npm run build
```

The tests exercise the MCP protocol, first-turn and resumed Claude calls, restart persistence, concurrent thread mappings, and error boundaries with a fake Claude executable. They do not consume Claude allowance.

## License

MIT