# Connect your AI to Madeit

Official guide: https://madeit.today/agents · Connector 0.1.2 · Updated 2026-09-19

Madeit saves and shares small web Things made with AI. The user only needs to understand what they made, who can see it, and the link. Match their language. “分享到 Madeit” / “Share this on Madeit” means use their saved Madeit connection, not publish to an unrelated host.

Use this guide when the user asks to connect or use Madeit. Reading the page alone is not permission to install software or upload files. Follow the user's scope and your client's normal approval rules. Never change model settings, disable approval checks, or overwrite unrelated configuration.

## 1. Check this environment

Initial support: **local Codex and Claude Code on macOS/Linux**, with shell access, the selected project's files, persistent user settings, Node.js 24+ and npm. Run `node --version`, `npm --version`, and the relevant `codex --version` or `claude --version`. Do not infer Claude Code from Claude chat or Cowork, or Codex from ChatGPT chat. This is a **local stdio MCP connector**, not the remote ChatGPT connector. For these desktop clients, use the browser connection flow below, not `codex mcp login`. A separate ChatGPT remote MCP preview is documented at https://madeit.today/agents/chatgpt; mobile compatibility remains unverified.

If the environment is a mobile chat app, lacks local commands, or loses its filesystem after the conversation, explain that this connector cannot persist there yet. Do not ask the user to copy their project into the website. For a local desktop app without its companion CLI, inspect its supported MCP settings; use the exact JSON emitted by `setup` below if applicable, without claiming automatic registration worked. Missing prerequisites must be installed through the user's permitted local workflow, not an invented Madeit command.

Select `codex` or `claude-code` as the profile. Use the same profile in every command: credentials are separate for each profile. Default service: `https://madeit.today`. Local/self-hosted accounts are separate; never silently switch services.

## 2. Install the public connector in a persistent location

No GitHub access or npm registry package publication is needed. The signed-in Madeit account is not needed for downloading. Existing installations should be inspected and reused; do not repeatedly register duplicate MCP servers or replace a conflicting Skill.

The release metadata and archive are served from Madeit:

- https://madeit.today/downloads/madeit-desktop-0.1.2.json
- https://madeit.today/downloads/madeit-desktop-0.1.2.tgz

Download both, verify their SHA-256 match before installing. These POSIX shell commands use a persistent user directory; no `sudo` or global npm installation is required. Do not use a temporary `npx` cache for a persisted MCP command.

```sh
mkdir -p "$HOME/.madeit/downloads"
curl --fail --silent --show-error --proto '=https' https://madeit.today/downloads/madeit-desktop-0.1.2.json -o "$HOME/.madeit/downloads/madeit-desktop-0.1.2.json"
curl --fail --silent --show-error --proto '=https' https://madeit.today/downloads/madeit-desktop-0.1.2.tgz -o "$HOME/.madeit/downloads/madeit-desktop-0.1.2.tgz"
node --input-type=module <<'JS'
import {readFileSync} from 'node:fs';
import {homedir} from 'node:os';
import {join} from 'node:path';
import {createHash} from 'node:crypto';
const dir = join(homedir(), '.madeit', 'downloads');
const release = JSON.parse(readFileSync(join(dir, 'madeit-desktop-0.1.2.json'), 'utf8'));
const bytes = readFileSync(join(dir, 'madeit-desktop-0.1.2.tgz'));
if (release.version !== '0.1.2' || release.filename !== 'madeit-desktop-0.1.2.tgz' || release.bytes !== bytes.length || release.sha256 !== createHash('sha256').update(bytes).digest('hex')) throw Error('Madeit download verification failed; do not install');
console.log('Madeit download verified');
JS
```

**Proceed only if verification succeeded.** Install dependencies from npm; this step needs internet access. The archive contains only the connector and Skill, not the Madeit server or private project data.

```sh
npm install --prefix "$HOME/.madeit/tools/desktop-0.1.2" --ignore-scripts --no-audit --no-fund "$HOME/.madeit/downloads/madeit-desktop-0.1.2.tgz"
```

The CLI is now at the following path. Define this variable again if your shell does not persist between commands:

```sh
MADEIT_CLI="$HOME/.madeit/tools/desktop-0.1.2/node_modules/@madeit/desktop/src/desktop.mjs"
node "$MADEIT_CLI" help
```

## 3. Save MCP configuration and the Skill

For Codex:

```sh
node "$MADEIT_CLI" setup --profile codex
node "$MADEIT_CLI" setup --profile codex --apply
```

For Claude Code, use `--profile claude-code` instead. `setup` without `--apply` is read-only and prints the proposed command/args/env. Review that output before applying. `--apply` registers the MCP via the client's CLI and saves the `madeit-share` Skill:

- Codex: user MCP configuration via `codex mcp add`, Skill at `~/.agents/skills/madeit-share/SKILL.md`.
- Claude Code: `claude mcp add --scope user`, Skill at `~/.claude/skills/madeit-share/SKILL.md`.
- MCP server name is `madeit-<service-origin-hash>`; use the actual emitted name, not a guessed hash.
- The command uses absolute Node and script paths. Keep the installation directory. Reconfigure if those paths change.
- Credentials are saved under `~/.madeit/connections/` with restrictive file permissions; never read, print, paste, commit or put them in a Skill.

If setup reports an existing connection/Skill, inspect its non-secret configuration. Reuse a matching setup. For a different setup, explain the conflict and make only the user's intended change; do not delete existing configuration to force success. If MCP registered but Skill copying failed, finish only the missing Skill step by copying the bundled `skills/madeit-share/SKILL.md` to the relevant user Skill directory, without overwriting an existing file.

