---
title: AI Agent Setup
description: Install flutter-mcp-toolkit skills and MCP wiring for Claude Code, Cursor, Codex, Cline, and the open skills ecosystem.
---

# AI Agent Setup

`flutter-mcp-toolkit` ships **16** agent skills (task guides, chain wiring, runtime golden path, maintenance lanes, migration, and boundary audit). Canonical source: [`plugin/skills/`](https://github.com/Arenukvern/mcp_flutter/tree/main/plugin/skills) (also exposed at repo root as [`skills/`](https://github.com/Arenukvern/mcp_flutter/tree/main/skills) for [`npx skills`](https://www.npmjs.com/package/skills) discovery).

| Skill | Purpose |
|---|---|
| `flutter-mcp-toolkit-guide` | Entry point — routes to the right task skill |
| `flutter-mcp-toolkit-setup` | Install verification + preflight |
| `flutter-mcp-toolkit-inspect` | Read app state |
| `flutter-mcp-toolkit-control` | Drive UI |
| `flutter-mcp-toolkit-debug` | Diagnose problems |
| `flutter-mcp-toolkit-custom-tools` | Register dynamic MCP tools in the Flutter app |
| `flutter-mcp-boundary-audit` | Audit CLI/MCP/schema/dynamic-registry boundary drift |
| `flutter-mcp` | Golden-path runtime loop (snapshot → act → hot-reload) |
| `flutter-mcp-cli-runtime-validation` | CLI `validate-runtime` smoke test |
| `flutter-mcp-toolkit-intentcall-migration` | Legacy call-entry to `AgentCallEntry` migration |
| `flutter-mcp-toolkit-maintain-web` | Web/WebMCP showcase maintenance |
| `flutter-mcp-toolkit-maintain-macos` | macOS native showcase maintenance |
| `flutter-mcp-e2e-harness` | Repeatable E2E scenarios as Dart (`flutter_mcp_harness`, showcase launcher) |
| `flutter-mcp-automation-chain` | Cross-tier automation chain — MCP/CLI/harness/oka picker, first loops, runner-session contract |
| `flutter-mcp-toolkit-dogfood-iterations` | Dogfood iteration scoring and evidence routing |
| `flutter-mcp-toolkit-repo-maintainer` | Release, version, and skill-bundle maintenance |

## Three layers (read this first)

1. **Host MCP** — `flutter-mcp-toolkit-server` with 30 `fmt_*` tools.
2. **In-app toolkit** — `mcp_toolkit` in your Flutter app (debug only).
3. **Dynamic registry** — register custom tools/resources at runtime (`AgentCallEntry`, `addEntries` / `addMcpTool`). Agents discover via `fmt_list_client_tools_and_resources` and invoke via `fmt_client_tool` / `fmt_client_resource`. Use skill **`flutter-mcp-toolkit-custom-tools`** and [Dynamic tool registry](/core/dynamic_tools_registry).

Skills alone do **not** replace the MCP server or in-app toolkit.

## Install methods (pick one)

Skills teach the agent **how** to use the toolkit. You still need the **MCP server binary** and **`mcp_toolkit` in your Flutter app** — see [Get started](../../README.md) steps 1–2 and 4.

| Method | Skills | MCP server config | Best for |
|---|---|---|---|
| **`flutter-mcp-toolkit init`** | Yes | Yes (plugin + `mcp.json`, `--dynamics`) | One command per agent; recommended default |
| **`npx skills add`** | Yes | No — configure MCP separately | Open ecosystem ([skills.sh](https://skills.sh)), any supported agent |
| **Claude git marketplace** | Yes (plugin) | Yes | `/plugin marketplace add Arenukvern/mcp_flutter` |
| **Codex git marketplace** | Yes (plugin) | Yes | `codex plugin marketplace add Arenukvern/mcp_flutter` |
| **Cursor local plugin** | Yes | Yes | `init cursor` |
| **Manual `mcpServers` JSON** | No | Yes only | Advanced / legacy — prefer `init` first |

Full matrix: [Marketplace distribution](/ai_agents/marketplace_distribution). Store submission: [runbook](/contributing/marketplace_submission_runbook).

`init all` installs for **claude-code, cursor, codex, and cline** only. For the cross-agent `.agents/skills/` layout, use `init agents-skills` or `npx skills`.

## Install for your agent (`flutter-mcp-toolkit init`)

```bash
flutter-mcp-toolkit init claude-code   # or: cursor | codex | cline | agents-skills | all
```

This writes skills + plugin manifest + MCP server registration to the agent's expected path. The `init` command auto-detects MCP vs CLI mode; override with `--mode mcp|cli|auto`.

```bash
flutter-mcp-toolkit init cursor --scope user   # user-global Cursor plugin
flutter-mcp-toolkit init agents-skills -y      # .agents/skills/ (Cursor, Cline, Codex, Copilot, …)
```

### Per-target output paths

| Target | Skills location | Also writes |
|---|---|---|
| `claude-code` | `.claude/skills/flutter-mcp-toolkit/<id>/SKILL.md` | — |
| `cursor` | `.cursor/plugins/local/flutter-mcp-toolkit/skills/<id>/` | `mcp.json`, plugin manifest |
| `codex` | `.codex/plugins/cache/local/flutter-mcp-toolkit/local/skills/<id>/` | marketplace + `mcp.json` |
| `cline` | `.clinerules/<id>.md` | — |
| `agents-skills` | `.agents/skills/<id>/SKILL.md` | — |

## Install via `npx skills` (open agent skills ecosystem)

The [`skills`](https://www.npmjs.com/package/skills) CLI (Vercel [vercel-labs/skills](https://github.com/vercel-labs/skills)) installs `SKILL.md` bundles from this GitHub repo into your agent's skills directory. It does **not** register the MCP server — run `flutter-mcp-toolkit init <agent>` afterward if you need `mcp.json`, or add `mcpServers` manually ([`mcp_server_dart/README`](https://github.com/Arenukvern/mcp_flutter/blob/main/mcp_server_dart/README.md)).

```bash
# Preview all skills in this repo
npx skills add Arenukvern/mcp_flutter --list

# Install the entry + setup skills for Cursor (project scope)
npx skills add Arenukvern/mcp_flutter \
  --skill flutter-mcp-toolkit-guide \
  --skill flutter-mcp-toolkit-setup \
  -a cursor -y

# Install all skills for Claude Code (global)
npx skills add Arenukvern/mcp_flutter -g -a claude-code -y

# Cross-agent layout (.agents/skills/) — same tree as `init agents-skills`
npx skills add Arenukvern/mcp_flutter -a cursor -a cline -y
```

Discover more community skills at **[skills.sh](https://skills.sh)**. Pin the CLI in CI with `npx skills@latest` if needed.

## Using the chain vs building a harness

To **use** this toolkit's automation chain in your own app — tier picker
(MCP / CLI / harness / oka), first loops, and the runner-session contract —
install `flutter-mcp-automation-chain` and read [The Automation
Chain](/start_here/automation_chain).

## Harness meta-skills (Agent Guild)

When **building or maintaining** product harnesses (CLI + MCP + docs), install meta-skills from [Agent Guild](https://github.com/arenukvern/agent_guild):

```bash
npx skills add arenukvern/agent_guild --skill harness-engineering-culture -a cursor -y
npx skills add arenukvern/agent_guild --skill north-star-governance -y
npx skills add arenukvern/agent_guild --skill faq-driven-docs -y
```

Guild teaches **how** to design agent-first harnesses (mechanical gates, docs map, CLI/MCP parity). **This repo** owns `flutter-mcp-toolkit` and `fmt_*` — not Guild’s `guild` CLI. See [OpenAI — Harness engineering](https://openai.com/index/harness-engineering/) and mcp_flutter [CLI vs MCP](/start_here/cli_vs_mcp).

### Team lockfile (reproducible installs)

After the first `npx skills add`, the CLI writes `.skills.json` and `skills-lock.json`. Commit those in your app repo so everyone gets the same skill versions.

Example manifest (copy from [`.skills.json.example`](https://github.com/Arenukvern/mcp_flutter/blob/main/.skills.json.example) or generate via install):

```json
{
  "skills": [
    {
      "name": "flutter-mcp-toolkit-guide",
      "remote": "Arenukvern/mcp_flutter",
      "version": "latest"
    }
  ]
}
```

CI restore (experimental API — check [skills CLI README](https://www.npmjs.com/package/skills) for current command names):

```yaml
- name: Restore AI agent skills
  run: npx skills@latest experimental_install
```

## Claude Code marketplace

```bash
# Git catalog (works today)
/plugin marketplace add Arenukvern/mcp_flutter
/plugin install flutter-mcp-toolkit@Arenukvern-mcp_flutter

# Prerequisite check
bash plugin/install.sh   # after server binary is on PATH or FLUTTER_MCP_BIN is set
```

Marketplace entry: [`.claude-plugin/marketplace.json`](https://github.com/Arenukvern/mcp_flutter/blob/main/.claude-plugin/marketplace.json) → `./plugin`.

Official Anthropic catalog: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit) — see [submission runbook](/contributing/marketplace_submission_runbook).

## Cursor and Codex

```bash
flutter-mcp-toolkit init cursor
flutter-mcp-toolkit init codex
# or:
codex plugin marketplace add Arenukvern/mcp_flutter
```

See [Marketplace distribution](/ai_agents/marketplace_distribution) for Smithery, MseeP, and asset requirements.

## Browse the skills

Skills are plain Markdown — readable without an agent. Edit under `plugin/skills/<id>/SKILL.md`, then run `make sync-skills` before committing (regenerates the embedded bundle in `mcp_server_dart`).