Usable Chat MCP server

Endpoint: https://YOUR_USABLE_HOST/api/mcp
Transport: MCP streamable HTTP
Release: v1.173.0

Usable Chat exposes a streamable HTTP MCP server for build-plane operations around custom experts and embed configurations.

Endpoint and protocol

• Transport: MCP streamable HTTP (GET, POST, OPTIONS)
• Runtime behavior: stateless per request; authenticate every request
• Server identity: name Usable Chat, version 1.0.0

Unauthorized requests return a JSON-RPC error and a WWW-Authenticate challenge.

Client configuration

{
  "mcpServers": {
    "usable-chat": {
      "type": "streamable-http",
      "url": "https://YOUR_USABLE_HOST/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

If your client supports OAuth discovery, use its normal OAuth flow. If it requires static headers, provide a valid bearer token.

Permission model

• Read tools return only resources visible to the authenticated user.
• Some permission misses are returned as “not found”.
• Owner-only tools include destructive/archive/revoke actions.
• create_embed_key returns the token once; store it carefully.

Expert tools

list_experts

{
  "workspaceId": "optional-workspace-uuid",
  "status": "active",
  "limit": 20,
  "offset": 0
}

status can be active, archived, draft, or all.

get_expert

{ "idOrKey": "expert-uuid-or-key" }

create_expert

{
  "name": "Support Expert",
  "description": "Answers order and return questions.",
  "workspaceId": "workspace-uuid",
  "expertConfig": {
    "systemPrompt": "You are a support expert.",
    "enabledTools": ["agentic-search-fragments"],
    "parentTools": ["lookup_order"],
    "routing": { "keywords": ["order", "return", "refund"] },
    "modelPreference": "quick-thinking"
  }
}

update_expert

Provide expertId and only the fields to change.

archive_expert

{ "expertId": "expert-uuid" }

list_expert_tools

Discover tool names assignable to experts. Returns the available built-in tool categories for the current user, including memory/workspace tools, web-search tools, image tools, and documentation tools.

Embed/config tools

list_embed_configs / get_embed_config

{ "configId": "config-uuid" }

create_embed_config

{
  "name": "Docs assistant",
  "workspaceId": "workspace-uuid",
  "configData": {
    "ui": {
      "inputMode": "contained",
      "embedded": true,
      "theme": { "mode": "auto", "primaryColor": "#1f7a5b" },
      "ui": {
        "placeholder": "Ask the docs…",
        "welcomeMessageEnabled": true,
        "welcomeMessage": "Ask me about this documentation."
      }
    },
    "models": { "locked": true, "default": "anthropic/claude-haiku-4.5" },
    "features": {
      "webSearch": { "enabled": false },
      "fileUploads": { "enabled": true }
    },
    "defaultContext": { "workspaces": ["workspace-uuid"] },
    "feedback": { "mode": "host-event" }
  }
}

update_embed_config

Accepts deep-partial configData patches — only the provided fields are changed:

{
  "configId": "config-uuid",
  "configData": {
    "features": {
      "dataStaging": {
        "acceptExtensions": [".gpx", ".kml"]
      }
    }
  }
}

archive_embed_config

{ "configId": "config-uuid" }

create_embed_key

{
  "configId": "config-uuid",
  "label": "Production site",
  "allowedDomains": ["https://www.example.com"],
  "public": false
}

Non-public keys must have at least one allowed domain. Returns the token once.

revoke_embed_key

{ "configId": "config-uuid", "keyId": "key-uuid" }

get_embed_snippet

{ "token": "uc_REDACTED" }

Returns a paste-ready snippet and iframe URL.

End-to-end workflows

Create and publish a website widget

1. create_embed_config with UI/model/features/experts/feedback/defaultContext.
2. create_embed_key with production origin in allowedDomains.
3. Store the token securely.
4. get_embed_snippet and paste the snippet into the host page.
5. Test from the exact allowed origin.

Build a custom expert and attach it to an embed

1. list_expert_tools to discover available tool names.
2. create_expert with a narrow prompt and minimal enabled tools.
3. update_embed_config to add the expert ID under experts.custom.enabled.

Rotate an embed key

1. create_embed_key with the new allowed domains.
2. Deploy the new token/snippet to the host page.
3. Confirm the new iframe works.
4. revoke_embed_key for the old key.

Troubleshooting