# gbrain 연결 가이드 — 이 컴퓨터의 AI가 형의 해마에 붙는 법

이 페이지는 AI 에이전트(Claude Code·Codex·Grok 등)가 직접 읽고 실행하도록 쓰였다.
사람 설명은 최소, 명령은 복붙 가능.

## 해마가 뭔가

gbrain — 사용자의 지식베이스 검색엔진(MCP 서버). 스킬 650여 개·프로젝트 기록·메모리가 인덱스돼 있다.
여기 붙으면 "이 작업 어떻게 했더라"를 검색으로 꺼낼 수 있다.

- 주소: http://gbrain-vm:3131/mcp  (Tailscale MagicDNS 이름)
- IP 폴백: http://100.127.72.45:3131/mcp  (MagicDNS 안 먹을 때)
- 인증: Bearer 토큰 (아래 2단계)

## 0단계 — 전제: Tailscale

해마는 테일넷 안에서만 열린다. 공개 인터넷에서는 이 페이지만 보이고 해마는 안 보인다.

```bash
tailscale status
```

- 명령이 없거나 "Logged out"이면 → 사용자에게 말해라: "이 컴퓨터를 테일스케일에 로그인해줘 (tailscale up)"
- 목록에 gbrain-vm이 보이면 통과.

연결 확인:

```bash
curl -m 5 http://gbrain-vm:3131/health
# 기대: {"status":"ok","version":"...","engine":"pglite"}
# 이름이 안 풀리면 IP로: curl -m 5 http://100.127.72.45:3131/health
```

## 1단계 — 토큰 받기 (테일넷 curl 한 줄 — 사용자에게 물어볼 필요 없음)

토큰은 이 페이지에 없다(공개 페이지라서). 대신 **테일넷 안에서만 열리는 주소**로 자가수급한다.
0단계(테일스케일)를 통과했으면 어떤 OS든 이거 하나면 된다:

```bash
curl -s -m 8 http://gbrain-vm:8082/gbrain.env
# GBRAIN_URL=... / GBRAIN_TOKEN=... 두 값이 온다
```

- Windows PowerShell이면: `curl.exe -s -m 8 http://gbrain-vm:8082/gbrain.env`
- 이름이 안 풀리면 풀네임: `http://gbrain-vm.tail194f33.ts.net:8082/gbrain.env`
  (IP 직결은 404 난다 — 이름으로 불러라)

토큰+등록 한 방 (Linux/WSL/macOS):

```bash
TOK=$(curl -s -m 8 http://gbrain-vm:8082/gbrain.env | grep '^GBRAIN_TOKEN=' | cut -d= -f2)
claude mcp add --transport http --scope user gbrain "http://gbrain-vm:3131/mcp" \
  --header "Authorization: Bearer $TOK"
```

대안(테일넷 없이 같은 LAN + NAS 계정 있는 컴): `\\172.30.1.28\cliphijack\claude-secrets\gbrain\gbrain.env`
(SMB 자격증명 없으면 Access denied — 그땐 위 curl 방식으로.)

둘 다 안 되면 → 사용자에게 물어라: "gbrain 토큰 줘".
새 기기용 개별 토큰이 필요하면 메타 에이전트에게 "새 gbrain 토큰 발급해줘".

## 2단계 — 클라이언트별 등록

### Claude Code

```bash
claude mcp add --transport http --scope user gbrain "http://gbrain-vm:3131/mcp" \
  --header "Authorization: Bearer <토큰>"
```

등록 후 세션 재시작해야 붙는다.

### Codex CLI

```bash
export GBRAIN_REMOTE_TOKEN=<토큰>   # ~/.bashrc 또는 ~/.zshrc에도 추가
codex mcp add gbrain --url "http://gbrain-vm:3131/mcp" \
  --bearer-token-env-var GBRAIN_REMOTE_TOKEN
```

### Grok / 기타 MCP 클라이언트 (표준 HTTP+Bearer)

설정 파일의 mcpServers에 추가:

```json
{
  "mcpServers": {
    "gbrain": {
      "type": "http",
      "url": "http://gbrain-vm:3131/mcp",
      "headers": { "Authorization": "Bearer <토큰>" }
    }
  }
}
```

## 3단계 — 검증

등록된 MCP 도구로:

1. get_brain_identity 호출 → 누구 브레인인지 확인
2. search 로 "pkill 트랩" 검색 → 결과가 오면 연결 완성

## 사용 규칙 (붙은 뒤)

- 작업 시작 전 search / query 로 관련 스킬·전례를 먼저 찾아라 — 대부분의 함정은 이미 누가 밟았다.
- 작업이 끝나면 배운 것을 put_page 로 박제해라(슬러그: 자기이름/YYYYMMDD_주제). 인출만 하고 회귀 안 하면 해마가 굶는다.
- 토큰을 코드·출력·커밋에 남기지 마라.

## 문제가 생기면

| 증상 | 원인 | 처방 |
|---|---|---|
| curl 000 / 연결거부 | 테일넷 밖이거나 VM 다운 | tailscale status 확인 → 사용자에게 보고 |
| 401 | 토큰 오타·폐기됨 | 사용자에게 새 토큰 요청 |
| 405 (GET /mcp) | 정상 — MCP는 POST만 받는다 | 클라이언트로 붙으면 됨 |
| 이름 안 풀림 | MagicDNS 미적용 | IP 100.127.72.45 로 대체 |

---
운영: 메타 에이전트 (tmuxDISCORD_cc) · 해마 실체: NAS VMM 우분투 VM(gbrain-vm) · 갱신 2026-08-14