Nexora Forge MCP

AI-native 3D production for Blender

A secure MCP automation platform I built to connect modern AI systems with Blender, coordinate multi-agent 3D workflows, manage collaborative asset production and keep a human approval step before final versions are published.

Installer · Architecture · Security · Cloud · Production Pipeline · Tool Catalog

Overview

I built Nexora Forge to turn an MCP-capable AI client into a structured Blender production operator without exposing Blender directly to the Internet.

The project is split into four main layers:

• Nexora Forge MCP Gateway — the Streamable HTTP MCP server that handles authentication, permission profiles, auditing and structured Blender tools.

• Blender Extension Bridge — a loopback-only bridge that dispatches bpy work back onto Blender's main thread.

• Nexora Forge Cloud — the optional PostgreSQL-backed collaboration and control plane for projects, devices, jobs, assets, versions and review.

• Device Agent — an outbound-only workstation worker that leases jobs from Cloud, controls the local Blender bridge, uploads artifacts/previews and waits for human approval.

My goal is to make the same platform useful for both individual creators and teams. It can be used for characters, creatures, zombies, weapons, props, skins/materials, environments, lobbies, rigs, animations, emotes, previews and game-ready exports.

Related MCP server: Subhuti Blender MCP

Technology

AI providers

I also included support for a custom OpenAI-compatible endpoint so I am not forced to hard-code every future provider into the core.

Architecture

I deliberately keep the public-facing services separated from Blender itself.

flowchart LR
    AI["ChatGPT / Responses API / MCP Host"] -->|HTTPS + MCP| GW["Nexora Forge MCP Gateway"]
    GW -->|127.0.0.1 + bridge secret| BR["Blender Extension Bridge"]
    BR --> BL["Blender / bpy"]

    HUMAN["Human Team"] --> CLOUD["Nexora Forge Cloud"]
    AGENTS["Multi-Agent Team"] --> CLOUD
    CLOUD -->|job lease| DA["Device Agent"]
    DA -->|local bridge| BR
    DA -->|preview + .blend + exports| CLOUD
    CLOUD --> REVIEW["Human Approval"]
    REVIEW --> VERSION["Approved Asset Version"]

Trust boundaries

What it can do

I focused the structured MCP surface on operations that are useful for real production instead of exposing Blender as one giant unsafe remote shell.

See docs/TOOL_CATALOG.md for the full MCP surface.

Nexora Forge Cloud

I added Forge Cloud so the project can grow beyond a single workstation without turning Blender into a shared public server.

The Cloud layer coordinates people, agents, devices, assets and production jobs while Blender continues to run locally on each enrolled workstation.

Human collaboration

The current Cloud foundation supports:

• organizations and project workspaces;

• project members and roles;

• enrolled Blender workstations;

• asset ownership and lease-based asset locking;

• immutable asset versions;

• previews and stored artifacts;

• human approval/rejection/change requests;

• auditable jobs and agent runs.

Multi-agent collaboration

I designed Agent Teams so one production request can use different AI providers and models at the same time.

flowchart TD
    U["Production request"] --> C["Coordinator"]
    C --> M["Modeler"]
    C --> R["Rigger / Animator"]
    C --> E["Environment / Export"]
    M --> V["Reviewer"]
    R --> V
    E --> V
    V --> P["Conflict-free execution plan"]

Each agent can independently select:

• role;

• provider;

• model;

• direct provider API or AI Gateway route;

• enabled/disabled state.

Dry-run mode lets me validate an Agent Team without sending provider requests or consuming provider tokens.

Production pipeline

The Cloud production pipeline is implemented end-to-end:

sequenceDiagram
    participant H as Human
    participant C as Forge Cloud
    participant D as Device Agent
    participant B as Blender
    participant S as Object Storage

    H->>C: Queue structured Blender job
    C->>C: Acquire/validate asset lock
    D->>C: Poll for work
    C-->>D: Atomic job lease + lease token
    loop During execution
        D->>C: Lease heartbeat
        D->>B: Structured Blender operation
        B-->>D: Result
    end
    D->>B: Save .blend checkpoint
    D->>B: Render preview
    D->>S: Upload .blend / exports / preview
    D->>C: Complete execution
    C-->>H: Awaiting approval
    H->>C: Approve / request changes / reject
    C->>C: Publish approved asset version

