{
  "openapi": "3.1.0",
  "info": {
    "title": "Clara MCP API",
    "summary": "Model Context Protocol access to a Clara account's calls, messages, and customers",
    "description": "Clara is an AI receptionist for small businesses. The Clara MCP server lets an AI assistant read a\nClara account holder's own calls, messages, and customers, and change their receptionist settings,\nover the Model Context Protocol.\n\nTransport: MCP Streamable HTTP. Send JSON-RPC 2.0 messages to POST /mcp with\n`Accept: application/json, text/event-stream`. The server may answer with a single JSON response or\nan SSE stream, and may return an `Mcp-Session-Id` header to be echoed on later requests.\n\nAuthorization: OAuth 2.1 with PKCE. Clara is both the protected resource and its own authorization\nserver, and registers clients dynamically (RFC 7591), so no manual app registration is needed. An\nunauthenticated request answers 401 with a `WWW-Authenticate: Bearer resource_metadata=...` challenge\npointing at the protected resource metadata (RFC 9728).\n\nPermissions: there is no scope vocabulary today. A token acts as one Clara user on the businesses\ntheir account can already reach, tenancy is enforced by the Clara backend on every call, and MCP\nclients confirm write tools with the person before calling them.",
    "version": "2026-08-21",
    "termsOfService": "https://heyitsclara.com/us/terms/",
    "contact": {
      "name": "Clara support",
      "email": "support@heyitsclara.com",
      "url": "https://heyitsclara.com/developers/"
    }
  },
  "externalDocs": {
    "description": "Clara developer resources",
    "url": "https://heyitsclara.com/developers/"
  },
  "servers": [
    {
      "url": "https://mcp.heyitsclara.com",
      "description": "Clara MCP server"
    }
  ],
  "security": [
    {
      "claraOAuth": []
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "mcpRpc",
        "summary": "Send an MCP JSON-RPC message",
        "description": "Initialize a session, list tools, or call one. The tool catalogue and each tool's access level are listed under `x-mcp-tools`.",
        "security": [
          {
            "claraOAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Mcp-Session-Id",
            "in": "header",
            "required": false,
            "description": "Session id returned by the server on initialize; echo it on later requests.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "MCP-Protocol-Version",
            "in": "header",
            "required": false,
            "description": "MCP revision the client speaks, e.g. 2025-06-18.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result, either as a single JSON response or an SSE stream.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Missing or rejected token. Carries a `WWW-Authenticate: Bearer resource_metadata=...` challenge (RFC 9728).",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer challenge pointing at the protected resource metadata.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Liveness and the live tool catalogue",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is up; `tools` lists the tool names currently served.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "tools": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "tools"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "claraOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorization code with PKCE (S256). Clara is its own authorization server and supports dynamic client registration, so clients need no pre-issued credentials.  No scope vocabulary is issued yet, so `scopes` is empty: a token acts as the authorizing Clara user, limited to the businesses their account can reach, and tenancy is enforced by the Clara backend on every call.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://mcp.heyitsclara.com/authorize",
            "tokenUrl": "https://mcp.heyitsclara.com/token",
            "refreshUrl": "https://mcp.heyitsclara.com/token",
            "scopes": {}
          }
        }
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "number"
            ]
          },
          "method": {
            "type": "string",
            "examples": [
              "initialize",
              "tools/list",
              "tools/call"
            ]
          },
          "params": {
            "type": "object"
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "number"
            ]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-mcp": {
    "endpoint": "https://mcp.heyitsclara.com/mcp",
    "transport": "Streamable HTTP (Model Context Protocol)",
    "protocolRevision": "2025-06-18",
    "requiresPlan": "Clara Pro",
    "authorizationServerMetadata": "https://mcp.heyitsclara.com/.well-known/oauth-authorization-server",
    "protectedResourceMetadata": "https://mcp.heyitsclara.com/.well-known/oauth-protected-resource",
    "dynamicClientRegistration": true
  },
  "x-mcp-tools": [
    {
      "name": "get_account",
      "access": "read",
      "summary": "The signed-in Clara account"
    },
    {
      "name": "list_businesses",
      "access": "read",
      "summary": "Businesses on the account"
    },
    {
      "name": "get_business",
      "access": "read",
      "summary": "One business and its receptionist setup"
    },
    {
      "name": "list_inquiries",
      "access": "read",
      "summary": "Inquiries captured from calls and texts"
    },
    {
      "name": "get_inquiry",
      "access": "read",
      "summary": "One inquiry in full"
    },
    {
      "name": "list_calls",
      "access": "read",
      "summary": "Answered calls with summaries"
    },
    {
      "name": "get_call_statistics",
      "access": "read",
      "summary": "Call volume and outcome totals"
    },
    {
      "name": "list_customers",
      "access": "read",
      "summary": "Callers Clara has spoken to"
    },
    {
      "name": "get_customer",
      "access": "read",
      "summary": "One customer and their history"
    },
    {
      "name": "get_recording",
      "access": "read",
      "summary": "A call recording and transcript"
    },
    {
      "name": "search",
      "access": "read",
      "summary": "Search across calls, messages, and customers"
    },
    {
      "name": "list_voices",
      "access": "read",
      "summary": "Voices the receptionist can use"
    },
    {
      "name": "preview_receptionist_voice",
      "access": "read",
      "summary": "Hear a voice before switching"
    },
    {
      "name": "list_receptionist_rules",
      "access": "read",
      "summary": "Instructions, follow-ups, transfer rules"
    },
    {
      "name": "update_business",
      "access": "write",
      "summary": "Edit business details"
    },
    {
      "name": "update_receptionist",
      "access": "write",
      "summary": "Edit greeting, voice, and intake fields"
    },
    {
      "name": "update_customer",
      "access": "write",
      "summary": "Edit a customer record"
    },
    {
      "name": "mark_inquiry_read",
      "access": "write",
      "summary": "Mark an inquiry read"
    },
    {
      "name": "set_inquiry_status",
      "access": "write",
      "summary": "Change an inquiry status"
    },
    {
      "name": "add_special_instruction",
      "access": "write",
      "summary": "Add a receptionist instruction"
    },
    {
      "name": "update_special_instruction",
      "access": "write",
      "summary": "Edit a receptionist instruction"
    },
    {
      "name": "remove_special_instruction",
      "access": "write",
      "summary": "Delete a receptionist instruction"
    },
    {
      "name": "add_followup_text",
      "access": "write",
      "summary": "Add an automated follow-up text"
    },
    {
      "name": "update_followup_text",
      "access": "write",
      "summary": "Edit an automated follow-up text"
    },
    {
      "name": "remove_followup_text",
      "access": "write",
      "summary": "Delete an automated follow-up text"
    },
    {
      "name": "test_followup_text",
      "access": "write",
      "summary": "Send yourself a test follow-up text"
    },
    {
      "name": "add_transfer_rule",
      "access": "write",
      "summary": "Add a live call transfer rule"
    },
    {
      "name": "update_transfer_rule",
      "access": "write",
      "summary": "Edit a live call transfer rule"
    },
    {
      "name": "remove_transfer_rule",
      "access": "write",
      "summary": "Delete a live call transfer rule"
    },
    {
      "name": "reply_to_customer",
      "access": "write",
      "summary": "Send a text reply to a customer"
    },
    {
      "name": "mark_sms_read",
      "access": "write",
      "summary": "Mark a text conversation read"
    }
  ],
  "x-permissions": {
    "identity": "Every request carries the individual Clara user's own credential. There is no cross-tenant key and no shared service account.",
    "tenancy": "A connection can only reach the businesses on the account that authorized it. Clara's backend enforces tenancy on every call, not the MCP layer.",
    "confirmation": "Write tools change a live receptionist, so MCP clients ask the person to confirm each call before it runs.",
    "revocation": "Access ends when the person disconnects Clara in their assistant or revokes the connection from the Clara web app. Nothing keeps working on its own afterwards.",
    "limits": "Per-user rate limits, a global concurrency cap, request timeouts, and a circuit breaker protect the Clara backend behind the MCP server.",
    "scopes": "No OAuth scope vocabulary is issued yet, so a client cannot currently request read-only access at the token level. Least-privilege today means connecting only the account that needs it and confirming writes."
  }
}