Building AI Companions with an Agent, and a Human in the Loop
Hanakoi’s MCP server lets Claude draft characters, generate their art and write their stories. Here is the workflow, and why every image and chapter waits for a person to approve it.
What a Hanakoi character is
A Hanakoi companion is more than a system prompt. Each one has a personality, a backstory and a voice, remembers what you talked about, and can generate photos of themselves in any scene you describe. Relationships grow through five stages (acquaintance, friend, flirty, lover and honeymoon) and each stage has its own avatar. Authored story chapters, with scene headers, story beats and unlock conditions, add plot on top of open conversation.
That is a lot of content per character, which is why we opened the whole authoring pipeline to agents.
42 tools over MCP
The Hanakoi MCP server exposes 42 tools. The main groups:
- Characters: create, update, read and list profiles.
- Media: generate images, video and audio, create music, upload reference files and track generation tasks.
- Stories: create and update chapters, check a character's script and simulate a playthrough before publishing.
- World: events, posts, NPCs and locations around a character.
The workflow
- The agent asks which language the character should be written in, drafts a complete profile with at least one opening suggestion, and creates the character without an image.
- It reads the character back and shows you the profile to review.
- It generates candidate portraits and waits. Nothing is attached until you pick one.
- The approved portrait is uploaded and becomes the display image, the acquaintance-stage avatar and the source image.
- From that source, image-to-image generation produces the friend, flirty, lover and honeymoon avatars, each shown for approval.
- Only when you ask for a story does the agent propose an outline and create chapters.
Why a person stays in the loop
Agents draft quickly; taste is still a human call. A wrong portrait attached to a character carries into every relationship stage generated from it, and a story chapter is often the first thing users see. So the rule is simple: the agent does not attach images or create stories until you confirm.
Connecting
The MCP endpoint lives on the API domain, https://api.hanakoi.ai/api/v1/mcp (the site domain returns 404). Authenticate with an OAuth 2.1 access token or an API key starting with hk_. It works with Claude Code, Claude Desktop and, as a custom connector, Claude.ai:
claude mcp add --transport http hanakoi https://api.hanakoi.ai/api/v1/mcp