Sun Lab Nbb Ataraxis Video MCP Environment Setup

MCP environment setup

Diagnoses and resolves ataraxis-video-system MCP server connectivity and environment configuration issues.

Scope

Covers:

• Verifying the ataraxis-video-system MCP server is reachable and functional
• Diagnosing why the axvs command is unavailable
• Checking Python version compatibility
• Validating ataraxis-video-system package installation and dependencies
• Environment-specific guidance for conda, pip, and uv workflows

Does not cover:

• MCP tool usage for camera discovery, configuration, and hardware interaction (see /camera-setup)
• MCP tool usage for log data processing (see /log-processing, /log-processing-results)
• ataraxis-video-system package development or contribution workflows

Architecture

ataraxis-video-system provides a single MCP server accessed through the axvs CLI entry point defined in pyproject.toml:

[project.scripts]
axvs = "ataraxis_video_system.interfaces.cli:axvs_cli"

The server accepts a --transport option (defaults to stdio). The plugin manifest .claude-plugin/plugin.json configures the Claude assistant to launch the server automatically via its mcpServers block:

{
  "mcpServers": {
    "ataraxis-video-system": {
      "command": "axvs",
      "args": ["mcp"]
    }
  }
}

The axvs command must be on PATH when the Claude assistant starts. This means the Python environment where ataraxis-video-system is installed must be active before launching the assistant.

Dual-distribution model

The ataraxis video plugin's Claude integration is split across two distribution channels:

Installing the plugin alone registers the MCP server and makes skills available, but the server will fail to start because the axvs CLI command is not present. The pip package must also be installed in the active Python environment for the MCP server to function.

This is the most common cause of MCP failures after initial setup: the plugin is installed but the pip package is not, or the pip package is installed in a different Python environment than the one active when the Claude assistant launches.

Diagnostic workflow

You MUST follow these steps in order when MCP tools are unavailable or the server fails to start.

Step 1: Check MCP server status

Use the /mcp slash command or inspect available tools to determine whether the ataraxis-video-system MCP server is connected. If connected, the issue is not environmental — investigate tool-specific errors instead.

Step 2: Verify command availability

which axvs

If the command is not found, proceed to step 3. If found, skip to step 4.

Step 3: Identify the environment type and resolve

Run these commands to determine the user's environment setup:

echo "CONDA_PREFIX: ${CONDA_PREFIX:-not set}"
echo "VIRTUAL_ENV: ${VIRTUAL_ENV:-not set}"
python --version
pip list 2>/dev/null | grep ataraxis-video-system

Based on the output, guide the user through the appropriate resolution:

Conda environment (CONDA_PREFIX is set but ataraxis-video-system is missing):

The user has an active conda environment but ataraxis-video-system is not installed in it. Instruct the user to install ataraxis-video-system into the active environment:

pip install ataraxis-video-system

Or if using uv within conda:

uv pip install ataraxis-video-system

Conda environment not activated (CONDA_PREFIX is not set, but conda is available):

The user needs to activate their environment before launching the Claude assistant. Instruct the user to exit the assistant and run:

mamba activate <environment-name>
claude

You MUST explain that the Claude assistant inherits the shell environment at launch time. Activating a conda environment after the assistant has started does not make the axvs command available to MCP server subprocesses.

Virtual environment (VIRTUAL_ENV is set but ataraxis-video-system is missing):

pip install ataraxis-video-system

No environment active (both CONDA_PREFIX and VIRTUAL_ENV are unset):

The user is running in the system Python. If ataraxis-video-system is installed globally, which axvs would have succeeded. Instruct the user to either activate their environment or install ataraxis-video-system into an accessible location.

Step 4: Verify Python version compatibility

python --version

ataraxis-video-system requires Python >=3.12,<3.15. If the Python version does not match, inform the user that their environment has an incompatible Python version, and they need to create or activate an environment with a compatible version.

Step 5: Verify package integrity

axvs --help

If the command fails with an import error, a dependency is missing or broken. Run:

pip check ataraxis-video-system 2>&1 | head -20

Report any missing or incompatible dependencies to the user.

Step 6: Restart the MCP server

After the user resolves the environment issue, they must restart the Claude assistant for the MCP server to pick up the changes. The ataraxis video plugin will automatically configure the server on the next session.

Common issues and resolutions

Related skills

Proactive behavior

You should proactively invoke this skill when:

• A session begins and MCP tools from the ataraxis-video-system server are expected but unavailable
• Any ataraxis-video-system MCP tool call fails with a connection or server error
• The user mentions issues with MCP server connectivity or environment setup

Verification checklist

MCP Environment Setup:
- [ ] Checked MCP server connection status (ataraxis-video-system)
- [ ] Verified 'axvs' command is on PATH (which axvs)
- [ ] Confirmed Python version matches >=3.12,<3.15
- [ ] Identified environment type (conda, venv, system)
- [ ] Provided environment-specific resolution steps
- [ ] Informed user that the Claude assistant must be restarted after environment changes

Source: Sun-Lab-NBB/ataraxis — distributed by TomeVault.