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
Your exact endpoint URL is also shown in Admin → Integrations inside your workspace.
How to connect
Three steps to get up and running.
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.
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.
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-resourcehttps://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. Sendresource=https://kioskmate.app/api/mcpon authorization, code exchange and refresh. Use one hostname consistently throughout the flow. - Least-privilege scopes
mcp:readpermits six read tools.mcppermits 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 symptom | What to do |
|---|---|
| 401 Unauthorized | Start OAuth from the challenge, refresh an expired token, or check whether the connection key was revoked. |
| 405 on GET /api/mcp | Expected: no standalone SSE stream is offered. Use POST request/response Streamable HTTP, not legacy SSE transport. |
| 400 / invalid_target | Use the exact same-host /api/mcp resource on authorization, code exchange and refresh. Do not mix hosts. |
| 403 Forbidden origin | Browser origins must be explicitly allowlisted. Native/server-side clients may omit Origin. Never put an admin key in public browser code. |
| Invalid params / -32602 | Use tools/list as the schema source. Limits must be integers from 1 to 100; unsupported fields and types are rejected. |
| Tool result has isError: true | The 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.
list_officesList the virtual offices in your organization, with room counts.
list_roomsList rooms, optionally filtered to one office. Includes type, capacity and current occupant count.
who_is_onlineList the people who are currently online, with their status and the room they are in.
list_peopleList members of the organization with role, job title and live status. Optional text search.
list_meetingsList meetings — upcoming, live, past or all. Optional limit up to 100.
get_overviewA quick snapshot: office, room and member counts, how many people are online, and live/upcoming meeting counts.
send_messagePost a chat message to a room (by name or id) or send a direct message to a member by email.
create_meetingSchedule a meeting with a title, time window, optional description, room and participant emails.
invite_guestInvite 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.
