coordinalo-mcp

<!-- TODO: Replace with actual Coordinalo logo -->
<p align="center">
  <img src="https://coordinalo.com/logo.png" alt="Coordinalo" width="200" />
</p>

<h1 align="center">Coordinalo MCP Server</h1>

<p align="center">
  Connect any AI agent to Coordinalo's scheduling platform via MCP
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@servicialo/mcp-server"><img src="https://img.shields.io/npm/v/@servicialo/mcp-server?label=%40servicialo%2Fmcp-server&color=blue" alt="npm version" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache 2.0 License" /></a>
  <a href="https://coordinalo.com"><img src="https://img.shields.io/badge/status-Production-brightgreen" alt="Status: Production" /></a>
</p>

---

**Coordinalo** is a booking and scheduling SaaS platform. This repository is the official documentation and integration guide for connecting AI agents to Coordinalo via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

> Coordinalo implements the **Servicialo** open protocol. Any Servicialo-compatible MCP client works out of the box. See [Built on Servicialo](#built-on-servicialo).

## Quick Connect

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "coordinalo": {
      "url": "https://coordinalo.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Org-Slug": "your-org-slug"
      }
    }
  }
}
```

See [examples/claude-desktop.json](./examples/claude-desktop.json) for a ready-to-paste config.

### Cursor IDE

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "coordinalo": {
      "url": "https://coordinalo.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Org-Slug": "your-org-slug"
      }
    }
  }
}
```

See [examples/cursor-mcp.json](./examples/cursor-mcp.json).

### Any MCP Client

Point your MCP client to:

```
Endpoint: https://coordinalo.com/api/mcp
Auth:     Authorization: Bearer <YOUR_API_KEY>
Header:   X-Org-Slug: <your-org-slug>
```

## Authentication

Every request requires:

| Header          | Value                      | Description                              |
| --------------- | -------------------------- | ---------------------------------------- |
| `Authorization` | `Bearer <API_KEY>`         | Your API key from coordinalo.com         |
| `X-Org-Slug`    | `your-org-slug`            | Your organization identifier             |

Get your API key at [coordinalo.com/settings/api](https://coordinalo.com/settings/api). See [docs/authentication.md](./docs/authentication.md) for full details.

## Tool Summary

| Tool                      | Description                                | Key Params                                           |
| ------------------------- | ------------------------------------------ | ---------------------------------------------------- |
| `availability_get_slots`  | Query free slots for a provider/service    | `orgSlug`, `providerId?`, `serviceId?`, `dateFrom`, `dateTo` |
| `booking_create`          | Create a new session/appointment           | `orgSlug`, `providerId`, `serviceId`, `clientId`, `scheduledAt` |
| `booking_list`            | List sessions with filters                 | `orgSlug`, `status?`, `providerId?`, `dateFrom?`, `dateTo?` |
| `booking_get`             | Get a single booking's details             | `orgSlug`, `sessionId`                               |
| `booking_reschedule`      | Move a booking to a new time               | `orgSlug`, `sessionId`, `newScheduledAt`, `confirm`  |
| `booking_cancel`          | Cancel a session                           | `orgSlug`, `sessionId`, `reason`, `confirm`          |
| `client_list`             | List organization clients                  | `orgSlug`, `search?`                                 |
| `client_get`              | Get client details                         | `orgSlug`, `clientId`                                |
| `client_create`           | Create a new client                        | `orgSlug`, `name`, `lastName`, `email?`, `phone?`    |
| `admin_list_providers`    | List active providers                      | `orgSlug`                                            |
| `service_list`            | List bookable services                     | `orgSlug`                                            |
| `report_dashboard`        | Get org summary metrics                    | `orgSlug`, `date?`                                   |

See [docs/tools.md](./docs/tools.md) for full parameter docs, response formats, and examples.

## Documentation

- **[Quickstart](./docs/quickstart.md)** — Connect and make your first booking in 5 minutes
- **[Tool Catalog](./docs/tools.md)** — Full reference for every available tool
- **[Authentication](./docs/authentication.md)** — API keys, org slugs, and auth flow
- **[Use Cases](./docs/use-cases.md)** — Real-world agent integration patterns

## Examples

- [`claude-desktop.json`](./examples/claude-desktop.json) — Claude Desktop MCP config
- [`cursor-mcp.json`](./examples/cursor-mcp.json) — Cursor IDE MCP config
- [`booking-agent.js`](./examples/booking-agent.js) — Node.js autonomous booking flow
- [`availability-check.py`](./examples/availability-check.py) — Python availability checker

## Built on Servicialo

Coordinalo implements the [Servicialo](https://github.com/servicialo/mcp-server) open protocol — an open-source MCP server specification for service scheduling platforms. This means:

- **Any Servicialo-compatible client** works with Coordinalo without modification
- **Tool names and parameters** follow the Servicialo spec
- **Other platforms** implementing Servicialo share the same interface, so your agent code is portable

The `@servicialo/mcp-server` npm package defines the protocol. Coordinalo hosts a production instance at `https://coordinalo.com/api/mcp`.

## Community & Support

- **Issues** — [GitHub Issues](https://github.com/coordinalo/coordinalo-mcp/issues) for bugs and feature requests
- **Tool Requests** — Use the [tool request template](./.github/ISSUE_TEMPLATE/tool-request.md) to propose new MCP tools
- **Website** — [coordinalo.com](https://coordinalo.com)
- **Servicialo Protocol** — [github.com/servicialo/mcp-server](https://github.com/servicialo/mcp-server)

## License

[Apache 2.0](./LICENSE)