dcc-mcp-fpt

Agent workflow

AI agents should use the shared gateway through dcc-mcp-cli; IDE users may continue to use the MCP endpoint. Prefer typed skills and tools over raw scripts.

Install or update the CLI

dcc-mcp-cli is the preferred control path for every shell-capable agent. If it is missing, ask the user before installing the latest official release:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.ps1 | iex"

Keep an official build current through the release manifest:

dcc-mcp-cli update check
dcc-mcp-cli update apply

update apply downloads and stages the latest CLI for the next launch. It does not update a running dcc-mcp-server; update that server in its own environment.

dcc-mcp-cli dcc-types
dcc-mcp-cli list
dcc-mcp-cli search --query "<task>" --dcc-type shotgrid
dcc-mcp-cli describe <tool-slug>
dcc-mcp-cli call <tool-slug> --json '{"key":"value"}'

dcc-types reports release-catalog support; list reports live sessions. If a tool belongs to an inactive progressive skill, call dcc-mcp-cli load-skill <skill-name> --dcc-type shotgrid before retrying. For post-task improvement, attach a stable session id with --meta-json, query dcc-mcp-cli stats --range 24h --session-id <task-id>, then pass the bounded evidence to the review_skill_improvement prompt from dcc-mcp-skills-creator.

ShotGrid (Flow Production Tracking) adapter for the DCC-MCP ecosystem.

Bridges AI assistants (Claude, Cursor, VS Code Copilot) to ShotGrid data through typed, progressively-loaded MCP tools built on dcc-mcp-core.

This is a fresh re-implementation of the shotgrid-mcp-server using the dcc-mcp framework — providing the same ShotGrid integration surface with gateway routing, skill-based progressive loading, and multi-DCC observability built in.

Related MCP server: shotgrid-mcp-server

Why Use It

Quick Start

Install

pip install dcc-mcp-fpt

Or with uv:

uv pip install dcc-mcp-fpt

Configure

Set your ShotGrid credentials:

export SHOTGRID_URL="https://mysite.shotgrid.autodesk.com"
export SHOTGRID_SCRIPT_NAME="my_script_name"
export SHOTGRID_SCRIPT_KEY="my_script_key"
export SHOTGRID_PROJECT="my_project_code"
export SHOTGRID_PERMISSION_LEVEL="read"

Run Locally

The shortest local path is:

uvx dcc-mcp-fpt

By default the adapter binds an OS-assigned instance port and enables the stable local gateway at http://127.0.0.1:9765/mcp. Use dcc-mcp-cli list to inspect the direct endpoint. If a healthy gateway is already running on that port, this FPT adapter registers into it; otherwise the core gateway election path can own the gateway port for the local session.

Use standalone mode only when you do not want gateway registration:

uvx dcc-mcp-fpt --no-gateway
# Same as: uvx dcc-mcp-fpt --gateway-port 0

Development checkout:

python -m dcc_mcp_fpt
just serve-gateway
just serve-standalone

ASGI mode for uvicorn/gunicorn remains available:

uvicorn dcc_mcp_fpt.asgi:app --host 0.0.0.0 --port 8000

IDE MCP Config

For IDEs that support Streamable HTTP MCP, point the IDE at the gateway URL:

