API reference

The MCP Studio SDK provides REST endpoints for managing your developer credentials and widget configuration.

Audience	Developers building server-side SDK automations or admin tooling
Prerequisites	SDK Client Secret for server-to-server calls or an authenticated portal session

Base URL

https://appatools.com/mcp-studio-sdk/api

Authentication

All API requests require a valid session cookie (for portal access) or an Authorization: Bearer header with your Client Secret (for server-to-server calls).

curl -X GET https://appatools.com/mcp-studio-sdk/api/configurations \
  -H "Authorization: Bearer YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json"

---

Credentials

GET /api/credentials

Retrieve your developer credentials. If no developer profile exists, one is automatically created with a new Client ID and Client Secret.

Response:

{
  "clientId": "clxyz123abc",
  "clientSecret": "mcps_a1b2c3d4e5f6...",
  "appName": "My App"
}

PUT /api/credentials

Regenerate your Client Secret. The old secret is immediately invalidated.

Request body:

{
  "action": "regenerate_secret"
}

Response: Same shape as GET, with the new secret.

---

Attribution

POST /api/attribution/token

Exchange your Client Secret for a short-lived token proving an embed session is yours. Call this from your backend only. See Verify embed sessions for the full integration.

Headers: Authorization: Bearer YOUR_CLIENT_SECRET

Request body:

{
  "clientId": "clxyz123abc",
  "endUserId": "user_1842"
}

endUserId is optional and opaque to us. It records which of your users a session belongs to.

Response:

{
  "token": "mcpsat_v1.eyJjaWQiOi...",
  "expiresAt": "2026-09-08T16:45:00.000Z",
  "expiresInSeconds": 900
}

Pass token to the embed as attributionToken. It is valid for 15 minutes and works once, so mint one per embed session and do not cache the response.

Errors:

Status	Meaning
400	Body was not valid JSON
401	Missing or invalid clientId / Client Secret. The same response is returned for an unknown client and a wrong secret
403	The request carried an Origin header, meaning it came from a browser. Your Client Secret must never reach frontend code
503	Signing is unavailable. Not a fault in your integration

---

Configurations

GET /api/configurations

Retrieve your saved SDK configurations, ordered by most recently updated.

Response:

[
  {
    "id": "clxyz789def",
    "developerId": "clxyz456ghi",
    "name": "Default",
    "domain": null,
    "tools": "[{...}]",
    "sources": "[{...}]",
    "colors": "{...}",
    "layout": "horizontal",
    "fontFamily": "Inter",
    "isActive": true,
    "createdAt": "2026-04-17T12:00:00.000Z",
    "updatedAt": "2026-04-17T12:00:00.000Z"
  }
]

POST /api/configurations

Create or update your SDK configuration. If a configuration already exists, it is updated (upsert behavior).

Request body:

{
  "domain": "yourdomain.com",
  "tools": "[{\"name\":\"search_docs\",\"enabled\":true,...}]",
  "sources": "[{\"type\":\"website\",\"enabled\":true,...}]",
  "colors": "{\"primary\":\"#6366f1\",\"background\":\"#fafafa\"}",
  "layout": "vertical",
  "fontFamily": "Plus Jakarta Sans"
}

Validation Rules

Field	Rules
domain	Valid domain format (e.g., example.com). Max 253 characters.
tools	Valid JSON string, max 10,000 characters. No script injection.
sources	Valid JSON string, max 10,000 characters. No script injection.
colors	Valid JSON string, max 10,000 characters. No script injection.
layout	Must be "horizontal" or "vertical".
fontFamily	Alphanumeric and spaces only. Max 100 characters.

---

Error responses

All endpoints return standard HTTP status codes:

Status	Description
200	Success
400	Invalid input (validation failed)
401	Not authenticated
404	Resource not found

Error responses include a JSON body:

{
  "error": "Invalid tools configuration"
}