npm package: @girardmedia/altohost-mcp
Description: AltoHost MCP server — auto-discover account, apps, and platform services for AI-assisted builds
Author: AltoHost
Latest version: 1.4.0

# altohost-mcp

MCP (Model Context Protocol) server for the AltoHost real-time infrastructure platform. Allows AI assistants and MCP clients to auto-discover account details, app configuration, platform services, and connection credentials during project builds.

## What It Does

When connected to an MCP client (Claude Code, Bootspring MCP, etc.), this server provides:

- **Account discovery** — plan, billing status, app count
- **App configuration** — list/create apps, get API keys and connection credentials
- **Connection config** — ready-to-use env vars, SDK init code for client/server/React
- **Platform services** — status of all AltoHost services (WebSocket, Jobs, SSE, Cache, Email)
- **Plan limits** — current plan's resource limits and available features
- **Health checks** — API and WebSocket engine status

## Configuration

### Claude Code

Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "altohost": {
      "command": "npx",
      "args": ["@girardmedia/altohost-mcp"],
      "env": {
        "ALTOHOST_API_TOKEN": "alto_your_token_here"
      }
    }
  }
}
```

### Other MCP Clients

Any MCP-compatible client can connect using stdio transport:

```json
{
  "mcpServers": {
    "altohost": {
      "command": "npx",
      "args": ["@girardmedia/altohost-mcp"],
      "env": {
        "ALTOHOST_API_TOKEN": "alto_your_token_here"
      }
    }
  }
}
```

### Local Development

If running from the monorepo:

```json
{
  "mcpServers": {
    "altohost": {
      "command": "node",
      "args": ["./packages/altohost-mcp/dist/index.js"],
      "env": {
        "ALTOHOST_API_TOKEN": "alto_your_token_here"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ALTOHOST_API_TOKEN` | Yes | — | Bearer token (`alto_` prefixed) from your AltoHost dashboard |
| `ALTOHOST_API_URL` | No | `https://app.altohost.com` | Base URL for the AltoHost API |

## Available Tools

| Tool | Description |
|------|-------------|
| `get_account` | Get current account info — plan, email, app count, billing status |
| `list_apps` | List all apps with their config and API keys |
| `get_app` | Get detailed app config by ID, including connection credentials |
| `create_app` | Create a new app and return credentials |
| `get_connection_config` | Get ready-to-use connection config — env vars, SDK init code, WebSocket URL |
| `get_plan_limits` | Get current plan's limits and available features |
| `get_service_status` | Check which platform services are available and their status |
| `get_platform_services` | Detailed info about each service — integration instructions, env vars, SDK methods |
| `health_check` | Check AltoHost API health |

## Available Resources

| Resource URI | Description |
|-------------|-------------|
| `altohost://account` | Current account profile and plan |
| `altohost://services` | Available platform services and their status |
| `altohost://docs/quickstart` | Quick start guide |
| `altohost://docs/services` | Platform services overview |

## Platform Services

| Service | Status | Description |
|---------|--------|-------------|
| WebSocket Channels | Live | Real-time bidirectional communication with channels, presence, client events |
| Background Jobs | Live | Task automation, agent queues, document processing |
| SSE Streaming | Live | Server-sent events for AI token streaming, live feeds |
| Redis Caching | Live | Managed caching with TTL and key limits |
| Transactional Email | Live | Email delivery with templates and tracking |

## Building

```bash
cd packages/altohost-mcp
pnpm install
pnpm build
```

## License

MIT