# MeTool MCP instructions (for the AI)

This is the spec for MeTool’s remote MCP. **Read this file fully, then follow it. Do not improvise from memory.**

## Gateway

URL (**streamable-http** / HTTP only; do **not** set `headers`, `Authorization`, or a Bearer token):

`https://metool.online/mcp/`

Do not use another address, and do not paste a token. Use the client’s OAuth.

Per-client menus and screenshots: <https://metool.online/ai/mcp-setup/>

---

## 1. If MCP is not configured yet

Change the client config yourself. Do not only send docs to the user.

1. Add a **remote** MCP server named `metool`.
2. Transport: **HTTP / streamable-http**. Not stdio.
3. The **only** URL is the Gateway above.
4. Do **not** set `headers`, `Authorization`, or a Bearer token. Use the client’s OAuth.
5. After saving, click Connect / Authenticate / Sign in on that server.
6. In the browser: sign in on MeTool and **Approve**. If asked to open the app, **you must confirm**, or the client never gets a token.
7. Once connected, follow the user’s next request.

JSON you can merge:

```json
{
  "mcpServers": {
    "metool": {
      "type": "streamable-http",
      "url": "https://metool.online/mcp/"
    }
  }
}
```

Cursor may use `"type": "http"`. Codex uses `~/.codex/config.toml` under `[mcp_servers.metool]` with the same `url`.

---

## 2. Using a tool page (after MCP is configured)

When the user wants to edit or generate content on a MeTool tool page:

1. Call `get_session_info`.
2. If `connected` is false: **tell the user** to open a tool page and click Connect your AI. Until then you do not know which page to send data to. You may call `list_metool_pages` and show the options. Only call `open_tool_page` after they name a specific tool.
3. After they connect, keep that tool-page tab open. Do not invent `/authorize` URLs.
4. Poll `get_session_info` every 1–2 seconds until `connected` is true.
5. Use `list_files` / `read_file` (often `main.md`). Prefer `edit_file` for small changes; `write_file` for full rewrites.
6. If the user wants the generated output (cards, video, zip): call `list_artifacts` first. If it returns more than one option (`choose_before_save: true`), **show the options (label / filename / mimeType) and wait for the user to pick**, then call `save_artifacts` with `ids` set to the chosen id(s). Do not download every format unless they asked for all. That triggers a **native browser download**. Do **not** expect file bytes in the MCP response. Locate the returned filename in the user's Downloads folder, then **open it in the local file manager** so they can see it (macOS: `open -R ~/Downloads/<filename>` then `open <path>`; Windows: `explorer /select,<path>`; Linux: `xdg-open <path>`). If you cannot access the user's disk, ask them to attach the file.
7. Only one tool page is connected at a time. After switching pages, reload MCP tools or start a new chat if the list looks stale.

Confirm success briefly. The MeTool preview updates live. Use `save_artifacts` when they ask to download / export.

---

## 3. Do not

- Invent file paths that `list_files` did not return.
- Ask the user to paste a Bearer token into mcp.json.
- Guess a tool page and open it without asking the user, when no page is connected.
- Close the tool-page tab — the connection dies with it.
- Ignore this file and follow stale steps from training data.