Developer Integration

Connect your apps to KioskMate

KioskMate exposes a Model Context Protocol (MCP) endpoint for clients supporting request/response Streamable HTTP. Connect AI assistants, automation platforms and custom scripts to read office data and perform authorized actions within your workspace.

Endpoint

JSON-RPC 2.0 over HTTPS  ·  Streamable HTTP transport  ·  Bearer token authentication

POST https://kioskmate.app/api/mcp

Your exact endpoint URL is also shown in Admin → Integrations inside your workspace.

How to connect

Three steps to get up and running.

1

Choose OAuth or a connection key

For an interactive client, use OAuth to sign in and select a workspace and access level. For server-side automation, an admin can create a scoped key in Admin → Integrations; the key is shown once.

2

Point your MCP client at KioskMate

Use https://kioskmate.app/api/mcp with Streamable HTTP. OAuth clients discover authorization from the 401 challenge; key-based clients send Authorization: Bearer <key>. Keep credentials in secure storage, never in URLs or browser source code.

3

Call tools

Initialize, send notifications/initialized without an id, then call tools/list and tools/call with request ids. Use the negotiated MCP-Protocol-Version header on subsequent requests. Results stay scoped to the selected workspace.

Example request

After initialization and notifications/initialized, this request lists your offices. Load KIOSKMATE_MCP_KEY from your secret manager or a securely supplied environment variable.

curl -X POST https://kioskmate.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Authorization: Bearer ${KIOSKMATE_MCP_KEY}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_offices",
      "arguments": {}
    }
  }'

OAuth connection requirements

Start with the MCP endpoint. An unauthenticated POST returns a 401 challenge pointing to protected-resource metadata. Discover the authorization server, register your exact callback URI, then open authorization in the browser. Sign in, select a workspace and approve or deny access.

Discovery
https://kioskmate.app/.well-known/oauth-protected-resource
https://kioskmate.app/.well-known/oauth-authorization-server
Authorization and tokens
Use authorization code flow with S256 PKCE and validate callback state. Public clients register with token_endpoint_auth_method: none. Send resource=https://kioskmate.app/api/mcp on authorization, code exchange and refresh. Use one hostname consistently throughout the flow.
Least-privilege scopes
mcp:read permits six read tools. mcp permits all nine tools, subject to the access level approved at consent. An explicit read-only request defaults to Read only and disables Read & write.
Refresh and revocation
Access tokens last seven days; refresh tokens last 180 days. Refresh rotates both tokens and invalidates the previous pair. Save the new pair atomically, serialize refreshes and never retry a write blindly after an uncertain network result.

SDK read-only scope pitfall

The official TypeScript SDK 1.31.0 prefers scopes advertised by discovery over clientMetadata.scope. That setting alone does not guarantee a read-only authorization request. With your OAuthClientProvider, start authorization explicitly as shown below, or choose Read only on the consent screen.

import { auth } from '@modelcontextprotocol/sdk/client/auth.js';

// provider implements OAuthClientProvider with secure credential storage.
await auth(provider, {
  serverUrl: 'https://kioskmate.app/api/mcp',
  scope: 'mcp:read',
});
// Validate callback state, then call transport.finishAuth(code)
// and connect the client using the same provider.

Transport and troubleshooting

Response or symptomWhat to do
401 UnauthorizedStart OAuth from the challenge, refresh an expired token, or check whether the connection key was revoked.
405 on GET /api/mcpExpected: no standalone SSE stream is offered. Use POST request/response Streamable HTTP, not legacy SSE transport.
400 / invalid_targetUse the exact same-host /api/mcp resource on authorization, code exchange and refresh. Do not mix hosts.
403 Forbidden originBrowser origins must be explicitly allowlisted. Native/server-side clients may omit Origin. Never put an admin key in public browser code.
Invalid params / -32602Use tools/list as the schema source. Limits must be integers from 1 to 100; unsupported fields and types are rejected.
Tool result has isError: trueThe request reached the tool but permission or business validation failed. Check the content message; do not treat HTTP 200 alone as success.

Supported protocol: 2025-06-18. Responses are JSON; no session id or JSON-RPC batches are used. POST requests should accept both application/json and text/event-stream. Notifications have no id and return 202; tool calls require an id.

Production verification: the official SDK 1.31.0 passed browser sign-in, consent, discovery, all nine tools, read-only restrictions, workspace isolation and token refresh on October 25, 2026, using isolated test records. This is SDK-level compatibility evidence, not certification of individual assistant products. Existing outbound webhook destinations were not tested in this pass.

Available tools

9 tools across two access levels. Read-only grants and keys see 6; read & write grants and keys see all 9.

Read toolsavailable with either access level
list_offices

List the virtual offices in your organization, with room counts.

list_rooms

List rooms, optionally filtered to one office. Includes type, capacity and current occupant count.

who_is_online

List the people who are currently online, with their status and the room they are in.

list_people

List members of the organization with role, job title and live status. Optional text search.

list_meetings

List meetings — upcoming, live, past or all. Optional limit up to 100.

get_overview

A quick snapshot: office, room and member counts, how many people are online, and live/upcoming meeting counts.

Write toolsread & write access only
send_message

Post a chat message to a room (by name or id) or send a direct message to a member by email.

create_meeting

Schedule a meeting with a title, time window, optional description, room and participant emails.

invite_guest

Invite an external guest to your organization. Returns an invitation link valid for 7 days.

Security

Bearer token auth

Every MCP tool request requires an OAuth access token or an admin-issued connection key. Tokens belong in the Authorization header, not URLs.

Organization-scoped

Each grant or key is bound to one workspace. Tools only return and act on data within that workspace.

Scope control

Choose read-only or read & write during consent or key creation. Read-only access cannot trigger writes. OAuth uses S256 PKCE and resource-bound authorization.

Webhooks

Real-time event notifications

Configure outbound webhooks in Admin → Integrations to receive real-time POST notifications for office events. Supports Slack, Microsoft Teams, and generic HMAC-signed JSON webhooks.

Meeting scheduled

meeting.scheduled · Meetings

Meeting started

meeting.started · Meetings

Guest waiting in lobby

guest.knocked · Guests

Guest joined

guest.joined · Guests

Teammate invited

member.invited · Team

Teammate joined

member.joined · Team

Room created

room.created · Workspace

Office created

office.created · Workspace

Plan changed

plan.changed · Billing

Invoice paid

billing.paid · Billing

Webhook payload

Generic webhooks deliver a JSON body with an HMAC-SHA256 signature in the X-KioskMate-Signature header.

{
  "id": "evt_...",
  "type": "meeting.scheduled",
  "occurredAt": "2026-10-02T12:00:00Z",
  "organization": { "id": "org_...", "name": "Acme Corp" },
  "summary": "Daily standup scheduled for Oct 3",
  "link": "/app/meetings/mtg_...",
  "actor": { "name": "Jane Doe" },
  "metadata": null
}

Ready to integrate?

Connect with OAuth from your MCP client, or sign in and create a connection key in Admin → Integrations. Start with read-only access unless your integration needs to make changes.