# expertapp-receptionist-mcp

An [MCP](https://modelcontextprotocol.io) server that lets an AI agent act as
the receptionist for a business on [expert.com.jm](https://expert.com.jm) —
**without the API key ever entering the model's own context.**

This is the recommended way to connect an agent to expert.com.jm's Reception
API. The companion
[expertapp-receptionist skill](https://github.com/incrhst/expertapp-receptionist-skill)
(a plain REST API + prompt instructions) works too, but it requires the model
itself to construct an `Authorization: Bearer <key>` header on every request —
meaning the raw key has to pass through the model's own reasoning/output at
some point, which is exposed to conversation transcripts, logs, and
prompt-injection-triggered echoes. This server closes that gap: the key lives
only in this process's environment, set once in your agent's own
configuration file, never typed into a conversation. The model just calls
typed tools (`create_booking`, `check_availability`, ...) and never sees a
header, a key, or anything that looks like one.

## Install & configure

Add it to your MCP client's config (Claude Code, Claude Desktop, Cursor,
Windsurf, and most other MCP-compatible tools use a similar JSON config
format — check your tool's docs for the exact file/location):

```json
{
  "mcpServers": {
    "expertapp-receptionist": {
      "command": "npx",
      "args": ["-y", "github:incrhst/expertapp-receptionist-mcp"],
      "env": {
        "EXPERTAPP_API_KEY": "your-key-here"
      }
    }
  }
}
```

Get the key from the business's expert.com.jm dashboard: **Team → Reception
& management access → Generate an API key for an AI agent**. It's shown
once — paste it directly into this config file, not into a chat with the
agent.

Optional: set `EXPERTAPP_BASE_URL` in the same `env` block if the business
uses a white-labelled or staging domain. Defaults to
`https://www.expert.com.jm` — **use `www`, not the bare apex domain**: the
apex 308-redirects to `www`, and most HTTP clients (correctly, per the fetch
spec) strip the `Authorization` header on that cross-origin hop, which makes
requests against the apex silently unauthenticated rather than failing
loudly.

## Tools

| Tool | What it does |
|---|---|
| `list_services` | Every bookable service across the team, labelled with who it belongs to |
| `check_availability` | Open start times for one service over the next two weeks |
| `create_booking` | Books an appointment. Paid bookings confirm on payment; free ones hold the slot and require the client to confirm by email |
| `list_bookings` | Every booking across the team, most recent first |
| `reschedule_booking` | Moves a booking — requires the client's email/phone to match the record |
| `request_cancellation` | Queues a cancellation — the booking stays active until the client confirms by email, and may be rejected if it's within the business's cancellation-notice window |

Full behavior (including the email-confirmation flows and cancellation
policy) is documented in the
[skill's SKILL.md](https://github.com/incrhst/expertapp-receptionist-skill/blob/main/skills/expertapp-receptionist/SKILL.md) —
this server calls the exact same API, just without the model ever touching
the credential.

## Scope, on purpose

Same as the REST skill: view services/availability, create/reschedule/cancel
bookings. No pricing, subscription/billing, or payout access, and no refund
tool — those stay human-only, in the business's own dashboard.

## Local development

```bash
npm install
npm run build
EXPERTAPP_API_KEY=... node dist/index.js
```

## License

MIT