Claude and Codex through MCP

Two directions for agents

9Miho supports two agent relationships. They use the same catalog, assets, validation, Run, and approval contracts, but they begin on opposite sides.

Direction	Where the turn begins	What is configured
Agent inside 9Miho	The Agent panel, Storyteller, or an Assistant node	Choose a backend and model in Agent backends and models. 9Miho launches the CLI.
9Miho inside an external agent	Claude Code, Codex, Cursor, or another MCP host	The host launches the bundled 9Miho MCP entry point and talks to the already running local server.

The second path is useful when the wider task already lives in Claude or Codex. The agent can bring research, files, code, and planning into the same production records instead of reducing the handoff to copied prompts.

What the public 9miho skills add

The public KumihoIO/9miho-skills repository is an MIT-licensed trigger pack for Claude Code, Codex, Cursor, and other hosts that load Markdown skills. It is not the proprietary 9Miho application and does not contain its production engine.

Each installed trigger tells the agent when to ask 9Miho for guidance. The complete guidance is returned at task time by get_skill(task, detail) from the connected installation. That keeps the instructions aligned with that server’s current node catalog, provider set, and spend rules instead of freezing a stale copy in the agent.

Examples include image and video generation, Library search, reusable subjects, product photography, storyboard work, Storyteller planning, and Storyteller production. Do not infer availability from this list alone: list_skills() from the running installation is the source of truth.

Current release boundary: the signed Desktop runtime exposes the MCP stdio entry point, but a clean Desktop installation does not yet seed the version-matched guidance library automatically. The public repository installs the host-side triggers; it does not provision that server library. Its setup helper currently targets a 9Miho source checkout and is not the supported setup path for a released Desktop binary. An MCP connection can therefore work while list_skills() is empty or older than the public trigger pack.

What MCP can do

Through the same MCP surface, a connected agent can:

• discover the live node catalog and inspect the exact Variant and port contract;
• search Library assets, pin a Revision, and inspect its lineage;
• read and propose Storyteller structure and production work;
• fetch, author, validate, and place a Flow into an open Canvas;
• estimate a billable graph before it runs;
• start a validated Run, follow its status, and read the resulting pinned Krefs.

An agent should call get_flow before replacing an existing Flow. put_flow writes the document the creator will see, so it is an editing operation rather than a scratchpad.

Before connecting

1. Install and start 9Miho through Kumiho Desktop.
2. Confirm http://127.0.0.1:9999/api/healthz returns {"status":"ok"}.
3. Keep Kumiho CE or the selected Kumiho connection available; assets and skill guidance are stored there.
4. Install and sign in to Claude Code or Codex under the account that will use the MCP connection.

Keep port 9999 on loopback. The local 9Miho HTTP API is designed for a single-user self-hosted installation and must not be exposed directly to a LAN or the public internet.

Install the public triggers

For Codex and other compatible skill hosts:

npx skills add KumihoIO/9miho-skills

For Claude Code:

/plugin marketplace add KumihoIO/9miho-skills
/plugin install miho@miho

The triggers and the MCP connection are separate. Installing the repository does not connect a server by itself.

Connect the signed Desktop runtime

The 9Miho binary installed by Kumiho Desktop already contains the MCP stdio entry point. Released installations should use that binary, not a private source-checkout command.

The installed binary is normally here:

Platform	MCP command
Windows	%USERPROFILE%\.kumiho\apps\9miho\bin\9miho.exe --mcp-stdio
macOS	/Users/YOU/.kumiho/apps/9miho/bin/9miho --mcp-stdio
Linux	/home/YOU/.kumiho/apps/9miho/bin/9miho --mcp-stdio

Codex

Add an MCP server to ~/.codex/config.toml. Use the absolute path for your account; TOML does not expand ~ reliably inside a command value.

[mcp_servers.miho]
command = "C:\\Users\\YOU\\.kumiho\\apps\\9miho\\bin\\9miho.exe"
args = ["--mcp-stdio"]

[mcp_servers.miho.env]
MIHO_SERVER_URL = "http://127.0.0.1:9999"

On macOS or Linux, replace command with the absolute path shown in the platform table.

Claude Code

Windows PowerShell:

claude mcp add -e MIHO_SERVER_URL=http://127.0.0.1:9999 miho -- "$HOME\.kumiho\apps\9miho\bin\9miho.exe" --mcp-stdio

macOS or Linux:

claude mcp add -e MIHO_SERVER_URL=http://127.0.0.1:9999 miho -- "$HOME/.kumiho/apps/9miho/bin/9miho" --mcp-stdio

Restart the host after changing its MCP configuration.

Verify the connection

Ask the agent to call these in order:

1. list_skills() — confirms that MCP can reach this installation’s guidance library.
2. get_skill(task="video") — should return guidance sections, not names alone.
3. list_catalog(category="video") — confirms that the agent sees the catalog from the currently running server.

If the MCP tool is missing, the host has not reloaded its configuration. If list_skills() returns an empty or older pack, MCP is connected but that installation’s guidance library has not been provisioned at the matching version. Follow the server’s returned hint or the release notes; do not substitute commands that require access to the private 9Miho source repository.

Approval and credential boundaries

• Provider API keys stay in 9Miho Settings → Providers. Do not place them in a Skill file or MCP configuration.
• An external agent can estimate cost and propose a paid Run. On the normal released path, the Run waits at the itemized confirmation in 9Miho Canvas.
• confirm_spend=true is only the agent acknowledging that it showed the estimate. It is not payment authorization.
• Storyteller proposals remain Drafts until the separate approve_story_canon mutation is called. Its MCP tool contract tells the agent to obtain direct user instruction first, but the current server does not enforce a second human-confirmation gate. Treat this as an agent-conduct boundary, not as a permission or security boundary.
• A connected agent can upload a local media file the user points it to and can replace a Flow through put_flow. Review the file path and read the existing Flow before allowing either operation.

An external agent can operate a broad production surface. Keep host approvals and filesystem controls enabled, give direct instructions before Canon approval, and use 9Miho’s itemized gate for billable execution.