Altegio Pro MCP
No description available
Ask AI about Altegio Pro MCP
Powered by Claude Β· Grounded in docs
I know everything about Altegio Pro MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Altegio.Pro MCP Server
Official MCP server by Altegio organization
MCP server for Altegio.Pro business management API - B2B integration for salon/spa owners and administrators.
Target users: Business owners managing their Altegio companies
Authentication: All operations require user login (obtained via altegio_login)
Focus: Administrative B2B operations only (no public booking features)
Features
- 33 MCP tools including 10 onboarding wizard tools for first-time setup
- CRUD operations for staff, services, bookings, schedules, and positions management
- Conversational onboarding with bulk CSV/JSON import and checkpoint/resume
- Dual transport: stdio for Claude Desktop, HTTP for cloud deployments
- TypeScript with full type safety and comprehensive tests (157 passing)
- Auto-deploy CI/CD via VM cron (git pull + docker compose rebuild every 2 min)
- Rate limiting and retry logic with exponential backoff
- Secure credential storage in
~/.altegio-mcp/
Available Tools
33 tools organized by category for complete business management:
π Authentication
altegio_login- Authenticate with email/passwordaltegio_logout- Clear stored credentials
π’ Company Management
list_companies- Get managed companies (requires auth)
π₯ Staff Management
get_staff- View employees with admin detailscreate_staff- Add new employeeupdate_staff- Modify employee detailsdelete_staff- Remove employee
π Positions Management
get_positions- List company positions/rolescreate_position- Create new position (Manager, Stylist, etc.)update_position- Modify position detailsdelete_position- Remove position
ποΈ Services Management
get_services- View all services with configurationget_service_categories- View service categoriescreate_service- Add new serviceupdate_service- Modify service details
π Schedule Management
get_schedule- View employee work schedulescreate_schedule- Set employee work hoursupdate_schedule- Modify work scheduledelete_schedule- Remove schedule entry
π Bookings Management
get_bookings- View appointmentscreate_booking- Create client appointmentupdate_booking- Modify existing appointmentdelete_booking- Cancel appointment
π Onboarding Wizard
Conversational first-time setup assistant:
onboarding_start- Initialize setup sessiononboarding_resume- Resume interrupted setuponboarding_status- Check progressonboarding_add_categories- Bulk create service categoriesonboarding_add_staff_batch- Bulk import staff (CSV/JSON)onboarding_add_services_batch- Bulk import services (CSV/JSON)onboarding_import_clients- Import client databaseonboarding_create_test_bookings- Generate sample dataonboarding_preview_data- Validate before importonboarding_rollback_phase- Undo specific phase
Note: Services DELETE operation is not available in Altegio API. All write operations require user authentication via altegio_login. See Onboarding Guide for first-time setup workflows.
Quick Start
Prerequisites
- Node.js >= 18
- Altegio Partner Token from developer.alteg.io
Installation
git clone https://github.com/altegio/altegio-pro-mcp.git
cd altegio-mcp
npm install
cp .env.example .env
# Edit .env and add ALTEGIO_API_TOKEN
npm run build
Claude Desktop Setup
- Build the server:
npm run build - Add to
~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"altegio-pro": {
"command": "node",
"args": ["/absolute/path/to/altegio-mcp/dist/index.js"],
"env": {
"ALTEGIO_API_TOKEN": "your_partner_token"
}
}
}
}
- Restart Claude Desktop
See CLAUDE_DESKTOP_SETUP.md for detailed setup.
Onboarding Wizard
New in v2.0: Conversational assistant for first-time platform setup. Import staff, services, and clients through natural language or bulk CSV upload.
Quick Onboarding Flow
// 1. Login and start
altegio_login({ email: "owner@salon.com", password: "..." })
onboarding_start({ company_id: 123456 })
// 2. Create categories
onboarding_add_categories({
company_id: 123456,
categories: [
{ title: "Hair Services" },
{ title: "Nail Services" }
]
})
// 3. Import staff (CSV or JSON)
onboarding_add_staff_batch({
company_id: 123456,
staff_data: `name,specialization,phone
Alice Johnson,Senior Stylist,+1234567890
Bob Smith,Nail Technician,+1234567891`
})
// 4. Add services
onboarding_add_services_batch({
company_id: 123456,
services_data: [
{ title: "Haircut", price_min: 50, duration: 60 },
{ title: "Manicure", price_min: 30, duration: 45 }
]
})
// 5. Import clients
onboarding_import_clients({
company_id: 123456,
clients_csv: `name,phone,email
Sarah Miller,+1234560001,sarah@example.com
John Davis,+1234560002,john@example.com`
})
// 6. Generate test bookings
onboarding_create_test_bookings({ company_id: 123456, count: 5 })
// 7. Check progress
onboarding_status({ company_id: 123456 })
Key Features:
- Checkpoint/Resume: Automatically recovers from errors or interruptions
- Hybrid Input: Accept JSON arrays or CSV strings
- Preview Mode: Validate data before importing (
onboarding_preview_data) - Rollback: Undo specific phases (
onboarding_rollback_phase) - Progress Tracking: View completion status (
onboarding_status)
Time Savings: 5-10 minutes vs 30+ minutes manual setup
See docs/ONBOARDING_GUIDE.md for complete guide with CSV templates, error handling, and troubleshooting.
Local Docker Testing
# Create .env with your API token
echo "ALTEGIO_API_TOKEN=your_partner_token" > .env
# Start with Docker Compose (recommended)
docker compose -f docker-compose.local.yml up --build -d
# Health check
curl http://localhost:8080/health
# View logs
docker compose -f docker-compose.local.yml logs -f
# Stop
docker compose -f docker-compose.local.yml down
Or run standalone:
docker build -t altegio-mcp:local .
docker run --rm -p 8080:8080 --env-file .env -e PORT=8080 altegio-mcp:local
The MCP endpoint is available at http://localhost:8080/mcp (Streamable HTTP transport). See TESTING.md for the full MCP protocol testing guide.
Production Deployment
Automatic deployment to mcp-servers VM on PR merge to main. A cron job pulls latest main every 2 minutes and rebuilds if changed.
Public endpoint: https://mcp.alteg.io/pro/mcp
See CI-CD.md for details.
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
ALTEGIO_API_TOKEN | Yes | - | Partner API token |
ALTEGIO_API_BASE | No | https://api.alteg.io/api/v1 | API base URL |
LOG_LEVEL | No | info | debug|info|warn|error |
NODE_ENV | No | development | development|production |
RATE_LIMIT_REQUESTS | No | 200 | Max requests per minute |
Development
npm install # Install dependencies
npm run dev # Dev mode with hot reload
npm run build # Build TypeScript
npm test # Run tests
npm run test:watch # Watch mode
npm run lint # Check code style
Project Structure
src/
config/ # Configuration and validation
providers/ # API clients (altegio-client.ts)
tools/ # MCP tool handlers & registry
types/ # TypeScript interfaces
utils/ # Logging, errors, helpers
__tests__/ # Jest unit tests
index.ts # stdio server entry
http-server.ts # HTTP server entry
server.ts # Shared MCP server setup
Testing
- 157 tests (23 suites) covering authentication, all tools, error handling, pagination
- Jest for unit tests with mocked API responses
- Test isolation with temporary credentials directory
- Run:
npm testornpm run test:coverage - See TESTING.md for local Docker and MCP protocol testing
Integrations
- Claude Desktop: Native stdio transport (recommended)
- Other MCP Clients: Streamable HTTP transport via Cloud Run URL (MCP spec 2025-11-25 with tool annotations and structured output)
API Reference
Base URL: https://api.alteg.io/api/v1
Documentation: developer.alteg.io/api
Authentication:
- Partner token:
Authorization: Bearer {token} - User token:
User-Token: {token}(obtained viaaltegio_login)
Contributing
Contributions welcome! See CONTRIBUTING.md for:
- Development setup
- Coding standards (TypeScript, Prettier, ESLint)
- Testing guidelines
- Commit conventions
Quick contribution flow:
- Fork and create feature branch
- Add tests for new features
- Ensure
npm testandnpm run lintpass - Submit PR with clear description
License
MIT License - see LICENSE file
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Altegio API: support.alteg.io
Acknowledgments
Built with Model Context Protocol by Anthropic and Altegio API for salon/spa management.
