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.
- 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. - Add the server to Claude Code. Open a terminal in any folder, paste this command, and replace
tat_your_tokenwith your token andyour-taleart-apiwith your API's host:
On Windows, the same command works in Command Prompt, PowerShell and Windows Terminal.claude mcp add --transport sse taleart https://your-taleart-api/api/v1/mcp/sse --header "Authorization: Bearer tat_your_token" - Check it. Start
claudeand type/mcp.taleartshould show as connected. Then ask Claude something like "list my TaleArt projects": it callslist_operationsandcall_operationfor 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:
| Tool | What it does |
|---|---|
list_operations | Lists 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 path | Meaning |
|---|---|
GET /api/v1/mcp/sse | Opens 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_MCP | on (default) or off, the kill switch. |