MCP server: operate your account from your coding agent

nisebookings runs a hosted Model Context Protocol server on top of the Management API. Connect Claude Code, Codex, Cursor or VS Code to it and the agent can read your catalogue, find free times, plan and change appointments, and configure the account with tool calls — the same operations, scopes and validation as /api/v1, without writing HTTP code.

1. Get a key

In the admin, go to Settings → API → New key and pick the scopes the agent may use (table in the Management API quickstart). The key is shown once. Every tool call is checked against the key's scopes exactly like the REST call it maps to: a missing scope comes back as a tool error with status 403, not as a connection failure, so a read-only key is a safe way to start.

Just trying it? curl -s -X POST https://app.nisebookings.com/api/sandbox (no auth) returns a 24-hour sandbox account with an all-scopes apiKey — connect MCP with that. At most 5 per hour per IP; over that you get 429 {"error":{"code":"rate_limited"}} and both the Retry-After header and the message say how long to wait (a sliding window, so usually a minute or two, not a full hour). Its mail is never delivered; list_outbox shows what would have been sent.

Keep the key out of version control: every snippet below reads it from an environment variable or a prompt. Revoke it in Settings → API when you no longer need it; every write that reaches the database is audited per key (rate-limited rejections and the sandbox delete are not).

2. Connect

Claude Code

claude mcp add --transport http nise-booking https://app.nisebookings.com/api/mcp \
  --header "Authorization: Bearer $NISE_API_KEY"

The shell expands $NISE_API_KEY once, so the key is stored in your user config (~/.claude.json), not in the project. To share the server with a team, commit a .mcp.json that expands the variable at start-up instead, so each member uses their own key:

{
  "mcpServers": {
    "nise-booking": {
      "type": "http",
      "url": "https://app.nisebookings.com/api/mcp",
      "headers": { "Authorization": "Bearer ${NISE_API_KEY}" }
    }
  }
}

Check with claude mcp list, or /mcp inside a session.

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json)

{
  "mcpServers": {
    "nise-booking": {
      "url": "https://app.nisebookings.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:NISE_API_KEY}" }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.nise-booking]
url = "https://app.nisebookings.com/api/mcp"
bearer_token_env_var = "NISE_API_KEY"

Codex sends Authorization: Bearer <value of NISE_API_KEY>. Export the variable in the shell that starts Codex. A trusted project can use .codex/config.toml instead.

VS Code / GitHub Copilot (.vscode/mcp.json)

{
  "inputs": [
    { "type": "promptString", "id": "nise-api-key", "description": "nisebookings API key (nk_…)", "password": true }
  ],
  "servers": {
    "nise-booking": {
      "type": "http",
      "url": "https://app.nisebookings.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:nise-api-key}" }
    }
  }
}

VS Code asks for the key once and stores it securely; the file itself holds no secret and can be committed.

Any other client

Any MCP client that supports Streamable HTTP with a custom header works. To check the endpoint by hand:

curl -s https://app.nisebookings.com/api/mcp -H "Authorization: Bearer $NISE_API_KEY" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3. Tools

Tool names are snake_case; arguments are camelCase and go to the Management API unchanged, so the field names, defaults and error codes in openapi.yaml and the quickstart apply. Read-only tools carry readOnlyHint; deletes and whole-object replacements carry destructiveHint, so clients can auto-approve reads and ask before anything changes. whoami and find_slots work with any valid key. The client gets each tool's full description and JSON Schema from tools/list.

Everything else under /api/v1 — extras, compound-service parts, notification templates, events and ticket types, packages, coupon edits, payment completion and refunds, the Mollie key, webhook edits, secret rotation and delivery retries — goes through api_request {method, path, query?, body?} with path relative to /api/v1 (for example {"method":"POST","path":"/services/<id>/extras","body":{"title":"Wassen","price":5}}). Its description lists every route.

4. Results and errors

• A tool result is the API's JSON response as text (and as structuredContent when it is an object). A 204 comes back as ok.
• An API error is a tool result with isError: true and the API's error body plus its HTTP status: 403 forbidden (scope missing), 404 not_found, 409 slot_unavailable / capacity_exceeded, 422 validation (see fields) and 422 warnings.
• Warnings and force. Creating or moving an appointment runs the admin's checks (overlap, duration, outside the schedule or in a break, day off). Any of these returns 422 warnings with the reasons in fields. Show them to the human; resend with force: true only when they agree.
• notify defaults to false on appointment and booking writes, so the agent never mails a customer unless asked.
• Lists take limit (1–100, default 50) and offset and return {data, total}.
• Webhooks. create_webhook returns the signing secret (whsec_…) once — hand it to the human or store it where the receiver reads it. Then test_webhook and, a second later, list_webhook_deliveries to see whether the receiver answered 2xx. Payloads and verification: Webhooks.
• A missing or invalid key fails the whole HTTP request with 401 and WWW-Authenticate: Bearer; the client shows the server as failed to connect.

5. Verify the connection

Ask the agent: "Use nise-booking: who am I, and what are the next free times for the first service?" It should call whoami, list_services and find_slots. If the client reports the server as failed, the key is missing, wrong or revoked (401). If a tool returns 403, the key lacks that scope.

The whole flow (initialize, tool list, slot search, customer + appointment create/update/delete, scope check) is covered by an automated end-to-end test.

Limits

• API keys only; OAuth (and therefore "Connect" buttons in hosted assistants such as claude.ai) is not supported yet.
• No resources, prompts or server-sent notifications — tools only, and the tool list does not change.
• One JSON-RPC message per request (no batches). Browser origins other than the app's own are refused.
• MCP calls run through the same handlers in process: /api/v1 tool calls share the key's 120 requests/min budget (per server process) and always speak the latest API version, while the public-API tools (find_slots, …) have no client address and are counted per tenant, not per key.
• Not available through MCP either: creating accounts (a sandbox is created with POST /api/sandbox, no key) and dashboard statistics. Deleting a sandbox early: api_request {"method":"DELETE","path":"/sandbox"}.