Ikiro Developer Docs

The MCP dev kit is for developers who want full control over their superpower definitions. Write YAML, validate locally, deploy, and test — all from your terminal via Claude Code.

Prerequisites

Claude Code installed
An Ikiro developer API key (get one at ikiro.ai/dashboard/developer/keys)

Setup

Add the superpower-dev MCP server to your Claude Code configuration:

.mcp.json

{
  "mcpServers": {
    "superpower-dev": {
      "command": "python3",
      "args": ["/path/to/ikiro-backend/superpower_dev_mcp.py"],
      "env": {
        "IKIRO_API_KEY": "ik_dev_YOUR_KEY_HERE",
        "IKIRO_BACKEND_URL": "https://api-dev.ikiro.ai",
        "SUPERPOWERS_DIR": "~/superpowers"
      }
    }
  }
}

The dev loop

1. Scaffold

Tell Claude Code what you want:

Build me a superpower that checks crypto prices when I ask about bitcoin or ethereum

Claude Code uses scaffold_superpower to create ~/superpowers/crypto-checker/definition.yaml.

2. Edit

The YAML definition is your superpower. Edit it directly or let Claude Code modify it.

3. Validate

Validate the crypto-checker superpower

The validate_superpower tool checks the definition against the schema and reports errors.

4. Dry-run

Dry-run crypto-checker with message "how's bitcoin doing?"

The dry_run_superpower tool simulates execution locally — shows which action matches, which operations would run, and what the response template would produce.

5. Deploy

Deploy crypto-checker to sandbox

The deploy_to_sandbox tool:

Validates the definition
Pushes it to the dev backend
Smart redeploy: if a superpower with the same name exists, updates it in-place
Auto-equips to Luna's loadout so it's immediately testable

6. Test

Send a test message: "what's the bitcoin price?"

The send_test_message tool sends the message through the full orchestrator pipeline and returns Luna's actual response.

7. Iterate

Edit the YAML, redeploy, test again. Each deploy updates the existing superpower — no duplicates.

Available tools

Tool	What it does
`scaffold_superpower`	Create a new superpower directory
`validate_superpower`	Check definition against schema
`dry_run_superpower`	Simulate execution locally
`deploy_to_sandbox`	Deploy/redeploy to dev (smart update + auto-equip)
`send_test_message`	Send message, get persona's actual response
`get_logs`	Fetch execution history and usage
`watch_superpower`	Configure hot reload for file watchers
`list_integrations`	Browse all operation types
`list_examples`	See working superpower examples
`get_superpower_spec`	Full specification reference

Example definition

definition.yaml

version: '1.0'
metadata:
  name: Crypto Checker
  description: Check cryptocurrency prices
  category: finance
  tags: [crypto, bitcoin, ethereum, price]

trigger_patterns:
  keywords: [bitcoin, ethereum, crypto, btc, eth]
  phrases: [crypto price, how's bitcoin]

actions:
  - id: check_price
    name: Check Crypto Price
    triggers:
      keywords: [bitcoin, ethereum, crypto, btc, eth, price]
    operations:
      - type: llm_extract
        output: coin
        input: "{{$input.text}}"
        output_schema:
          type: object
          properties:
            id:
              type: string
              description: "CoinGecko ID: bitcoin, ethereum, solana, etc."

      - type: http_request
        output: price_data
        method: GET
        url: "https://api.coingecko.com/api/v3/simple/price?ids={{$vars.coin.id}}&vs_currencies=usd&include_24hr_change=true"

      - type: llm_generate
        output: summary
        prompt: |
          Crypto price data: {{$vars.price_data}}
          User asked: {{$input.text}}
          Give a brief, friendly price update. Include the current price and 24h change percentage.

    response:
      template: "{{$vars.summary}}"

Quickstart — MCP Dev Kit