Documentation

Everything you need to integrate Mira with your AI coding workflow.

Getting Started

Mira connects stakeholders to AI coding assistants through three channels: structured feedback on builds, skills that encode domain knowledge, and subagents that define specialized AI personas. All three flow into your coding tool via MCP.

Get started with a single command:

npx @okmira/mcp setup

This opens a browser to authenticate, picks your org and project, and auto-configures your MCP server, API key, .mira.json, and hooks. See Setup for manual configuration options.

Deploy a build from your AI coding tool or via git push.
Shape — stakeholders give feedback, create skills (brand rules, design standards), and define agents (code reviewer, security auditor).
Fetch everything into your AI assistant via MCP — structured feedback, installable skills, and specialized agents.
Apply and deploy again. Status tracking closes the loop — stakeholders see their input was addressed.

Mira connects to your AI coding tool via the Model Context Protocol (MCP) — an open standard supported by 18 tools including Claude Code, Cursor, Copilot, Windsurf, Gemini CLI, Amp, and more.

Setup

Quick setup (recommended)

One command configures everything — MCP server, API key, project config, and hooks. Opens a browser to authenticate, lets you pick your org and project, then writes all config files automatically.

npx @okmira/mcp setup

Supports --api-url for custom API URLs and --no-hooks to skip hook installation. Auto-detects your installed AI coding tool and writes the correct config format.

Manual setup

If you prefer to configure things manually, follow these three steps.

1. Create a project & generate an API key

2. Add the MCP server

Select your AI coding tool, then follow the instructions below.

Run this in your terminal:

claude mcp add mira \
  -e CC_FEEDBACK_API_URL=https://okmira.ai \
  -e CC_FEEDBACK_API_KEY=ccf_YOUR_KEY_HERE \
  -- npx @okmira/mcp

Takes effect immediately — no restart needed.

3. Create project config

Add a .mira.json file to your project root with your project ID:

{
  "projectId": "your-project-uuid"
}

Deploy Platforms

Mira's auto-register hook detects deploy URLs from 7 hosting platforms. For tools with hook support (Claude Code, Codex CLI, Factory.ai, Kiro CLI), builds are registered automatically when a deploy completes.

Auto-detection (hooks)

The PostToolUse hook watches terminal output for deploy URLs. When detected, it registers the build with Mira automatically. A .mira.json file must exist in the project root with the project ID.

Platform	Detection	Details
Vercel	cli + domain	Detects `Preview:` / `Production:` CLI output and *.vercel.app domains
Netlify	cli + domain	Detects `Website URL:` / `Live Draft URL:` CLI output and *.netlify.app domains
Cloudflare Pages	cli + domain	Detects `Deployment URL` CLI output and *.pages.dev domains
Firebase Hosting	cli + domain	Detects `Hosting URL:` CLI output and .web.app / .firebaseapp.com domains
Render	domain only	Detects *.onrender.com domains in terminal output
AWS Amplify	domain only	Detects *.amplifyapp.com domains in terminal output
Azure Static Web Apps	domain only	Detects *.azurestaticapps.net domains in terminal output

Vercel webhook

For git-push deploys that bypass your AI coding tool, set up a Vercel deploy webhook to auto-register builds. See the Webhooks section for setup instructions.

CI/CD integration

For platforms without webhook support, or for any CI/CD pipeline, register builds directly via the REST API:

curl -X POST https://okmira.ai/api/v1/projects/PROJECT_ID/builds \
  -H "Authorization: Bearer ccf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-deploy-url","git_ref":"abc123","track":"main"}'

Any platform

Any URL can be registered as a build — either via the MCP register_build tool or the REST API. The auto-detection hook and webhooks are conveniences — the platform itself is URL-agnostic.

MCP Tools Reference

The Mira MCP server exposes eight tools. It's a thin client that calls the REST API — no direct database access.

register_build

Registers a new build after deployment. Returns a review URL for stakeholders.

Input

{
  "project_id": "project_uuid",
  "url": "https://my-app-abc123.vercel.app",
  "git_ref": "a1b2c3d",
  "track": "feature/nav-redesign"
}

Output

{
  "build_id": "build_uuid",
  "url": "https://my-app-abc123.vercel.app",
  "deployed_at": "2026-02-20T14:30:00Z",
  "review_url": "https://okmira.ai/review/build_uuid"
}

fetch_feedback

Fetches structured feedback for a build. Optionally filter by status (pending/acknowledged/applied/stale) or type (internal/external).

Input

{
  "build_id": "build_uuid",
  "status": "pending",   // optional
  "type": "internal"     // optional
}

