# Working over MCP

You reach Moket from outside, as a client of its MCP server: Claude Code, Claude, ChatGPT, Codex or another agent. No Moket tab or editor needs to be open for you, and you never ask the user to open a document or to make a project. You use the same tools as Moket AI in the editor, and your changes follow the user's approvals.

## Projects and documents

1. Start with `list_projects`: the user's projects with their documents, templates, notes (`noteId`, read them first: see [Project notes](notes.md)) and parameter table (`parametersId`).
2. `list_agent_documents` with a `projectId` lists a project's documents; without one, what is open now.
3. `create_project` makes a project; `create_part`, `create_drawing` (from a part or an assembly, with a template), `create_assembly` and `create_note` make documents. Give the user the link `create_part` returns when they want to look.
4. Work on any document by its `documentId`: Moket opens it for you in the background, and the user follows your work in Agent activity. Every applied plan is a version of the document in your name.

## Plans that wait

A plan the user must approve waits in Agent activity and in the document's editor. `commit_plan` with its `previewId` answers `pending` until the user decides, then `applied` or `discarded`: call it again to keep waiting, and tell the user what waits for them. A plan that applied at once (`autoApplied`) needs no `commit_plan`.

## When something is unavailable

- `CAD_SESSION_UNAVAILABLE` means nothing can open documents for you right now: ask the user to open Moket in a browser tab, or to turn on **Work without an open tab** in Settings > Agents.
- `HOST_UPDATING` means Moket is restarting on a new version: call again in a few seconds.
- `HOST_OUTDATED` means Moket was updated and the user's tab that runs your tools still has the old version open in an editor: ask the user to reload that tab.
- `EDITOR_NOT_READY` means the document is opening in the user's editor tab: call again in a few seconds.
- `DOCUMENT_CONFLICT` means the user's editor holds changes made on an older revision: ask the user to click **Choose what to keep** in the banner over the view in that tab and pick **Keep my changes** or **Use rev N** (the newest revision: usually right when they did not mean to change anything there), then call again.
- `revision` in what the tools return is the document's revision in the cloud, the one `list_agent_documents` lists and the user sees in Versions.
- A tool or a guide name that a guide mentions is missing from your tool list: Moket was updated after you connected, and your client keeps the list it read then. Ask the user to reconnect Moket in the client (`/mcp` in Claude Code).
- A call that fails without an answer may still have applied: inspect the document and compare its revision before you send the plan again.

## Guides and this skill

`read_guide` returns any guide by name (`working`, `parts`, `sketches`, `assemblies`, `mechanisms`, `drawings`, `project-parameters`, `notes`, `library`, `mcp`), and without a name lists them. They are also MCP resources (`moket://guides/<name>`). The text Moket answers is always current; a skill installed earlier is a copy of the day it was downloaded.

## Feedback

When a tool behaves differently from its description, when you need something Moket cannot do, or when a description misled you, tell Moket's team once with `send_feedback`, then go on with the task.