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