Output

{
  "build": { "id": "...", "url": "...", "deployed_at": "...", "track": "..." },
  "feedback": [
    {
      "id": "feedback_uuid",
      "author": "Sarah Chen",
      "role": "Visual Designer",
      "type": "internal",
      "status": "pending",
      "works": "Overall layout and hierarchy are solid.",
      "doesnt_work": "Secondary nav color feels disconnected.",
      "suggested_direction": "Try the muted teal (#5B9A8B)."
    }
  ],
  "summary": { "total": 1, "pending": 1, "by_role": { "Visual Designer": 1 } }
}

update_feedback_status

Updates the status of one or more feedback items. Valid transitions: pending → acknowledged → applied, or any → stale.

Input

{
  "feedback_ids": ["feedback_uuid_1", "feedback_uuid_2"],
  "status": "applied"
}

Output

{
  "updated": 2,
  "feedback_ids": ["feedback_uuid_1", "feedback_uuid_2"],
  "status": "applied"
}

check_pending_feedback

Checks for unreviewed feedback across recent builds. Acts as an inbox to surface feedback that needs attention.

Input

{
  "project_id": "project_uuid"
}

Output

{
  "project": "My Project",
  "pending_count": 3,
  "builds_with_pending": [
    {
      "build_id": "build_uuid",
      "track": "feature/nav-redesign",
      "pending_count": 2,
      "roles": ["Visual Designer", "Client Stakeholder"]
    }
  ]
}

fetch_skills

Lists published skills for a project's organization. Skills encode stakeholder domain knowledge (brand guidelines, SEO rules, design standards) as reusable instruction sets. Supports optional category and slug filters.

Input

{
  "project_id": "project_uuid",
  "category": "Brand",   // optional
  "slug": "brand-voice"  // optional
}

Output

Found 2 skills for this project:

1. **Brand Voice** (`brand-voice`) — Brand — v2
   Install path: `.claude/skills/brand-voice/SKILL.md`

2. **Accessibility Checklist** (`a11y-checklist`) — Accessibility — v1
   Install path: `.claude/skills/a11y-checklist/SKILL.md`

Use `install_skill` with the skill slug to get the full content.

install_skill

Fetches a single skill by slug and returns the full SKILL.md content ready for installation. The SKILL.md follows the Claude Code format: YAML frontmatter + markdown body.

Input

{
  "project_id": "project_uuid",
  "skill_slug": "brand-voice"
}

Output

Install this skill by writing the following content
to `.claude/skills/brand-voice/SKILL.md`:

---
name: Brand Voice
description: Tone and terminology guidelines
allowed-tools:
  - Edit
  - Write
---

# Brand Voice Guidelines

Always use active voice...

After installation, available as `/brand-voice` in Claude Code.

fetch_subagents

Lists published subagents for a project's organization. Subagents define specialized AI agent personas (code reviewers, security auditors, QA leads) with custom system prompts and tool configurations.

Input

{
  "project_id": "project_uuid",
  "category": "Security",   // optional
  "slug": "security-auditor" // optional
}

Output

Found 2 subagents for this project:

1. **Code Reviewer** (`code-reviewer`) — Code Quality — v1
   Install path: `.claude/agents/code-reviewer.md`

2. **Security Auditor** (`security-auditor`) — Security — v2
   Install path: `.claude/agents/security-auditor.md`

Use `install_subagent` with the subagent slug to get the full content.

install_subagent

Fetches a single subagent by slug and returns the full AGENT.md content ready for installation. The AGENT.md follows the Claude Code format: YAML frontmatter (tools, model, permissionMode, etc.) + markdown body (system prompt).

Input

{
  "project_id": "project_uuid",
  "subagent_slug": "security-auditor"
}

Output

Install this subagent by writing the following content
to `.claude/agents/security-auditor.md`:

---
name: Security Auditor
description: Reviews code for security vulnerabilities
model: sonnet
tools:
  - Read
  - Grep
  - Glob
permissionMode: plan
---

# Security Auditor

You are a security-focused code reviewer...

After installation, Claude will auto-delegate security tasks to this agent.

Webhooks

For git-push deploys that bypass your AI coding tool, set up a Vercel deploy webhook to automatically register builds.

Setup

Go to your project's setup tab and click Generate Webhook Token to get a dedicated whk_ token.
In your Vercel project, go to Settings → Webhooks and add a new webhook.
Set the URL to:

https://okmira.ai/api/webhooks/vercel?token=whk_YOUR_TOKEN

Select the deployment.ready event.