{
  "mcpServers": {
    "shotgrid": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}

If your IDE only supports stdio MCP, use uvx directly:

{
  "mcpServers": {
    "shotgrid": {
      "command": "uvx",
      "args": ["dcc-mcp-fpt", "stdio", "--no-gateway"],
      "env": {
        "SHOTGRID_URL": "https://mysite.shotgrid.autodesk.com",
        "SHOTGRID_SCRIPT_NAME": "my_script_name",
        "SHOTGRID_SCRIPT_KEY": "my_script_key",
        "SHOTGRID_PROJECT": "my_project_code",
        "SHOTGRID_PERMISSION_LEVEL": "read"
      }
    }
  }
}

mcpcall

After uvx dcc-mcp-fpt is running, smoke-test through the gateway:

mcpcall doctor --url http://127.0.0.1:9765/mcp --json
mcpcall list --url http://127.0.0.1:9765/mcp --json
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-discovery__check_connection
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-discovery__get_server_info

You can also import the same mcpServers JSON used by your IDE:

mcpcall config import --from ./mcp.json --output ./mcpcall.json
mcpcall list --config ./mcpcall.json --server shotgrid --json

Tool Surface

Bootstrap (eager-loaded)

Scene (loaded on demand)

Authoring

Pipeline

Architecture

AI Agent (Claude, Cursor, Copilot)
        │
        │ MCP Protocol (stdio / HTTP / ASGI)
        ▼
┌───────────────────────────────┐
│     ShotGridMcpServer         │
│   (DccServerBase adapter)     │
│                               │
│  ┌─────────────────────────┐  │
│  │   Skill Catalog          │  │
│  │  (progressive loading)   │  │
│  └───────────┬─────────────┘  │
│              │                │
│  ┌───────────▼─────────────┐  │
│  │   HostExecutionBridge    │  │
│  │   → ShotGridClient       │  │
│  └───────────┬─────────────┘  │
│              │                │
│  ┌───────────▼─────────────┐  │
│  │  ConnectionPool          │  │
│  │  SchemaCache             │  │
│  └───────────┬─────────────┘  │
└──────────────┼────────────────┘
               │
               │ shotgun_api3 (REST)
               ▼
     ┌─────────────────┐
     │  ShotGrid API    │
     │  (Autodesk FPT)  │
     └─────────────────┘

Configuration

Project Scoping and Permissions

CRUD and batch tools accept optional project, project_id, and project_scoped inputs. When a default project is configured, reads add a ShotGrid project filter, creates inject data.project when missing, and updates/deletes validate project ownership before mutating data.

Permission levels are intentionally simple:

Examples:

export SHOTGRID_PROJECT="my_project_code"
export SHOTGRID_PERMISSION_LEVEL="write"
export SHOTGRID_PROJECT_PERMISSIONS='{"my_project_code":"write","id:456":"read"}'

Gateway Integration

The adapter uses the same DccServerOptions.from_env(...) gateway contract as the Maya, Blender, Houdini, and 3ds Max adapters. When DCC_MCP_GATEWAY_PORT or --gateway-port is set to a positive value, the server publishes an FPT runtime entry with a safe display name, project-aware scene label, version, and gateway election diagnostics.

export SHOTGRID_PROJECT="my_project_code"
export DCC_MCP_GATEWAY_PORT=9765
export DCC_MCP_FPT_GATEWAY_DISPLAY_NAME="FPT my_project_code"

just serve-gateway

Use --gateway-port 0 or just serve-standalone for local standalone testing. The shotgrid-discovery__get_server_info tool includes a gateway diagnostics object so agents and CI can confirm whether this instance joined the gateway.

Request-Scoped Credentials

HTTP MCP clients do not inject mcp.json.env into an already-running Gateway. For shared Gateway deployments, keep ShotGrid secrets in adapter-side profiles and pass request context through MCP _meta. With core PIP-520, caller identity lives under _meta.agent_context, while credential and policy controls are bounded top-level _meta fields:

{
  "_meta": {
    "agent_context": {
      "requester_id": "hallong",
      "requester_type": "human"
    },
    "credential_profile": "sg-read-zombie",
    "permission_hint": "read",
    "project_scope": "my_project_code"
  }
}

Legacy clients that still send credential_profile, permission_hint, or project_scope inside _meta.agent_context remain supported as a fallback, but new agents should use the PIP-520 top-level _meta shape above.

Profiles can be supplied as JSON in DCC_MCP_FPT_CREDENTIAL_PROFILES or from a JSON file via DCC_MCP_FPT_CREDENTIAL_PROFILES_FILE:

{
  "sg-read-zombie": {
    "url": "https://mysite.shotgrid.autodesk.com",
    "script_name": "sg_read_bot",
    "script_key": "<secret stored outside chat>",
    "permission_level": "read",
    "read_only": true,
    "project": "my_project_code"
  }
}

permission_hint can only reduce the effective policy. It is merged with the env/profile policy by minimum permission, so an agent cannot turn a read profile into write/admin. Inline credentials are rejected unless DCC_MCP_ALLOW_INLINE_CREDENTIALS=1 is set for local development.

Agent Setup Skill

shotgrid-setup is eager-loaded so agents can bootstrap configuration without guessing repo conventions:

mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-setup__validate_runtime_config
mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-setup__generate_agent_config target=all

The generated config includes uvx dcc-mcp-fpt, HTTP/stdio IDE snippets, mcpcall commands, Docker examples, and custom skill path environment variables. Secret values are redacted by default.

Custom Skills

Point DCC_MCP_FPT_SKILL_PATHS at a skill package directory or a parent directory containing multiple skill package folders:

# Windows uses semicolon between multiple roots.
set DCC_MCP_FPT_SKILL_PATHS=C:\studio\fpt-skills;C:\show\fpt-skills

# Linux/macOS uses colon.
export DCC_MCP_FPT_SKILL_PATHS=/studio/fpt-skills:/show/fpt-skills

uvx dcc-mcp-fpt

Use DCC_MCP_SKILL_PATHS for shared cross-adapter skills. The gateway admin skill path registry is also picked up by dcc-mcp-core on startup/reload.

Container Deployment

Build and run locally:

docker build -t dcc-mcp-fpt .
docker run --rm \
  -p 9765:9765 \
  --env-file .env \
  dcc-mcp-fpt

Inject custom skills by mounting a directory to /skills; the image sets DCC_MCP_FPT_SKILL_PATHS=/skills by default:

docker run --rm \
  -p 9765:9765 \
  --env-file .env \
  -v /studio/fpt-skills:/skills:ro \
  dcc-mcp-fpt

Docker Compose (includes health check and graceful shutdown):

docker compose -f docker-compose.yml up -d

For per-user credential profiles, use the profiles overlay:

# 1. Create fpt-credential-profiles.json (see Per-User Access below)
# 2. Launch with profiles compose file
docker compose -f docker-compose.yml -f docker-compose.profiles.yml up -d

Health Check

The stable gateway exposes /health for container probes and platform monitoring:

curl http://localhost:9765/health
# {"status": "ok", "version": "dcc-mcp-fpt/0.1.2", "sg_configured": true}

• sg_configured: true means ShotGrid credentials are available.

• No secrets are exposed — the field is a boolean derived from the presence of SHOTGRID_URL.

• The endpoint works even when dcc-mcp-core is not installed.

Agent Platform Deployment

The adapter is designed to run on OpenClaw, Harness, and other MCP-compatible agent platforms. See deployment/OPENCLAW.md and deployment/HARNESS.md for platform-specific configuration guides.

Key platform features:

• Graceful shutdown: Handles SIGTERM for clean orchestrated stops.

• Health endpoint: /health for Kubernetes liveness/readiness probes.

• Stateless + profiles: Deploy one instance; select credentials per-request via _meta.

• Gateway registration: Optionally joins the dcc-mcp gateway for unified routing.

Per-User Access with whoami

The shotgrid-users skill provides a whoami tool that reports the effective ShotGrid identity without exposing secrets. Use it to confirm which credential profile and permission level is active:

mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-users__whoami

With a request-scoped profile:

mcpcall call --url http://127.0.0.1:9765/mcp shotgrid-users__whoami \
  --meta '{"credential_profile":"sg-read-zombie","project_scope":"demo"}'

The response includes script_name, url, permission_level, credential_profile, and credential_source — but never the api_key.

Development

git clone https://github.com/dcc-mcp/dcc-mcp-fpt.git
cd dcc-mcp-fpt

# Install with dev deps
uv pip install -e ".[dev]"

# Run tests
pytest --cov=src/dcc_mcp_fpt --cov-report=term

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

Local Live CRUD Smoke

Copy .env.example to .env, fill in local credentials, and keep the file untracked. The dry-run command verifies configuration and skips mutations:

just install-dev
just live-crud-smoke-dry

To run a real local create/find/update/delete cycle against the configured project, set an admin-capable policy for that project and run:

export SHOTGRID_PERMISSION_LEVEL="admin"
export SHOTGRID_LIVE_CRUD_CONFIRM=1
just live-crud-smoke

The smoke creates a temporary entity, updates it, and retires it on cleanup.

CI/CD

• CI runs Python 3.8-3.12 across Linux, Windows, and macOS.

• Lint, format check, bundled skill metadata lint, CLI smoke, package build, and Docker build are separate gates.

• Release uses release-please, builds wheel/sdist artifacts, publishes via PyPI Trusted Publishing, and attaches the dist files to the GitHub Release.

• Live ShotGrid Smoke is manual-only and uses GitHub Secrets; it defaults to dry-run behavior unless CRUD confirmation is enabled.

• E2E tests cover all 8 skill packages, server lifecycle, health endpoint, credential profile file loading, and permission policy resolution.

Requirements

• Python 3.8+

• dcc-mcp-core >= 0.18.2,<1.0.0

• shotgun_api3 >= 3.4.0

License

MIT — see LICENSE.

Related

• dcc-mcp-core — Core runtime and shared tooling

• shotgrid-mcp-server — Original FastMCP-based implementation

• dcc-mcp-maya — Maya adapter reference

• dcc-mcp-blender — Blender adapter reference