Endor Labs Setup Wizard

Guide the user from zero to scanning in 5 minutes. The MCP server runs via npx using the published endorctl npm package - no binary installation required.

Step 1: Check Prerequisites

1.1 Check if Node.js is installed

Node.js v18+ is required to run the MCP server via npx.

node --version

If not installed, provide installation instructions:

# macOS (Homebrew)
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20

1.2 Verify npx is available

npx --version

npx comes bundled with Node.js. If missing, run npm install -g npx.

1.3 Quick test of endorctl via npx

npx -y endorctl --version

This downloads and runs endorctl without installing it globally. The -y flag auto-confirms the download.

Step 2: Configure the MCP Server

2.1 Check if MCP server is already configured

Look for endor-cli-tools in the project's .claude/settings.json.

2.2 Choose Authentication Workflow

Ask the user which workflow fits their use case:

These are mutually exclusive. Using both simultaneously causes an auth error loop. If the user is unsure, recommend Local Development — it's simpler and covers most use cases.

2.3 Check for conflicting auth sources

Before proceeding, check for conflicts:

test -f ~/.endorctl/config.yaml && echo "config.yaml exists"

• If config.yaml exists and user chose Multi-Namespace: warn that it must be removed (rm -rf ~/.endorctl) to avoid conflicts
• If config.yaml does not exist and user chose Local Development: good — endorctl init will create it in Step 3

2.4 Create settings.json

Create or update .claude/settings.json in the project root. Use the template matching the chosen workflow:

Local Development (no auth env vars — auth comes from config.yaml):

{
  "mcpServers": {
    "endor-cli-tools": {
      "command": "npx",
      "args": [
        "-y",
        "endorctl",
        "ai-tools",
        "mcp-server"
      ]
    }
  }
}

Multi-Namespace (auth via env vars — no config.yaml):

{
  "mcpServers": {
    "endor-cli-tools": {
      "command": "npx",
      "args": [
        "-y",
        "endorctl",
        "ai-tools",
        "mcp-server"
      ],
      "env": {
        "ENDOR_MCP_SERVER_AUTH_MODE": "google",
        "ENDOR_API": "https://api.endorlabs.com",
        "ENDOR_NAMESPACE": "demo-trial"
      }
    }
  }
}

2.5 Important: Restart Required

Tell the user: You must restart Claude Code after creating or modifying settings.json for the MCP server to become available.

Step 3: Authenticate

Local Development workflow

1. Ask the user for their auth mode (google, github, api-key) and namespace
2. Run endorctl init to generate ~/.endorctl/config.yaml:

npx -y endorctl init --auth-mode=<MODE>

3. The config.yaml will store the API key and namespace. The MCP server reads it automatically — no env vars needed.

Multi-Namespace workflow

1. Ask the user which authentication provider they use:

2. Update the ENDOR_MCP_SERVER_AUTH_MODE in settings.json accordingly.
3. On first MCP tool call, the server will automatically open a browser window for authentication. The token is cached for 1 hour.

For CI/CD or headless environments

Instruct the user to set these environment variables themselves (never ask them to paste credentials into chat):

export ENDOR_API_CREDENTIALS_KEY=<your-api-key>
export ENDOR_API_CREDENTIALS_SECRET=<your-api-secret>

Or use a pre-existing token:

export ENDOR_TOKEN=<your-token>

Step 4: Configure Namespace

Local Development workflow

The namespace was configured during endorctl init in Step 3.

Never print ~/.endorctl/config.yaml in Bash or chat — it contains live API credentials. Tool transcripts log stdout, so cat, grep across the file, or grep -v '…' “redaction” still leaks values (e.g. ENDOR_API_CREDENTIALS_KEY / SECRET are not reliably stripped).

Safe verification:

• File exists: test -f ~/.endorctl/config.yaml && echo "config.yaml present"
• Namespace: ask the user to confirm it matches app.endorlabs.com (top-left). Do not dump YAML to verify.

If the namespace is wrong, re-run npx -y endorctl init.

Multi-Namespace workflow

Replace "demo-trial" with the user's actual namespace in the ENDOR_NAMESPACE field of settings.json. The namespace is their Endor Labs organization name, found at app.endorlabs.com in the top-left corner.

For new users without an account

Direct them to:

• Sign up at endorlabs.com (free tier available)
• Or run /endor-demo to try with simulated data

Step 5: Verify Setup

After restarting Claude Code, try using one of the MCP tools to verify the connection:

Use the check_dependency_for_vulnerabilities MCP tool with a known package:

• ecosystem: npm
• dependency_name: lodash
• version: 4.17.20

If this returns vulnerability data, the setup is working.

If it opens a browser for authentication, that's expected on first use. Complete the login flow.

Step 6: Success

Congratulate the user and provide next steps:

## Setup Complete!

Your Endor Labs MCP server is configured and ready. Here's what to try:

### First Steps
1. `/endor-scan` - Scan your current project for security issues
2. `/endor-check express 4.17.1` - Check a dependency for vulnerabilities
3. `/endor-help` - See all available commands

### Daily Workflow
- Run `/endor-scan` regularly during development
- Use `/endor-check` when adding new dependencies
- Run `/endor-review` before creating pull requests

### Learn More
- `/endor-demo` - Interactive demo with sample data
- `/endor-help` - Full command reference

Troubleshooting

Available MCP Tools After Setup

Once configured, these tools are available to Claude Code: