AI Connection Setup

Beta Connect Claude Code, Codex CLI, or Gemini CLI to your BongoWaifu desktop companion.

Before You Start

1. Launch BongoWaifu from Steam and make sure Steam is logged in.
2. Open the Settings panel → find the AI Connection (Beta) section at the bottom of the Settings tab.
3. Flip the toggle ON. The status line will turn green and show a URL like http://127.0.0.1:7337/mcp.
4. Write down the port number you see (the four-digit number after 127.0.0.1:).

Quick setup — let the AI configure itself

Don’t want to edit config files by hand? Paste the prompt below into Claude Code / Codex CLI / Gemini CLI — the AI will pick the right file, write the JSON, and tell you when to restart. Remember to replace 7337 with the port shown in the game.

Prompt to paste

I'm running BongoWaifu, a desktop companion app that exposes an MCP (Model Context Protocol) server at http://127.0.0.1:7337/mcp on my local machine. Please add this server to your MCP configuration so you can talk to the companion.

Server details:
- Identifier: bongowaifu
- Local URL: http://127.0.0.1:7337/mcp
  (replace 7337 with the port the game actually shows — it tries 7337 first, then 7338–7356 if busy)

Choose the right transport for yourself:
- If you natively support streamable HTTP MCP (e.g. Claude Code): add a server entry with "url" set to the URL above and "transport" = "http".
- If you only support stdio MCP (e.g. Codex CLI, Gemini CLI, most other clients): wrap it with the mcp-remote bridge. Use "command": "npx" and "args": ["mcp-remote", "http://127.0.0.1:7337/mcp"]. This needs Node.js 18+.

Write the entry to whichever MCP config file you use — common locations are ~/.claude/mcp.json, ~/.codex/mcp.json, ~/.gemini/config.json, a project-local .mcp.json, or a built-in settings UI. After writing the file, tell me to fully restart you (close and reopen the client) so the new MCP server loads.

Once connected you should see 3 tools: say, ask_and_wait, get_game_state. List them back to confirm the connection worked.

Let the companion join the chat (Claude Code)

Claude Code HTTP direct

Claude Code speaks HTTP MCP natively, so this is the simplest setup — no extra bridge, no Node.js required.

Config file location

File content

{
  "mcpServers": {
    "bongowaifu": {
      "url": "http://127.0.0.1:7337/mcp",
      "transport": "http"
    }
  }
}

Codex CLI via mcp-remote

Codex CLI only speaks stdio MCP, so it needs the mcp-remote bridge to forward to our HTTP server. Requires Node.js 18+.

1. Install the bridge (optional)

npx will fetch it on first run, but installing globally is faster and works offline:

npm install -g mcp-remote

2. Config file location

3. File content

{
  "mcpServers": {
    "bongowaifu": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:7337/mcp"]
    }
  }
}

Gemini CLI & other stdio clients via mcp-remote

Any MCP client that only supports stdio transport uses the same pattern as Codex CLI — point the client at mcp-remote with our URL. Only the config file location differs per client.

{
  "mcpServers": {
    "bongowaifu": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:7337/mcp"]
    }
  }
}

Check your client’s own docs for the exact config path. Common locations include ~/.gemini/config.json, ~/.config/<client>/mcp.json, or a built-in settings UI.

Available Tools

Once connected, your AI client can call these 3 tools. You don’t invoke them directly — just ask the AI in natural language and it will pick the right one.

get_game_state response shape

Passing only the sections you need keeps the response small. Example responses (JSON, shortened):

{
  "character": {
    "character_id": "waifu",
    "character_name": "Waifu",
    "character_type": "waifu",
    "current_skin": "new",
    "current_clothes": ["ShortHair_Pink", "Polo_Purple", "CrewSocks_Yellow"]
  }
}

With sections: ["character", "achievements"]:

{
  "character": { "..." },
  "achievements": [
    {
      "api_name": "ACHIEVEMENT_1",
      "display_name": "ACHIEVEMENT_1",
      "description": "",
      "unlocked": true,
      "unlock_time_utc": "2026-02-11T11:03:26.0000000Z"
    }
  ]
}

Slash Commands

BongoWaifu ships with 6 MCP prompts. In Claude Code, Codex CLI, or any other MCP client that renders prompts as slash commands, typing / surfaces them under the mcp__bongowaifu__ namespace. They’re the quickest way for the player to manually nudge the companion.

The mcp__bongowaifu__ prefix is the Claude Code convention. Other clients may expose the prompts under a different prefix — check the client’s slash-command panel for the exact form.

Companion Persona System

When your AI client connects, the MCP server hands it a style playbook that tells it how to voice the companion. Persona is built from two signals: the character type (Cat vs Waifu) and keywords in the character name + current outfit. You don’t configure anything — just pick characters and outfits, and the voice follows.

Base character type

Style keywords

The AI does a case-insensitive substring match against character_name and current_skin. Multi-language aliases are supported (English / 中文 / 日本語 / 한국어) so names in any language still trigger the right flavor.

Real examples

Same question, different characters, different answers:

Always current — refresh before every line

The MCP instructions tell the AI to call get_game_state (default sections: ["character"]) immediately before every say or ask_and_wait. You can switch characters or change outfits at any moment without warning the AI, and the companion’s voice will pick up the change on her very next line. This adds one extra tool call per spoken line, so her voice always matches what she’s currently wearing.

Demo: a typical conversation

Here is what it looks like to use the say tool through Claude Code. Your exact wording doesn’t matter — just describe what you want.

🖼️

Screenshot or short GIF of the companion showing a speech bubble triggered by Claude Code

TODO-demo.png • recommended: 900x500

FAQ & Troubleshooting

Tap a question to expand.

Privacy & Security

Links