SelfScale API

SelfScale exposes one programmatic endpoint, https://selfscale.app/api/mcp. It speaks the Model Context Protocol over Streamable HTTP, which is plain JSON-RPC 2.0 sent with an HTTP POST. AI clients such as Claude and Cursor use it for you, and you can call it directly with curl or any HTTP library.

Every tool available with a personal API key is read-only. To connect an AI assistant instead of writing code, see the MCP server guide.

Create a personal API key in SelfScale under Settings › Developer. Keys start with ss_live_, are shown once, and can be revoked at any time. Send the key on every request in the Authorization header:

Authorization: Bearer ss_live_...

A missing, malformed, revoked or expired key gets 401 Unauthorized with a WWW-Authenticate: Bearer challenge. Keep keys out of source control and client-side code; treat a key like a password.

The server is stateless, so you can call tools/list and tools/call directly. Sending an initialize request first is optional; it returns the server's capabilities and protocol version:

curl -s https://selfscale.app/api/mcp \
  -H "Authorization: Bearer $SELFSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-script","version":"1.0.0"}}}'

tools/list returns every tool your key can call, with its title, description, JSON Schema for its arguments and annotations such as readOnlyHint.

curl -s https://selfscale.app/api/mcp \
  -H "Authorization: Bearer $SELFSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_voice_profile",
        "title": "Get my voice profile",
        "description": "Your SelfScale voice profile: the rules your writing follows, your signature phrases, words you avoid, and your tone settings. Use it to write in your voice.",
        "inputSchema": {
          "type": "object",
          "properties": {}
        },
        "annotations": {
          "title": "Get my voice profile",
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        }
      },
      {
        "...": "8 more"
      }
    ]
  }
}

tools/call runs one tool. Put the tool name in params.name and its arguments in params.arguments. The tool's result comes back as JSON text inside result.content[0].text.

curl -s https://selfscale.app/api/mcp \
  -H "Authorization: Bearer $SELFSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_voice_profile","arguments":{}}}'

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"success\":true,\"hasProfile\":true,\"profile\":{\"name\":\"My voice\",\"active\":true,\"version\":3,\"updatedAt\":\"2026-10-02T12:00:00.000Z\"},\"voice\":{\"learned\":true,\"rules\":[\"Short sentences.\",\"Open with a concrete number.\"],\"signaturePhrases\":[\"Here's the thing\"],\"avoidedWords\":[\"leverage\",\"synergy\"]},\"tone\":{\"...\":\"your tone settings\"},\"toneOmitted\":false}"
      }
    ]
  }
}

Every available tool, its arguments and an example response are listed in the tools reference.

Each key can send up to 60 requests a minute. Each account also has a number of calls per day, set by plan and reset at midnight UTC. Every request counts, including tools/list and initialize.

Usage headers

Successful responses carry your daily usage:

Going over either limit returns 429. Wait for the reset (the response body includes resetAt for the daily limit), then retry. Back off and retry on 503 after the number of seconds in Retry-After.

HTTP errors

The request was refused before any tool ran. The body is JSON with error and message.

Tool errors

The request was accepted but the tool could not finish. The HTTP status is 200, the JSON-RPC result has isError: true, and content[0].text holds {"error": CODE, "message": "..."}.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"NOT_FOUND\",\"message\":\"Competitors is not available on your account yet.\"}"
      }
    ],
    "isError": true
  }
}

A malformed JSON-RPC message gets a standard JSON-RPC error (for example -32600 invalid request or -32602 invalid params) instead of a result.

The endpoint follows the MCP specification. The server negotiates the protocol version in initialize; the version used in these examples is 2025-06-18. Tool names are stable. New tools and new optional arguments can be added at any time, so ignore fields you don't recognize. Breaking changes, such as a renamed tool, are listed on this page.