Lease guarantees

I use leases instead of permanent locks so abandoned clients do not block production forever.

• PostgreSQL FOR UPDATE SKIP LOCKED prevents multiple devices from claiming the same queued job.

• Every job lease has a separate secret lease token and expiry.

• Device heartbeats extend both the job lease and the associated asset lock.

• Expired leases can be recovered by another eligible device.

• Cloud jobs only accept the structured allowlist; python.execute is not accepted in queued Cloud plans.

Human approval

A completed Device Agent job enters awaiting_approval instead of becoming a published asset version automatically.

Open:

/cloud/review/<jobId>

From there I can:

• Approve & publish — promote the latest .blend or export artifact to the next immutable asset version.

• Request changes — return the job to the queue without publishing a version.

• Reject — close the job and release the asset lock.

Installation

Nexora Forge now includes a local installer and lifecycle manager. The recommended first command is:

uv sync --all-extras
uv run nexora-forge setup

Or use the platform wrappers:

Linux / macOS

./scripts/install.sh

Windows PowerShell

.\scripts\install.ps1

The setup wizard asks how the installation will be used:

How do you want to use Nexora Forge?

1) Individual
2) Team Host
3) Join Team

Individual

nexora-forge setup --mode individual
nexora-forge start
nexora-forge doctor

This creates the private local configuration, workspace and MCP/Blender bridge secrets.

Team Host

nexora-forge setup --mode team-host
nexora-forge start

With Docker, Node.js and npm available, the installer prepares the private PostgreSQL control plane, applies migrations, builds the web UI, creates the initial organization/project and pairs the host workstation.

Join Team

The owner/admin creates a member:

nexora-forge member add --name "Artist A" --role artist

Nexora Forge returns a temporary single-use code such as:

NXR-ABCD-EFGH-JKLM

The member joins with:

nexora-forge setup --mode join-team \
  --server http://TEAM-HOST:3000 \
  --code NXR-ABCD-EFGH-JKLM

The pairing flow creates the member and Device Agent credentials automatically. No UUIDs or database IDs need to be copied.

Lifecycle commands

nexora-forge start
nexora-forge stop
nexora-forge status
nexora-forge doctor
nexora-forge update
nexora-forge pair
nexora-forge token

See docs/INSTALLER.md for the complete installer, pairing, role and troubleshooting guide.

Blender extension

Install the blender_extension directory as a Blender extension/development extension.

Configure the NEXORA_BRIDGE_SECRET generated in .env, then start the bridge from the Nexora Forge MCP Blender panel.

Default local endpoints:

MCP Gateway:    http://127.0.0.1:8765/mcp
Blender Bridge: http://127.0.0.1:9876

I intentionally keep the Blender bridge on loopback. Port 9876 should never be exposed directly to the Internet.

Remote MCP access

I included three gateway modes so the same project can work locally, through a private tunnel or as a stable remote MCP resource server.

Cloudflare Tunnel and ngrok launch examples are available in scripts/ and deploy/cloudflare/.

See:

• OpenAI compatibility

• Secure MCP Tunnel

• OAuth deployment

• Remote access

Team Host / Forge Cloud

For normal use I let the installer configure Forge Cloud:

nexora-forge setup --mode team-host
nexora-forge start

The Team Host installer prepares:

• PostgreSQL in a private Docker Compose service;

• all migrations under deploy/postgres/;

• the initial organization/project;

• owner and host-device credentials;

• local artifact storage;

• the Next.js control center;

• the local MCP gateway and Device Agent runtime configuration.

The control center provides:

/cloud
/cloud/pipeline
/cloud/review/<jobId>

The owner/admin can create members and one-time pairing codes directly from the pipeline UI or CLI.

Manual/advanced setup

Manual PostgreSQL deployments remain supported. Apply all migrations in order, including the local team-access migration:

psql "$DATABASE_URL" -f deploy/postgres/001_forge_cloud.sql
psql "$DATABASE_URL" -f deploy/postgres/002_production_pipeline.sql
psql "$DATABASE_URL" -f deploy/postgres/003_local_team_access.sql

Local storage remains the default:

NEXORA_STORAGE_DRIVER=local
NEXORA_STORAGE_ROOT=.nexora-storage

