Model Context Protocol (MCP)

Quick start

ArtyChat exposes a remote Streamable HTTP MCP server. AI clients connect to it and authenticate each business through ArtyChat OAuth.

1. Add the ArtyChat MCP server to your compatible AI client.
2. Start a connection and complete ArtyChat OAuth when prompted.
3. Grant only the scopes needed for the requested tools.
4. Call read tools directly. Use write tools only when the user explicitly requests the action.

Connection details

Example MCP configuration

{
  "mcpServers": {
    "artychat": {
      "type": "streamable-http",
      "url": "https://mcp.artychat.com/mcp"
    }
  }
}

OAuth authentication

MCP access uses OAuth 2.1-style authorization with PKCE. The authenticated ArtyChat account determines which business the client can access.

• PKCE uses S256.
• Authorization code and refresh token grants are supported.
• Access tokens are bound to the MCP resource and granted scopes.
• Refresh tokens rotate when used.
• Manual External API keys are not accepted by the MCP server.

Tools and scopes

Tool access is controlled by OAuth scopes. Read and write capabilities are intentionally separated.

Tool examples

Check availability

{
  "date": "2026-10-09",
  "service_ids": [120],
  "primary_service_id": 120,
  "branch_id": 1
}

Create a booking

{
  "client_name": "OpenAI Review Test",
  "client_email": "[email protected]",
  "client_phone": "55555555",
  "service_id": 120,
  "booking_date": "2026-10-09",
  "booking_time": "14:00",
  "branch_id": 1
}

Always call get_booking_availability first and use an exact slot returned by the tool. Services can require a branch, assignee, required extra service, or quantity.

List today's bookings

{
  "date": "2026-10-05",
  "per_page": 50
}

Test with MCP Inspector

MCP Inspector is useful for verifying OAuth, scopes, schemas, and live tool results before integrating another client.

npx @modelcontextprotocol/inspector@latest

1. Open the localhost URL printed in the terminal.
2. Select Streamable HTTP.
3. Enter https://mcp.artychat.com/mcp.
4. Connect and complete ArtyChat OAuth.
5. Run tools/list, then invoke a read tool such as get_business.

Errors and authentication challenges

Unauthenticated MCP requests return a WWW-Authenticate challenge that points the client to ArtyChat's protected-resource metadata. Tool-level auth failures also include MCP authentication metadata so compatible clients can reconnect.

Expanded business tools

The MCP server now exposes the broader ArtyChat platform, not only bookings and chats.

Expense tools support receipt/logo attachments as a file object containing filename, mime_type, and base64. Exports and proof tools return file metadata and base64 content. Reconnect and authorize the new expense/delivery scopes before using them. Delivery completion must use actual customer signature and coordinates.

Write tools continue to use separate OAuth scopes and consequential-action annotations. Tools that communicate externally, create transactions, or send campaigns are marked as open-world operations.

Security and tenant isolation

• Every MCP request is authenticated to an ArtyChat user and business.
• Tools reuse ArtyChat's existing account-scoped API controllers and ownership checks.
• OAuth scopes are enforced per tool.
• Write tools change business data only when the authenticated user has the required scope.
• ArtyChat does not expose another business's bookings, customers, chats, orders, or POS data.
• Manual External API keys cannot be used as MCP access tokens.
• Clients should treat write actions such as sending messages, creating bookings, recording sales, and updating records as consequential actions and obtain clear user intent.