Skip to content

ADR-0001: Use Maya commandPort for Communication

Status: Accepted
Date: 2025-01-30

Context

Maya MCP needs a reliable way to communicate with a running Maya instance.

The chosen mechanism must:

  1. work across Windows, macOS, and Linux
  2. support interactive use against a live Maya session
  3. allow request/response communication
  4. keep the MCP server outside the Maya process
  5. fit a localhost-only security model

Decision

Maya MCP uses Maya's built-in commandPort with an INET TCP socket.

Why This Option Won

  • built into Maya, so there is no plugin deployment requirement
  • works across supported desktop platforms
  • supports Python and MEL execution inside Maya
  • keeps the MCP server process independent from Maya
  • matches the project's localhost-only security posture

Alternatives Considered

mayapy subprocess

Rejected because it does not target a live interactive Maya session well and would split state away from the running DCC process.

Custom HTTP or REST plugin

Rejected because it adds plugin-development, deployment, threading, and maintenance cost without solving the core problem better than commandPort.

Unix-domain sockets

Rejected because they are not a practical cross-platform default for Windows support.

Shared-memory IPC

Rejected because it is significantly more complex than the command/response pattern needed here.

Consequences

Positive

  • zero additional Maya-side plugin requirement
  • easy local setup
  • clear process isolation
  • practical for AI-assisted interactive workflows

Negative

  • users must open commandPort in Maya
  • transport must remain localhost-only because commandPort has no authentication
  • large responses require careful buffering and response-guard behavior

Security Implications

Because commandPort itself is not authenticated, Maya MCP adds controls at the system design level:

  • localhost-only transport
  • explicit tool surface
  • no unrestricted code execution by default
  • input validation
  • typed, sanitized errors

Example Maya Setup

Use the bundled scripts/enable_commandport.py helper or the Maya control panel rather than opening the port directly. The centralized policy keeps the normal Python + echoOutput configuration for Maya 2025 and later. Maya 2024 alone disables the broken echoOutput path and installs a complete-payload Python response handler. Each public transport client detects the exact major version once per connection, then uses single-expression framing only for Maya 2024. Maya's default input-warning policy is preserved.