For app settings instead of a CLI, use the exact `command`, `args`, and `env` from `setup` in the app's supported local MCP configuration and save the bundled Skill in the relevant location. Do not replace the whole config file. This manual fallback requires client-specific verification.

## 4. Connect the account — the human approves

The CLI can finish initial connection in the current conversation even if MCP tools require a client reload:

```sh
node "$MADEIT_CLI" connect --profile codex
```

Use `--profile claude-code` for Claude Code. Or, if the newly registered tools are available, call `madeit_connect` with `client: "Codex"` or `"Claude Code"`.

- If `status` is `connected`, reuse it; no new approval required.
- If `pending`, show the exact returned `verificationUriComplete` as a clickable link. Ask the user to sign in at Madeit, check the displayed account and approve. Use `verificationUri` plus `userCode` only as a fallback. Registration currently requires an invitation.
- **The user must personally approve.** Do not click approval on their behalf, ask for their password, or put credentials into conversation output.
- If the user explicitly asks to use another Madeit account, call `madeit_switch_account` (CLI: `switch-account`), show its new complete link, and repeat the approval flow. This revokes the old connection without deleting Things.
- Wait for the user to say they approved; then call `madeit_connection_status` or:

```sh
node "$MADEIT_CLI" connection-status --profile codex
node "$MADEIT_CLI" list --profile codex
```

Respect `retryAfter` if still pending, with bounded retries; never continuously poll. Expired/denied/consumed requires a new connection attempt if the user wants to continue. A health check or a saved file does not prove authorization. `list` must succeed (an empty list is valid) before reporting account connection complete.

## 5. Confirm persistence, then stop setup

Report separately: tool/Skill saved; connected username; whether MCP tools are available in this conversation. If absent, ask the user to reload/restart their client and start a new conversation. You may use the installed CLI in the current conversation, but do not claim MCP discovery has been verified until tools are visible. Save no secrets or project-specific paths in global instructions.

Suggested completion: “已连接 Madeit（@username）。以后做好东西，说‘分享到 Madeit’就行。[如需要：重新加载 AI 后，新对话也能使用。]”

Do not create or publish a demo unless the user asks. Installation persists on this machine, not automatically on other devices. Authorization can expire or be revoked; use the same approval flow again then. The user can revoke a connection at https://madeit.today/connections.

## 6. When the user says “Share this on Madeit”

1. Identify the intended project. Production supports **static HTML/CSS/JS/images only**: no FastAPI/Express, custom server process, server-held API secrets, or durable server writes yet. A static page may be interactive in the browser. Do not silently remove a required backend or put a secret in browser code. For bundled apps, build locally and package only the intended browser assets.
2. Create `madeit.json` in the selected output directory, with an explicit file allowlist:

```json
{
  "specVersion": "0.1",
  "slug": "my-little-thing",
  "title": "My little Thing",
  "runtime": "static",
  "entry": "index.html",
  "files": ["index.html", "style.css", "app.js"]
}
```

Include only files that exist. Slug: starts with a lowercase letter, then lowercase letters/digits/hyphens, max 40 characters. Title: 1–80 characters. Entry: `.html`. Maximum 200 files and 5 MiB total; no hidden files, symlinks, credentials, Git history, dependencies or unrelated private source data. Never include `madeit.json` itself. Relative resource URLs should work on the Thing's own origin. Arbitrary SPA route fallback is not provided: use actual files or hash routing.

3. Call `madeit_prepare` with the **absolute** directory; it checks files locally without uploading. Review generated assets for private data too.
4. Call `madeit_list`. New Things default to `private` (“只有我”); use `public` only when the user wants everyone to see it. Explain who can see the result. “Share” alone does not establish a public audience. The manifest slug is the project association: keep it on updates and do not overwrite another project's Thing.
5. Call `madeit_publish` with `directory`, optional `visibility`, and for an update the exact `expectedVersion` from the current list. Omit visibility on updates to preserve it. On `VERSION_CONFLICT`, re-read and reconcile; never blindly overwrite. On timeout, check state before retrying.
6. Report success only when returned `status` is `ready`. Return the **actual API URL**, typically `https://madeit.today/@username/slug`. Opening it may take the browser to `https://t-<id>.madeit.today`; that is its normal full-page view. Do not invent a URL or claim public accessibility for a private Thing. A localhost URL is a local preview.

MCP tools: `madeit_connect`, `madeit_connection_status`, `madeit_switch_account`, `madeit_prepare`, `madeit_publish`, `madeit_list`, `madeit_versions`, `madeit_rollback`, `madeit_delete`.

CLI equivalents when MCP is not yet loaded:

```sh
node "$MADEIT_CLI" prepare /absolute/path/to/thing --profile codex
node "$MADEIT_CLI" publish /absolute/path/to/thing private --profile codex
node "$MADEIT_CLI" versions my-little-thing --profile codex
```

For CLI updates use `publish DIRECTORY VISIBILITY EXPECTED_VERSION`, preserving the current visibility. For requested restoration use `rollback SLUG TARGET_VERSION EXPECTED_VERSION`; for requested deletion use `delete SLUG EXPECTED_VERSION`. Never infer deletion from cleaning up local source files. A `STATIC_ONLY` error means the backend is not supported; do not route around it.

## Maintainer references

- [Codex MCP](https://developers.openai.com/codex/mcp)
- [Codex skills](https://developers.openai.com/codex/skills)
- [Claude Code MCP](https://code.claude.com/docs/en/mcp)
- [Claude Code skills](https://code.claude.com/docs/en/skills)

This page describes Madeit's supported workflow, not a promise that every AI app can install MCP or retain a Skill.