Provides MCP tools for interacting with FacetCue annotations in Blender: agents can read surface-anchored notes with IDs, revisions, positions, and visibility, and submit completion summaries for edits made with separate Blender modeling tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@FacetCue MCP Server Read my FacetCue surface annotations and process all pending change requests."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
简体中文 · Downloads · User guide · Release notes
Put a note on the surface. Let your agent work from it. Review the result in Blender.
FacetCue turns changes you want into independent, annotated markers on a Blender model. Each marker tells an agent what to change and where: a natural-language request, a surface anchor, current 3D coordinates and viewport visibility. Through MCP, the agent can read the requests in a batch, apply edits using its connected Blender modeling tools, and submit each result for your review.
0.5.2 · Beta · Blender 4.2+ · Python 3.10+ for MCP · GPL-3.0-or-later
Capability | How it works |
One marker, one issue | Give each requested change its own note, number and distinct color. |
Surface-bound context | Anchor to a supported mesh triangle; expose current position, normal and anchor validity. |
Immediate agent access | Read confirmed notes without selecting objects, saving the file, taking screenshots or showing overlays. |
Batch processing | Read multiple issues, follow pagination for larger sets, and submit completion summaries by marker ID. |
Review in Blender | Track open, in-progress, awaiting-review, resolved, changes-requested and archived states; locate and review each issue. |
Continue later | Save the |
Markers are viewport overlays and scene metadata. They add no renderable or exportable geometry. You control their display; agents can still read confirmed notes while markers or objects are hidden.
Related MCP server: Blender MCP Server
Mark: in Object Mode with Solid shading, place a marker on a supported mesh surface.
Describe: enter a request, such as “move this panel up by 0.12 Blender units; preserve its shape and size.” Press Enter to save.
Delegate: ask your agent to read the FacetCue marks and process the requested changes.
Inspect: completed submissions gain a blue dot with a narrow white border. The original marker color stays unchanged.
Review: jump to the point for a close view, then approve or reject and revise the request. Save your .blend to keep the review record.
FacetCue supplies the annotation and review connection. Model edits require an agent with separate Blender modeling tools. Installing FacetCue alone does not start an autonomous editing session or provide arbitrary Python execution.
Download facetcue-0.5.2.zip from Releases. In Blender, use Preferences → Add-ons → Install from Disk, select the ZIP without extracting it, and enable FacetCue for Blender. Open 3D View → N → FacetCue for Blender. Enable only one installation of the add-on.
The ZIP is enough for local annotation and review. GitHub's automatic Source code archives are for development and cannot be installed directly as Blender extensions.
For agent access, download facetcue-0.5.2-py3-none-any.whl from the same release. Run these commands in its download directory with a separate Python 3.10+ installation.
Windows PowerShell:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install .\facetcue-0.5.2-py3-none-any.whlmacOS / Linux:
python3 -m venv .venv
./.venv/bin/python -m pip install ./facetcue-0.5.2-py3-none-any.whlThe wheel's dependencies are installed by pip; they are not bundled. The Blender add-on uses Blender APIs and the standard library only. Do not install MCP dependencies into Blender's Python.
Add a stdio MCP server to your agent client. Set command to the absolute path of the Python executable above and args to ["-m", "agent_mcp.server"]. See the TOML configuration example.
Keep Blender running with the add-on enabled, then reload your client's MCP configuration. One Blender instance is discovered automatically. With several instances, set ASM_INSTANCE to the session ID shown in the target Blender panel; update it after restarting that connection. No fixed port or third-party Blender MCP bridge is needed for annotation access.
The client should discover two tools:
Tool | Purpose |
| Read notes, stable IDs, revisions, positions and visibility. Start without arguments; follow |
| After successful edits, submit marker IDs, the revisions read before editing and a summary of actual work. This marks the results for user review. |
Example request to your agent:
Read my FacetCue surface annotations. Process the pending requests with the connected Blender modeling tools, preserve the stated constraints, and submit a completion summary for each successful change. Leave approval to me.
Display toggles, object selection and sidebar filters do not restrict agent reads. Unconfirmed drafts are excluded. Connection failures return errors, not empty results. See the API guide for revision handling and data semantics.
Notes open in a compact, draggable Blender dialog near the lower center of the viewport. Enter saves; Esc cancels. Drag its title to move it; later note dialogs reuse that position, including after restarting Blender. Click a marker to select it or double-click its number to edit. Longer notes have an explicit Multiline edit entry in the sidebar; existing line breaks are preserved. Search, status filters and close-up navigation help you work through a batch.
Shortcut in Object Mode / 3D View | Action |
Ctrl+Alt+Shift+M | Toggle marker display and point selection |
Ctrl+Alt+Shift+A | Place a marker |
Ctrl+Alt+Shift+Left / Right | Previous / next matching marker |
Ctrl+Alt+Shift+Enter | Approve the selected modified marker |
Ctrl+Alt+Shift+Backspace | Reject and edit its request |
Ctrl+Alt+Shift+Z | Withdraw the most recent review decision |
Ctrl+Alt+Shift+X | Confirm deletion of the selected marker |
Annotation UI edits and deletion support Blender Ctrl+Z / Ctrl+Shift+Z. Review withdrawal restores the previous note and review state without undoing geometry. Detected keymap conflicts are skipped and reported in the panel; change bindings in Blender's Keymap preferences as needed.
Both FacetCue display and Blender Show Overlays must be enabled to see markers. Normal mode hides occluded points. Alt+Z (X-Ray) reveals them at 60% transparency / 40% opacity, with note cards collapsed by default. Review badges follow the same visibility and transparency as their markers.
Requires Blender 4.2+. Windows with Blender 5.2.1 LTS has been validated. The same packages target macOS and Linux, but Blender runtime behavior on those platforms still needs testing. Cross-platform Python CI does not establish Blender runtime compatibility.
Anchors support base mesh objects without enabled viewport modifiers or shape keys. Unsupported or changed topology preserves the note but returns an explicitly invalid position; automatic reattachment is not provided.
Scene duplication does not duplicate annotations. As marker counts grow, use numbers alongside colors to distinguish issues.
Confirmed edits are immediately available to agents. Save the .blend to preserve them across sessions; sharing that file also shares its stored annotation metadata.
The add-on serves authenticated requests on 127.0.0.1 only, using a temporary per-user discovery file. It accepts annotation reads and completion submissions, not geometry commands or arbitrary Python. FacetCue has no cloud service or telemetry; annotations read by your agent are subject to that agent's data policy. See SECURITY.
python -m pip install -e ".[dev]"
python -m ruff check .
python -m ruff format --check .
python scripts/export_mcp_catalog.py --check
python scripts/package_addon.py
python -m build
python scripts/check_release.py --blender /path/to/blenderBuilds produce the extension ZIP, MCP wheel, source archive and SHA256SUMS in dist/. CI checks style, MCP contracts and package contents; the optional Blender check validates installation in an isolated process. Packaging never publishes. See CONTRIBUTING for module boundaries and development guidance.
Read user surface marks/TODOs from the current Blender file in one call.
Call with no arguments first. Returns all statuses from all scenes, including hidden objects and hidden overlays: full notes, stable IDs, current 3D positions, anchor validity, and automatically selected viewport visibility. No selection, saving, Python code or screenshot is required. Includes unsaved edits. No viewport still returns notes and 3D positions. Pagination: follow next_offset if has_more. Each page is a fresh read. scene_name optionally narrows the file; limit is 1..200. Set include_visibility=false for a lighter read. Blender must be running with FacetCue for Blender enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| scene_name | No | ||
| include_visibility | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), and the description adds substantial context beyond them: it includes hidden objects/overlays, unsaved edits, works with no viewport, each page is a fresh read, and requires Blender running with FacetCue enabled. This is a genuine auth prerequisite and coverage disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and return summary, then layers prerequisites and pagination. Dense but every clause carries information; the 'no selection, saving, Python code or screenshot is required' list is slightly flourishy but clarifies a common agent assumption.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description covers the return shape well (full notes, stable IDs, 3D positions, anchor validity, visibility), plus prerequisites and pagination. Nothing an agent needs to call this correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it largely does: scene_name narrows the file, limit is 1..200, include_visibility=false gives a lighter read, and pagination follows next_offset. It never directly explains the offset parameter's meaning, leaving one small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read user surface marks/TODOs from the current Blender file') with clear scope. It does not explicitly name or contrast with its only sibling submit_annotation_changes, though the read-vs-write distinction is inferable. Clear purpose but no explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Call with no arguments first' and gives conditions for optional narrowing ('scene_name optionally narrows the file') and a lighter read ('include_visibility=false'). No explicit when-not guidance or named alternative, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After model edits succeed, mark 1..200 affected annotations as MODIFIED.
Pass the scene_name, marker_id and expected_revision from the read before editing, plus a brief summary of actual completed work. The whole batch is validated before status writes. Same revision/summary retries are safe. This adds a blue review badge; it does not change geometry, approve work, overwrite user notes, or infer which objects were edited. A revision conflict requires rereading and reconciling the updated user request.
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the actual effect (a blue review badge, no geometry change), the atomicity guarantee ('the whole batch is validated before status writes'), retry semantics for identical revision/summary, and the required recovery path on conflict. These complement rather than restate readOnly=false, idempotent=true, destructive=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action in the first sentence, then preconditions, safety notes, exclusions, and error recovery in short blocks; every sentence carries information. The idempotency sentence partly echoes the idempotentHint annotation and could be tightened, but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers invocation, preconditions, side effects, idempotency, and conflict recovery, which is strong for a batch-mutation tool with an idempotent, non-destructive profile. With no output schema, it stops short of describing what a successful call returns (e.g., per-item validation results), which is the one remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the load and does: it explains each nested field's source (scene_name, marker_id, expected_revision taken from the pre-edit read) and the intent of summary ('brief summary of actual completed work'). It also adds a batch-size constraint (1..200) that appears nowhere in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('mark 1..200 affected annotations as MODIFIED') and scopes it with a concrete bound and a triggering condition ('After model edits succeed'). The negative list ('does not change geometry, approve work, overwrite user notes') separates it cleanly from adjacent write-style actions and from the read-only sibling get_surface_annotations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to invoke it ('after model edits succeed'), what to pass and from where ('from the read before editing'), and how to recover from failure ('a revision conflict requires rereading and reconciling'). It gives clear context but never explicitly names an alternative tool or a case where the call should be skipped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.5.2get_surface_annotationssubmit_annotation_changesScored across 2 tools
The two tools have clearly distinct purposes: one reads annotations, the other submits changes. There is no overlap in functionality, and their descriptions make the read vs. write separation obvious.
Both tools follow a consistent verb_noun pattern in snake_case (get_surface_annotations, submit_annotation_changes). The naming is predictable and easy to parse.
With only 2 tools, the count is slightly below the typical 3–15 range, but it fits the narrow read-and-update workflow. No additional tools are needed for the stated purpose, so the count is reasonable.
The server covers reading all annotations and marking affected ones as MODIFIED after edits, which closes the core loop. It intentionally omits creating or deleting annotations (done in Blender) and only supports the MODIFIED status, a minor gap for broader annotation management.
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
MarkupBase turns AI-generated Markdown and HTML into durable, versioned artifacts that people can review and discuss. Its MCP server lets agents publish new versions, preserve contextual comments, include hosted images, and respond to feedback through secure account-linked identities, creating a clear human review boundary without requiring real-time editing.
Versioned artifact review for people and AI agents, with contextual comments and human control.
The coordination layer for autonomous agents working on beneficial projects: research, shared knowledge, and tools that help people or agents. Discover public goals, share a workspace, claim leased tasks, exchange handoffs, submit evidence, and review results without a human dispatcher. Agents execute in their own runtimes. Public help; OAuth or an agent key for protected tools. Start the two-agent walkthrough: https://agentsknow.app/docs/getting-started. MCP: https://agentsknow.app/mcp. Skills and examples: https://github.com/stockblog/agentboard-checkpoint (client and instructions, not server source).