Using Claude Code with Noukai

Full walkthrough of AI-assisted flow building — from natural language to working integration.

Claude Code (and other AI assistants) can build Noukai flows from natural language descriptions, then integrate the API call into your codebase.

Two Approaches

The fastest way to get started. No server configuration needed.

Download the Prompt File

Download noukai-prompt.md and add it to your project:

curl -o CLAUDE.md https://docs.noukai.xyz/noukai-prompt.md
# Or append to existing CLAUDE.md
curl https://docs.noukai.xyz/noukai-prompt.md >> CLAUDE.md

Describe What You Want

Tell Claude Code what pipeline you need:

"I want a pipeline that takes customer support tickets, classifies the intent, and generates a draft response based on the intent category"

Claude will guide you through:

Creating the flow in the web UI
Setting up blocks and prompts
Integrating the API call into your code
Configuring environment variables

What Happens Under the Hood

When you ask Claude to build a flow via MCP, here's the exact sequence of tool calls:

You: "Create a pipeline that translates text and extracts vocabulary"

Claude calls: hydrate_project("project-id")
  → Sees: existing flows, current state

Claude calls: create_flow(project_id, "Translation Pipeline", "translation-pipeline")
  → Created flow: flow-abc123

Claude calls: add_block(
    flow_id="flow-abc123",
    name="Translate",
    processor_type="llm",
    prompt="Translate the following text to {target_language}:\n\n{message}"
  )
  → Created block: step-1

Claude calls: add_block(
    flow_id="flow-abc123",
    name="Extract Vocabulary",
    processor_type="llm",
    target_id="step-1",
    direction="right",
    prompt="Extract key vocabulary from the translation. For each word, provide the reading and English meaning.\n\nTranslation: {previous_output}"
  )
  → Created block: step-2

Claude calls: update_block_output_schema(
    flow_id="flow-abc123",
    step_id="step-2",
    content={
      "type": "object",
      "properties": {
        "words": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "word": {"type": "string"},
              "reading": {"type": "string"},
              "meaning": {"type": "string"}
            }
          }
        }
      }
    }
  )
  → Schema set

Claude calls: publish_version(flow_id="flow-abc123", note="v1: translate + vocabulary extraction")
  → Version: ver-xyz789

Claude calls: set_production_version(flow_id="flow-abc123", version_id="ver-xyz789")
  → Production set. Flow live at /seq/{org}/{project}/translation-pipeline/execute

Integration Code

After building the flow, Claude inserts the API call into your project:

export async function translateAndExtract(
  text: string,
  targetLanguage: string
) {
  const response = await fetch(
    `${process.env.NOUKAI_API_URL}/api/v1/seq/your-org/your-project/translation-pipeline/execute`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.NOUKAI_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message: text,
        parameters: { target_language: targetLanguage },
      }),
    }
  );
 
  if (!response.ok) {
    throw new Error(`Noukai API error: ${response.status}`);
  }
 
  return response.json();
}

Example Prompts

You Say	Claude Does
"Create a sentiment analysis pipeline"	Creates flow with one LLM block, prompt for sentiment classification
"Add error handling to my support flow"	Reads existing flow, adds a validation block
"Make my flow return JSON with specific fields"	Sets output schema on the final block
"Update the prompt in my translator to be more formal"	Calls `update_block_draft` with revised text
"Deploy the latest version"	Calls `publish_version` then `set_production_version`
"Add a loop that processes each item separately"	Wraps target blocks in a loop over the array field

Troubleshooting

Issue	Solution
Claude doesn't know about Noukai	Add `noukai-prompt.md` to context or verify `.mcp.json`
"401 Unauthorized" on tool calls	API key expired or revoked — create a new one
"Flow not found" when calling slug	Flow isn't published yet, or slug has a typo
"Connection refused"	Check that `NOUKAI_API_URL` is correct
Claude creates blocks in wrong order	Use `get_flow_structure` to check, then `move_block` to fix