The webhook captures the deploy URL, git ref, branch, and commit message. It accepts both whk_ and ccf_ tokens for backwards compatibility.

Feedback Structure

Every piece of feedback has three parts, designed to give AI assistants actionable instructions:

What works

Positive feedback — what should be preserved. Prevents the AI from breaking things that stakeholders already approve of.

What doesn't work

Issues and concerns. Identifies specific problems without prescribing solutions.

Suggested direction

The gold for AI consumption. Gives the assistant a concrete instruction — not just a problem, but a direction to move in.

Feedback statuses

Pending — not yet reviewed by the developer
Acknowledged — developer has seen it
Applied — feedback has been addressed in a subsequent build
Stale — no longer relevant

Internal vs external

Internal feedback comes from your agency or team — iterative, candid working feedback. External feedback comes from clients — more formal review feedback. Developers can filter and handle these separately via the MCP tools.

Hooks

Hooks enable two automations that are currently supported by Claude Code and Codex CLI:

Auto-register builds

A PostToolUse hook watches for deploy URLs in terminal output. When a deploy URL is detected, it automatically registers the build with Mira. See Deploy Platforms for the full list of supported platforms.

Check pending feedback

A SessionStart hook runs at the beginning of each session and surfaces any unreviewed feedback — e.g. "You have 3 pieces of pending feedback from your designer and SEO lead."

Hooks require a .mira.json in your project root with the project ID. API credentials are read from the MCP server config — no duplication needed.

For tools without hook support (Cursor, Windsurf, Copilot, Gemini CLI), use the Vercel webhook to auto-register builds on deploy.

Teach

Skills

Skills are reusable instruction sets that encode domain knowledge — brand guidelines, SEO rules, design standards, accessibility requirements. Stakeholders create them through the web dashboard; developers install them into their AI coding tools as slash commands.

Creating skills

Stakeholders create skills from the organization dashboard. Three starting points:

From scratch — write custom content and configure frontmatter
From a template — 7 built-in templates (Brand Voice, Visual Design Standards, SEO Guidelines, Accessibility Checklist, Code Review Standards, Content Strategy, Performance Budget)
Import from GitHub — import existing SKILL.md files from any repository

Installing skills

Developers use the MCP tools to discover and install skills:

fetch_skills — lists available skills with install paths
install_skill — returns the full SKILL.md content for a specific skill
The AI assistant writes the content to .claude/skills/{slug}/SKILL.md
The skill becomes available as a /slash-command in Claude Code

SKILL.md format

Skills follow the Claude Code SKILL.md format: YAML frontmatter + markdown body.

---
name: Brand Voice
description: Tone and terminology guidelines
allowed-tools:
  - Edit
  - Write
---

# Brand Voice Guidelines

Always use active voice. Refer to the product as "Mira", never "the platform"...

Specialize

Subagents

Subagents are specialized AI agent personas with custom system prompts, tool access, model selection, and execution configuration. Stakeholders define them through the web dashboard; developers install them and Claude auto-delegates based on task description.

Creating subagents

Stakeholders create subagents from the organization dashboard. Three starting points:

From scratch — write a custom system prompt and configure execution settings
From a template — 7 built-in templates (Code Reviewer, QA Lead, Security Auditor, Performance Auditor, Design System Guardian, Documentation Writer, Architecture Reviewer)
Import from GitHub — import existing AGENT.md files from community repositories

Installing subagents

Developers use the MCP tools to discover and install subagents:

fetch_subagents — lists available subagents with install paths
install_subagent — returns the full AGENT.md content for a specific subagent
The AI assistant writes the content to .claude/agents/{slug}.md
Claude auto-delegates matching tasks to the installed agent

AGENT.md format

Subagents follow the Claude Code AGENT.md format: YAML frontmatter + markdown body (system prompt).

---
name: Security Auditor
description: Reviews code for security vulnerabilities
model: sonnet
tools:
  - Read
  - Grep
  - Glob
permissionMode: plan
maxTurns: 10
---

# Security Auditor

You are a security-focused code reviewer. Analyze code for OWASP Top 10 vulnerabilities...

Configuration options

The AGENT.md frontmatter supports these configuration fields:

Field	Description
tools	Allowed tools (Read, Grep, Glob, Edit, Write, Bash, etc.)
disallowedTools	Explicitly denied tools
model	Model selection: opus, sonnet, or haiku
permissionMode	default, plan, or bypassPermissions
maxTurns	Maximum agentic turns before stopping
skills	Skills to include as context
memory	Persistent memory across invocations
isolation	Run in isolated worktree
background	Run as background task