A private team may instead configure its own S3-compatible storage such as S3, R2 or MinIO.

Device Agent

The Device Agent remains outbound-only: it polls the private Team Host, leases work, talks to the local Blender bridge, uploads results and waits for review.

The recommended enrollment path is now a one-time pairing code:

nexora-forge setup --mode join-team \
  --server http://TEAM-HOST:3000 \
  --code NXR-ABCD-EFGH-JKLM

That command stores the Device Agent and member credentials locally. After the Blender extension is configured:

nexora-forge start

The Device Agent:

1. reads local Blender/bridge capabilities;

2. polls the private control plane for an atomic lease;

3. maintains lease heartbeat;

4. executes the structured plan locally;

5. saves a reproducible .blend checkpoint;

6. renders a review preview;

7. uploads preview/Blend/exports to object storage;

8. submits the job to human review.

It never opens a public inbound workstation port.

See device_agent/README.md.

Cloud API workflow

Configuration

The complete environment template is available in .env.example.

# safe | standard | unrestricted
NEXORA_PERMISSION_PROFILE=standard

# Raw Blender Python requires unrestricted + this explicit switch.
NEXORA_ALLOW_PYTHON_EXEC=false

# Cloud artifact upload limit.
NEXORA_MAX_ARTIFACT_BYTES=104857600

# Default Device Agent lease.
NEXORA_JOB_LEASE_SECONDS=900

I keep raw Blender Python disabled by default, and the Cloud structured-job pipeline never accepts python.execute.

Repository structure

.
├── apps/web/                   # Next.js Cloud/control-center UI + Cloud APIs
├── blender_extension/         # Blender extension and localhost bridge
├── device_agent/              # outbound Cloud → local Blender worker
├── deploy/
│   ├── cloudflare/            # Cloudflare Tunnel examples
│   └── postgres/              # Cloud schema/migrations
├── docs/                      # architecture, security and deployment guides
├── examples/                  # OpenAI Responses API example
├── scripts/                   # bootstrap and tunnel launchers
├── src/nexora_forge_mcp/      # Python MCP gateway
└── tests/                     # gateway/security/config tests

Security model

Nexora Forge can modify Blender scenes and files. In unrestricted mode it can also execute Python with the workstation user's permissions, so I treat this project like remote developer access rather than a harmless visualization plugin.

For production I recommend:

1. Keep the Blender bridge on 127.0.0.1.

2. Use different secrets for the public MCP gateway, Cloud API and Blender bridge.

3. Use OAuth for public MCP deployments.

4. Store Device Agent tokens in an OS secret store or protected service environment.

5. Use PostgreSQL with encrypted transport and least-privilege credentials.

6. Use private object storage buckets.

7. Keep raw Python disabled unless it is explicitly needed.

8. Rotate secrets after accidental disclosure.

9. Keep Forge Cloud on a trusted local/private network unless you deliberately add your own secure remote-access layer.

See docs/SECURITY.md.

Local-first scope

I am keeping Nexora Forge focused on local and privately self-hosted use.

The MCP gateway, Blender bridge, Forge Cloud control plane, Device Agent, asset locking, versioning, storage, previews, multi-agent orchestration and human approval pipeline are designed to run under the control of the user or team operating the Blender workstations.

I am not treating account subscriptions, public billing, hosted user acquisition or a managed multi-tenant service as part of the current project scope.

For AI provider credentials, local/private installations can use server-side environment variables. The existing secret_ref field remains useful for installations that choose to connect their own private secret manager, but Nexora Forge does not require a hosted vault service to operate.

Documentation

• Installer & local setup\n- Architecture

• Security

• Tool catalog

• Forge Cloud

• Multi-agent production

• Production pipeline

• OpenAI compatibility

• Secure MCP Tunnel

• OAuth

• Remote access

• Public distribution

Contributing

Issues and pull requests are welcome.

When contributing, please keep changes scoped, use clear commit messages, preserve the local-only Blender trust boundary and make sure CI remains green.

For new Blender operations, I prefer typed/structured tools over raw Python whenever possible.

Credits & contact

Owner / Maintainer: Ghost Developer
Source: GitHub
Email: ghostnexora@gmail.com
Telegram: @Gh0stDeveloper

License

I release Nexora Forge under the MIT License.

Nexora Forge — AI-native 3D production for Blender.