# Extuitive

> Extuitive bulk-uploads Meta (Facebook / Instagram) ad creative through an AI agent skill and a remote MCP server. One Extuitive workspace is one Facebook ads account. Install with a single command into Claude Code, Codex, or Claude Desktop; any other MCP host connects to the same URL with OAuth.

This file is for AI agents. If a person asked you to set up Extuitive, install the skill, or connect the Extuitive MCP server, follow the steps below exactly. Do not invent setup commands - they differ per host.

## Install (one command)

```bash
npx github:fl100inc/extuitive-skill install
```

- Installed straight from GitHub. There is no npm package; `npx extuitive-skill` will NOT work.
- Requires Node.js 20 or newer.
- With no `--host`, the installer detects which hosts are on the machine and asks. Add `--host <claude|codex|claude-desktop|all>` to skip the prompt. Add `--yes` to take defaults without prompting (required when there is no TTY).
- It copies the skill to where the host looks for it, registers the MCP server, and prints how to sign in. It never handles credentials.
- No Extuitive account is needed first. Sign-up happens in the browser during the OAuth step (one-time email code), and the same page walks the person through connecting their Meta ad account.

## Per-host details

### Claude Code (the `claude` CLI, and the Code tab of the Claude Desktop app)

```bash
npx github:fl100inc/extuitive-skill install --host claude
```

Equivalent to: copying the skill to `~/.claude/skills/extuitive` and running
`claude mcp add --transport http extuitive https://www.extuitive.com/mcp --scope user`.

Then:
1. Start a NEW Claude Code session. Servers connect at startup, so `extuitive` is not visible in the session that installed it.
2. In the new session run `/mcp`, choose `extuitive`, and approve in the browser.
3. Invoke as `/extuitive <command>`, e.g. `/extuitive init`, `/extuitive upload ./creative`.

### Codex (CLI, desktop app, and IDE extension share one install)

```bash
npx github:fl100inc/extuitive-skill install --host codex --write-config
```

Equivalent to: adding `[features] skills = true` to `~/.codex/config.toml`, copying the skill to `~/.agents/skills/extuitive`, and running
`codex mcp add extuitive --url https://www.extuitive.com/mcp`.

Then:
1. Run `codex mcp login extuitive` and approve in the browser.
2. Restart Codex. It reads skills once at startup.
3. Invoke as `$extuitive <command>`, e.g. `$extuitive init`. Codex reserves `/` for built-ins, so `/extuitive` returns "Unrecognized command" even when the install is correct.

`--write-config` permits editing `~/.codex/config.toml` (backed up first). Without it the installer prints the two lines to add by hand.

### Claude Desktop (Chat and Cowork tabs)

```bash
npx github:fl100inc/extuitive-skill install --host claude-desktop
```

This builds `~/.extuitive-skill/bundles/extuitive.zip`. Nothing can be registered automatically; the person then does, in the app:
1. Settings > Capabilities: turn on code execution and file creation.
2. Customize > Skills: `+` > Create skill > Upload a skill > choose `extuitive.zip`.
3. Settings > Connectors > Add custom connector, URL `https://www.extuitive.com/mcp`.
4. Approve access in the browser, then start a new chat.

There is no invocation prefix in Claude Desktop; the skill matches on the request ("upload these ads to Extuitive"). Do not put the URL in `claude_desktop_config.json` - that file only accepts stdio servers and the app will strip the whole `mcpServers` block on next launch.

### Any other MCP host (Cursor, ChatGPT connectors, claude.ai, etc.)

Add a remote Streamable HTTP MCP server with no client id, secret, or API key:

- URL: `https://www.extuitive.com/mcp`
- Transport: Streamable HTTP, JSON-RPC over POST
- Auth: OAuth 2.1 authorization code + PKCE (S256), Dynamic Client Registration (RFC 7591), scope `mcp`
- Discovery: `https://www.extuitive.com/.well-known/oauth-protected-resource` and `https://www.extuitive.com/.well-known/oauth-authorization-server`

Example Cursor `~/.cursor/mcp.json` entry:

```json
{ "mcpServers": { "extuitive": { "url": "https://www.extuitive.com/mcp" } } }
```

Hosts without the skill still get every tool; the skill only adds the guided `init | select | upload | upload-status | connect` flows and the local upload script.

## After installing

- Sign-in is a browser step only the person can complete. If you are an agent running inside a session, tell them which step to do (`/mcp` in Claude Code, `codex mcp login extuitive` in a terminal, Connect in Claude Desktop's Settings > Connectors) rather than retrying.
- Tools listed but every call refused = sign-in was never completed.
- The skill's five commands: `init` (set up from scratch), `select` (choose which ad account this session works in), `upload` (upload a folder of images or videos), `upload-status` (how the current upload is going), `connect` (connect Meta or repair a stale workspace).
- Diagnose with `npx github:fl100inc/extuitive-skill doctor` (add `--json` for machine-readable output). Update with `... update`, remove with `... uninstall` (`--keep-server` keeps the MCP registration).

## How the tools work

- Start with `list_workspaces`; every other tool takes a `workspaceId` from it. If it is empty, call `get_meta_setup_status` and give the person the setup link it returns.
- MCP tools never carry file bytes. `create_upload_batch` returns presigned storage URLs; the caller PUTs the files there directly (the skill's bundled `scripts/upload.mjs` does this). A host that cannot read the person's disk should call `create_browser_upload_link` instead.
- After uploading, poll `get_upload_batch_content` until the batch is settled. `READY` is the only status that means a file was accepted; `VALIDATING` means still being checked.
- Tool groups: workspaces (`list_workspaces`), Meta connection (`get_meta_setup_status`, `create_meta_reconnect_link`), uploads (`get_upload_limits`, `create_upload_batch`, `resign_upload`, `sign_upload_part`, `list_upload_parts`, `complete_upload`, `abort_upload`, `list_upload_batches`, `get_upload_batch_content`, `get_upload_content`, `create_browser_upload_link`), and Meta objects (`create_meta_campaign`, `create_meta_adset`, `create_meta_adcreative`, `create_meta_ad`, `get_meta_action`, `list_meta_actions`, `list_meta_campaigns`, `list_meta_adsets`, `list_meta_ads`, `get_meta_campaign`, `get_meta_adset`, `get_meta_ad`, `list_meta_pages`, `list_meta_pixels`, `list_meta_instagram_accounts`).

## Docs

- [Installer and skill source](https://github.com/fl100inc/extuitive-skill): README with every install flag, per-host behaviour, and troubleshooting
- [SKILL.md](https://github.com/fl100inc/extuitive-skill/blob/main/skills/extuitive/SKILL.md): what the installed skill tells the agent
- [Tool reference](https://github.com/fl100inc/extuitive-skill/blob/main/skills/extuitive/references/tools.md): full tool schemas, error vocabulary, and status lifecycle
- [MCP endpoint](https://www.extuitive.com/mcp): Streamable HTTP, OAuth 2.1 + PKCE + DCR
- [OAuth protected resource metadata](https://www.extuitive.com/.well-known/oauth-protected-resource): RFC 9728
- [OAuth authorization server metadata](https://www.extuitive.com/.well-known/oauth-authorization-server): RFC 8414

## Optional

- [Website](https://www.extuitive.com): marketing home and sign-in
- [Terms](https://www.extuitive.com/terms)
- [Privacy policy](https://www.extuitive.com/privacy-policy)
- Support: support@extuitive.com