Altegio

You run an MCP server that exposes Altegio API records, clients, services, staff, and schedules through an AI-assisted interface. It provides a flexible, multi-transport MCP setup you can connect to from local tooling or cloud environments, enabling streamlined management of your Altengio data.

How to use

You interact with the MCP server through an MCP client or editor that communicates via standard MCP endpoints. You can perform full CRUD operations on records and clients, search and filter data intelligently, and navigate scheduling, services, and staff data through a unified, programmable interface. Use the HTTP transport for cloud or remote deployments and the stdio transport for local tools that connect directly to the process.

How to install

Prerequisites you need before installation are a Bun runtime (version 1.x or higher) or Docker, and partner and user tokens for Altegio API.

# Bun installation flow (local)
git clone https://github.com/moro3k/mcp-altegio.git
cd mcp-altegio
bun install

# Docker build flow (local Docker daemon)
git clone https://github.com/moro3k/mcp-altegio.git
cd mcp-altegio
docker build -t mcp-altegio .

Configuration

You must provide three Altegio credentials to run the MCP server securely. Set these environment variables in your deployment environment or through your MCP host configuration.

ALTEGIO_TOKEN=your_partner_token
ALTEGIO_USER_TOKEN=your_user_token
ALTEGIO_COMPANY_ID=your_company_id

Connecting via HTTP transport (Streamable HTTP)

For cloud deployments or when using the Streamable HTTP transport, the MCP server exposes an HTTP endpoint at port 3000 by default. You can connect to it with an MCP client by pointing to the /mcp path.

# Local run example (HTTP)
bun run start:http

# Or Docker run example
docker run --rm -p 3000:3000 \
  -e ALTEGIO_TOKEN=your_token \
  -e ALTEGIO_USER_TOKEN=your_user_token \
  -e ALTEGIO_COMPANY_ID=12345 \
  mcp-altegio bun run src/http.ts

Endpoint to connect via MCP URL:

http://localhost:3000/mcp

Stdio transport (local) and Settings

You can run a local stdio transport to connect with Claude Desktop, Claude Code, Cursor, or VS Code Copilot. Use Bun to start the server process and pass the full path to the MCP entry script.

# Bun-based stdio start (local)
bun run /full/path/to/mcp-altegio/src/index.ts

Where /full/path/to/mcp-altegio/src/index.ts is the absolute path to the MCP entry script. You may also run via Docker if you prefer containerized stdio transport, but ensure you expose and pass the required Altegio tokens as environment variables.

## Tools and endpoints you can use

The MCP server exposes a set of 18 tools to manage appointments, clients, services, staff, scheduling, and finances. Each tool provides specific actions to create, read, update, delete, or search data.

## Quick start examples

Show today’s appointments, search for a client by phone, book a Thai massage, and view available slots for a staff member across a week.

## Development and tests

Develop locally by installing dependencies, starting the server, and running tests to validate unit, API client, and integration behavior.

## Notes and advanced topics

The server supports multiple transport methods and can be connected with both local and cloud workflows. It includes a comprehensive test suite and a modular architecture to extend tools or add new workflows. Ensure your tokens are kept secure and rotated as needed.

## Security and tokens

Only use valid Altegio partner and user tokens. Do not expose tokens in client-side code or public repositories. Rotate tokens periodically and apply principle of least privilege for access.

## Troubleshooting

If the MCP server fails to start, verify that Bun is installed, environment variables are set, and the correct entry script path is provided. Check container logs or console output for token or company ID validation errors.

## Available tools

### get\_records

Retrieve records within a date range with filters for master and client

### get\_records\_by\_client

Fetch all records associated with a specific client

### get\_records\_by\_visit

Find records linked to an external visit via api\_id

### create\_record

Create a new record with full parameter configuration

### book\_service

Quickly book a service and attach it to a visit

### update\_record

Modify an existing record's details or timing

### delete\_record

Remove a record from the system

### search\_clients

Search clients by name, phone, or email with automatic type inference

### get\_client

Retrieve a client's profile by ID

### create\_client

Create a new client entry

### update\_client

Update client information

### get\_services

List available services, filterable by master or category

### get\_service\_categories

List service categories

### get\_staff

List staff members (excluding terminated)

### get\_staff\_member

Get details for a specific staff member

### get\_available\_times

Get free time slots for a given date

### get\_available\_dates

Get working days for a master

### get\_transactions

Retrieve financial transactions for a period