MCP server

TaleArt runs a Model Context Protocol (MCP) server over SSE. An MCP client, such as an assistant or a tool that speaks MCP, connects to it with an API token and works with your projects through the same operations as the API reference, as you and within the token's limits.

Connect

Three steps. You need a read-write or read-only API token first.

  1. Copy your token. In the dashboard, open Settings, then API tokens, and create one. It starts tat_; copy it now, it is shown only once.
  2. Add the server to Claude Code. Open a terminal in any folder, paste this command, and replace tat_your_token with your token and your-taleart-api with your API's host:
    claude mcp add --transport sse taleart https://your-taleart-api/api/v1/mcp/sse --header "Authorization: Bearer tat_your_token"
    On Windows, the same command works in Command Prompt, PowerShell and Windows Terminal.
  3. Check it. Start claude and type /mcp. taleart should show as connected. Then ask Claude something like "list my TaleArt projects": it calls list_operations and call_operation for you.

To remove it later: claude mcp remove taleart.

Or put it in a config file

To share the setup with a project, save this as .mcp.json in the project folder. Claude Code reads ${TALEART_TOKEN} from an environment variable of that name, so the token stays out of the file:

{
  "mcpServers": {
    "taleart": {
      "type": "sse",
      "url": "https://your-taleart-api/api/v1/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${TALEART_TOKEN}"
      }
    }
  }
}

Set the variable before starting Claude Code: on macOS or Linux, export TALEART_TOKEN=tat_your_token; on Windows, setx TALEART_TOKEN "tat_your_token", then open a new terminal.

Other MCP clients

Any client that supports MCP over SSE takes the same three values: the URL, the transport (sse) and the Authorization header. In a JSON settings file they look like this:

{
  "taleart": {
    "type": "sse",
    "url": "https://your-taleart-api/api/v1/mcp/sse",
    "headers": {
      "Authorization": "Bearer tat_your_token"
    }
  }
}

The server answers 401 without a token, and a session cookie is never accepted here. Use a read-only token when the assistant only needs to look.

Tools

The server offers two tools:

ToolWhat it does
list_operationsLists the operations this token may call: operationId, method, path, tag and summary. Takes an optional tag.
call_operation Calls one operation by its operationId, with pathParams, query and body as the operation needs. Returns the HTTP status and the JSON body.

Uploads (fonts, media and user list files) are not offered: they send files, which the tools do not carry. Use the dashboard or the command-line tool for them.

What it can do

  • Everything the token can do over the Management API, and nothing more: the token's projects and its read-only limit apply to every call.
  • Nothing a token can never do: creating, listing or revoking API tokens, sign-in and sessions, and member changes.
  • Calls are made by the API itself with the same token, so they are limited and recorded like any other request.

Kill switch

The server is on by default. To turn it off for the whole install, set TALEART_MCP=off in the API's environment and restart the API. Then /api/v1/mcp/… answers 404, and no MCP client can connect. Leave it unset, or set TALEART_MCP=on, to keep it on. Any other value stops the API at start.

Reference

Setting or pathMeaning
GET /api/v1/mcp/sseOpens the event stream. Needs Authorization: Bearer tat_….
POST /api/v1/mcp/messages?sessionId=…Carries the client's messages. Repeat the same token; another token answers 401.
TALEART_MCPon (default) or off, the kill switch.