Endor

Setup and Configuration

Starting the MCP Server

# Install Endor CLI
npm install -g @endorhq/cli

# Start MCP server (stdio mode)
endor mcp

# Or with network access enabled
endor mcp --allow-net

Connecting from AI Clients

The MCP server communicates via stdio transport. Configure your AI client to connect to the Endor MCP server:

{
  "mcpServers": {
    "endor": {
      "command": "endor",
      "args": ["mcp", "--allow-net"]
    }
  }
}

Available Tools

Core Management Tools

list_available_services

Returns available service types that can be provisioned.

Response:

["alpine", "mariadb", "memcached", "postgres", "redis", "valkey"]

list_running_services

Lists all currently running service instances.

Response:

["postgres-server-abc123", "redis-server-def456"]

run_command_in_service

Execute shell commands inside running service VMs.

Parameters:

• serverId (string): Service instance identifier
• command (string): Shell command to execute
• timeout (number, optional): Timeout in seconds (max 600)

Example:

{
  "serverId": "postgres-server-abc123",
  "command": "psql -c 'SELECT version();'",
  "timeout": 30
}

Response:

{
  "serverId": "postgres-server-abc123",
  "command": "psql -c 'SELECT version();'",
  "stdout": "PostgreSQL 15.3 on x86_64-pc-linux-gnu...",
  "stderr": "",
  "returnCode": 0,
  "success": true
}

Service-Specific Tools

Each service type provides three main tools:

run_{service}_service

Provisions a new service instance.

Parameters:

• serverId (string, optional): Custom server ID
• hostPort (number, optional): Preferred host port

Available Services:

• run_postgres_service - PostgreSQL database
• run_mariadb_service - MariaDB database
• run_redis_service - Redis cache
• run_valkey_service - Valkey cache
• run_memcached_service - Memcached cache
• run_alpine_service - Alpine Linux environment

stop_{service}_service

Stops and removes a service instance.

Parameters:

• serverId (string): Service instance to stop

get_{service}_connection

Retrieves connection details for a service.

Response:

{
  "serverId": "postgres-server-abc123",
  "host": "localhost",
  "port": 5432,
  "username": "postgres",
  "password": "<passwordless>",
  "status": "running"
}

Usage Examples

Example 1: Setting Up a PostgreSQL Database

// 1. Start a PostgreSQL service
const postgresResult = await mcp.callTool("run_postgres_service", {
  serverId: "my-postgres-db"
});

// 2. Get connection details
const connectionInfo = await mcp.callTool("get_postgres_service_details", {
  serverId: "my-postgres-db"
});

// 3. Create a database and table
await mcp.callTool("run_command_in_service", {
  serverId: "my-postgres-db",
  command: "psql -c 'CREATE DATABASE testapp;'"
});

await mcp.callTool("run_command_in_service", {
  serverId: "my-postgres-db", 
  command: "psql testapp -c 'CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(50));'"
});

// 4. Insert sample data
await mcp.callTool("run_command_in_service", {
  serverId: "my-postgres-db",
  command: "psql testapp -c \"INSERT INTO users (name) VALUES ('Alice'), ('Bob');\""
});

// 5. Query the data
const queryResult = await mcp.callTool("run_command_in_service", {
  serverId: "my-postgres-db",
  command: "psql testapp -c 'SELECT * FROM users;'"
});

Example 2: Multi-Service Setup (Database + Cache)

// Start PostgreSQL and Redis services
await mcp.callTool("run_postgres_service", { serverId: "app-db" });
await mcp.callTool("run_redis_service", { serverId: "app-cache" });

// Get connection details for both
const dbConnection = await mcp.callTool("get_postgres_service_details", {
  serverId: "app-db"
});
const cacheConnection = await mcp.callTool("get_redis_service_details", {
  serverId: "app-cache"
});

// Set up database schema
await mcp.callTool("run_command_in_service", {
  serverId: "app-db",
  command: "psql -c 'CREATE DATABASE myapp;'"
});

// Test Redis cache
await mcp.callTool("run_command_in_service", {
  serverId: "app-cache", 
  command: "redis-cli SET greeting 'Hello, World!'"
});

const cacheValue = await mcp.callTool("run_command_in_service", {
  serverId: "app-cache",
  command: "redis-cli GET greeting"
});

Example 3: Development Environment with Alpine Linux

// Start Alpine Linux environment
await mcp.callTool("run_alpine_service", { 
  serverId: "dev-env" 
});

// Install development tools
await mcp.callTool("run_command_in_service", {
  serverId: "dev-env",
  command: "apk add --no-cache git nodejs npm python3"
});

// Clone and set up a project
await mcp.callTool("run_command_in_service", {
  serverId: "dev-env",
  command: "git clone https://github.com/example/project.git /workspace"
});

await mcp.callTool("run_command_in_service", {
  serverId: "dev-env",
  command: "cd /workspace && npm install"
});

Service Connection Details

PostgreSQL

• Default Port: 5432
• Username: postgres
• Password: (none)
• SSH Access: Port 2222, user 'root'

MariaDB

• Default Port: 3306
• Username: root
• Password: (none)
• SSH Access: Port 2222, user 'root'

Redis

• Default Port: 6379
• No authentication required

Valkey

• Default Port: 6379
• No authentication required

Memcached

• Default Port: 11211
• No authentication required

Best Practices

1. Service Naming: Use descriptive service IDs (e.g., "user-api-db", "session-cache")
2. Resource Cleanup: Always stop services when done using stop_{service}_service
3. Command Timeouts: Set appropriate timeouts for long-running commands
4. Error Handling: Check command return codes and stderr for errors
5. Port Conflicts: Let Endor assign ports automatically for better reliability