Référence technique du serveur MCP de takotak, pour qui écrit son propre agent ou veut savoir précisément ce qu'un agent peut faire. Pour simplement connecter Claude ou Claude Code, voir Connecter un agent IA.

Le serveur

Élément Valeur
Adresse https://app.takotak.ai/api/mcp
Transport Streamable HTTP, sans session : chaque requête est indépendante, réponses en JSON
Authentification Authorization: Bearer <jeton d'accès>, obtenu par OAuth 2.1
Portée actions

Chaque réponse d'outil est un texte JSON. Une erreur (site inconnu, action déjà faite…) revient avec isError: true et une phrase qui dit quoi faire.

Les outils

Outil Type Rôle
list_sites lecture Les sites du compte.
list_actions lecture Les actions d'un site, comme dans « Mes actions ».
site_health_problems lecture Les problèmes relevés par Santé du site, adresse par adresse.
site_today lecture La journée en cours face aux mêmes jours de la semaine, comme l'onglet « Aujourd'hui ».
complete_action écriture Passe une action à faire en fait.
skip_action écriture Écarte une recommandation de takotak.
add_action écriture Note une action faite hors de « À faire ».
list_letters lecture Les lettres de la newsletter, les listes d'abonnés, les formats et les articles proposables.
get_letter lecture Une lettre en entier : objet, aperçu, destinataires, MJML, images, version texte.
create_letter écriture Crée une lettre vierge, ou la copie d'une lettre.
request_letter_draft écriture Fait rédiger une lettre par takotak.
update_letter écriture Enregistre l'objet, l'aperçu, le MJML et les destinataires.
add_letter_image écriture Dépose une image dans une lettre.
send_letter_test écriture Envoie un test à l'adresse du compte connecté.

Rien ne se supprime. Toute action à faire se passe en fait ou s'ignore, sauf celle qui se règle d'elle-même (can_complete: false) : la laisser.

list_sites

Sans paramètre. Rend le compte connecté et ses sites :

{ "account": "vous@exemple.fr", "sites": [{ "domain": "exemple.fr", "name": "Boulangerie Martin" }] }

list_actions

Paramètre Type
domain texte Domaine du site, tel que le rend list_sites.
status todo, done, resolved, skipped ou all Par défaut todo : les actions à faire. resolved : retirées d'elles-mêmes, le problème ayant disparu.

Les actions à faire sont rangées par thème (Votre entreprise, Santé du site, Votre site, Réputation en ligne, Publicité en ligne, Ce qui marche, Articles et posts, Mon pack, puis vos notes), puis par échéance (cette semaine, ce mois-ci, ensuite). Chaque action porte :

Champ
id, title Identifiant et intitulé.
theme, priority La page de la console qui porte son plan, et l'échéance.
why, how, refs Pourquoi, comment, et ce qui est visé (pages, mots-clés…).
gain Ce qu'elle rapporte, quand takotak sait le chiffrer.
kind D'où elle vient : « Recommandé par takotak », « Article publié », « Posts publiés », « Site mis à jour », « Newsletter envoyée », « Google Ads » ou « Action notée ».
link Où agir dans la console.
status, done_at, done_via, note État, date, agent et note de celui qui l'a faite.
can_complete false pour une action qui se règle d'elle-même : elle ne se passe pas en fait.

site_health_problems

Paramètre Type
domain texte Domaine du site.
list keywords, off_topic, duplicates ou gone Facultatif : une seule liste. Sans : les quatre, plus la note et les contrôles.
offset entier, 0 par défaut Rang de la première adresse rendue dans off_topic, duplicates et gone.
limit 1 à 200, 50 par défaut Nombre d'adresses rendues par liste.

Les listes viennent de la Search Console du site sur 90 jours, et gone aussi du relevé des liens entrants :

  • keywords : le mot-clé de référence de chaque thème et la page qui le porte ; to_fix signale une page qui redirige, une canonique ailleurs ou un mot-clé partagé entre plusieurs pages.
  • off_topic : les pages hors métier vues par Google sans aucun clic, à raccrocher à l'offre ou à retirer de l'index. referring_domains supérieur à 0 : la page est liée par d'autres sites, à rediriger en 301 plutôt qu'à supprimer.
  • duplicates : les adresses en double, avec leur kind et, dans kinds, le geste qui règle tout le groupe.
  • gone : les pages retirées du site (erreur 404 ou 410) qui reçoivent encore des visites depuis Google ou des liens d'autres sites, à rediriger en 301 vers la page en ligne la plus proche. from_links à true : Google ne la montre plus, seuls des liens d'autres sites y mènent encore (referring_domains). redirects_to_error à true : l'adresse redirige déjà, vers une page en erreur : c'est la cible de cette redirection qu'il faut corriger. Sur un site hébergé chez takotak, redirected_to donne la page d'arrivée quand la redirection a déjà été posée depuis la console (Santé du site › Problèmes, bouton « Rediriger »), et to_redirect compte les pages qui l'attendent encore.

Une liste longue se lit par pages : repassez next_offset dans offset tant qu'il n'est pas null. Sans analyse disponible, la réponse porte status : pending (en préparation, quelques minutes), failed ou not_available (Search Console pas encore reliée, ou pas de produit payant actif).

site_today

Paramètre Type
domain texte Domaine du site.

Répond à « est-ce normal aujourd'hui ? ». Le cumul depuis minuit des ventes (boutique), des prises de contact (vitrine) ou à défaut des visites, comparé aux huit derniers mêmes jours de la semaine à la même heure. Les ventes viennent de Mes ventes quand la journée et les jours de référence y sont déposés avec leur heure (source, sans retard), sinon de Google Analytics :

Champ
state normal, low (en dessous), high (au-dessus), early (trop peu d'événements attendus pour juger), silent (plus aucune visite mesurée) ou history (moins de quatre jours de référence).
verdict, hint Le verdict en une phrase, et une piste quand les visites et les ventes ne disent pas la même chose.
main, visits Le chiffre du jour (today), sa source, l'heure jusqu'où il est compté (counted_until) et la fourchette habituelle à la même heure (usual : low, median, high), puis sur un jour entier (usual_full_day).
counted_until L'heure jusqu'où le résultat suivi est compté : Google Analytics publie la journée avec environ trois heures de retard, les ventes déposées arrivent sans retard.
checks Le site répond, des visiteurs ces 30 dernières minutes, les annonces Google Ads s'affichent.

Une journée n'est dite en dessous ou au-dessus que hors de la fourchette et si l'écart est improbable par le seul hasard : une heure sans vente n'a rien d'anormal. Sans Google Analytics partagé avec takotak, la réponse porte status : not_available. Lecture gardée dix minutes.

complete_action

Paramètre Type
domain texte Domaine du site.
action_id texte Identifiant rendu par list_actions.
note texte, 3 à 1 000 caractères, obligatoire Ce qui a été fait, concrètement : pages modifiées, réglage changé, texte publié.
done_on AAAA-MM-JJ, facultatif Jour où l'action a été faite, heure de Paris, aujourd'hui ou avant. Par défaut : maintenant.

L'action quitte « À faire » et devient un repère daté sur la courbe des visites et des ventes, au nom de l'agent. Une date dans le futur est refusée.

skip_action

Paramètre Type
domain texte Domaine du site.
action_id texte Identifiant rendu par list_actions.

Seules les recommandations de takotak (kind « Recommandé par takotak ») s'ignorent ; elles ne reviennent pas. Une action faite se passe en fait (complete_action), elle ne s'ignore pas.

add_action

Paramètre Type
domain texte Domaine du site.
title texte, 3 à 160 caractères Ce qui a été fait, en une phrase courte.
detail texte, 1 000 caractères au plus, facultatif Précisions : pages, réglages, chiffres.
metric texte, 120 caractères au plus, facultatif Ce qu'on regarde pour juger l'effet : visites, appels, ventes, position sur un mot-clé.
done_on AAAA-MM-JJ, facultatif Comme pour complete_action.

La newsletter

Un agent compose une lettre de bout en bout, avec les mêmes droits que la console : un site du compte avec l'option Newsletter, et une newsletter déjà réglée (adresse d'envoi) pour créer une lettre. Deux gestes n'existent pas ici. La validation, qui seule envoie la lettre, reste au client, dans la console : chaque lettre rendue porte son lien console. La suppression aussi reste dans la console.

Les destinataires ne se choisissent jamais par défaut : audience vaut all (tous les abonnés) ou lists (avec list_ids), sur instruction du client.

list_letters

Paramètre Type
domain texte Domaine du site.

Rend configured (newsletter réglée ou non), le nombre d'abonnés, les lists (identifiant, nom, abonnés), les formats de rédaction, les articles publiés que la lettre peut mettre en avant, le quota de lettres rédigées par takotak (drafts_by_takotak) et les letters : état, objet, destinataires, dates et, pour une lettre partie par takotak, ses chiffres (envoyés, délivrés, ouverts, cliqués). Une lettre partie par le compte Resend du client (channel: "resend") n'a pas de chiffres ici : ils sont dans Resend.

get_letter

Paramètre Type
domain texte Domaine du site.
letter_id texte Identifiant rendu par list_letters ou create_letter.

Rend l'objet, l'aperçu (preheader), les destinataires, le mjml (qui fait foi) et son empreinte stamp, les images de la lettre (url : le src à employer dans le MJML), la version texte (text), et validation.missing, ce qui manque pour que le client puisse la valider : destinataires, un vrai objet, un texte au-delà de la salutation et de la signature.

create_letter

Paramètre Type
domain texte Domaine du site.
copy_of texte, facultatif Lettre à recopier : même MJML, mêmes images, destinataires à choisir de nouveau.

Sans copy_of, une lettre vierge au cadre du site : logo, couleur, salutation par le prénom, signature. Ni rédaction ni quota.

request_letter_draft

Paramètre Type
domain texte Domaine du site.
format texte Un format de list_letters (edito, promo, news…).
brief texte, 4 000 caractères au plus Les consignes. Exigées pour une offre : l'avantage, le code, la date de fin et les conditions, rien n'est inventé.
audience, list_ids voir plus haut Les destinataires.
article_ids liste, 6 au plus, facultatif Articles à mettre en avant.
images articles (par défaut) ou generated Les images des articles, ou des images dessinées au style du site.

La rédaction prend quelques minutes : get_letter montre l'état « en rédaction » tant qu'elle tourne. Un client a 4 lettres rédigées par 30 jours ; une lettre écrite par l'agent lui-même (create_letter) n'a pas de limite.

update_letter

Paramètre Type
domain, letter_id texte La lettre.
subject texte, 200 caractères au plus, facultatif L'objet. {{first_name}} (ou {prénom}) y met le prénom de l'abonné.
preheader texte, 200 caractères au plus, facultatif L'aperçu, la ligne que la messagerie montre après l'objet.
mjml texte, facultatif Le document MJML entier, qui remplace l'actuel.
stamp texte, exigé avec mjml L'empreinte rendue par get_letter.
audience, list_ids facultatif Les destinataires.

Seuls les champs passés changent ; list_ids va avec audience: "lists". Le MJML est vérifié puis compilé : refusé, rien n'est enregistré et le motif est rendu. Si la lettre a changé depuis la lecture (éditeur de la console, assistant, autre agent), l'enregistrement est refusé : relisez-la. Une lettre validée dont ce qui part change redevient un brouillon, à revalider par le client.

Ce que le MJML d'une lettre admet :

  • mj-head : mj-attributes, mj-font, mj-style, mj-breakpoint ;
  • mj-body > mj-wrapper ou mj-section > mj-column (ou mj-group) > mj-text, mj-image, mj-button, mj-divider, mj-spacer ;
  • des images de la lettre seulement (add_letter_image), des liens en https, mailto: ou tel: ;
  • ni mj-raw, mj-hero, mj-navbar, mj-social, mj-table ou mj-carousel, ni script, ni attribut on…, ni srcset, ni style qui charge un fichier ;
  • dans un mj-text, du HTML simple (p, strong, em, a, ul, li, br…), nettoyé à l'enregistrement ;
  • {{first_name}} pour saluer l'abonné : son prénom, à défaut son nom complet, sinon rien (« Bonjour {{first_name}}, » donne « Bonjour, »).

Le pied (nom du site, lien de désinscription) s'ajoute à chaque envoi : il ne s'écrit pas. La première section (en-tête) et la dernière (conclusion et signature) se gardent ; les blocs se placent entre les deux.

add_letter_image

Paramètre Type
domain, letter_id texte La lettre, modifiable.
url adresse publique, 5 Mo au plus L'image à récupérer.
data base64, 15 Mo au plus Ou son contenu (JPEG, PNG ou WebP).

L'image est convertie en JPEG de 1 200 px de large au plus. La réponse donne son url, à placer comme src d'un mj-image avec update_letter : déposée, elle n'apparaît dans la lettre qu'une fois placée. 40 images au plus par lettre. L'image entre aussi dans la médiathèque du site (origine « Newsletter ») : la réponse, comme chaque entrée de images dans get_letter, porte son identifiant asset, et une même image déposée deux fois ne fait qu'une entrée.

send_letter_test

Paramètre Type
domain, letter_id texte La lettre.

Envoie un test de la lettre enregistrée à l'adresse du compte connecté, et à elle seule. Rien ne part chez les abonnés. Un test par minute au plus ; get_letter › test dit s'il est parti ou pourquoi il a échoué.

Connexion OAuth

Le serveur suit la spécification d'autorisation de MCP : un agent n'a besoin que de l'adresse /api/mcp et trouve seul le reste.

  1. Sans jeton, /api/mcp répond 401 avec l'en-tête WWW-Authenticate: Bearer resource_metadata="https://app.takotak.ai/.well-known/oauth-protected-resource/api/mcp" (RFC 9728).
  2. Ces métadonnées désignent le serveur d'autorisation, décrit à https://app.takotak.ai/.well-known/oauth-authorization-server (RFC 8414).
  3. L'agent s'inscrit à /api/oauth/register (inscription dynamique, RFC 7591), puis ouvre /oauth/authorize dans le navigateur : la personne se connecte et accepte.
  4. L'agent échange le code à /api/oauth/token. PKCE S256 est obligatoire ; le code vaut 10 minutes, une seule fois.
Élément Valeur
Jeton d'accès 1 heure
Jeton de rafraîchissement 90 jours, remplacé à chaque usage (rotation)
Authentification du client au jeton none (client public), client_secret_post ou client_secret_basic
Révocation /api/oauth/revoke (RFC 7009), ou « Déconnecter » dans la page Agents IA de l'espace client

Les jetons sont opaques et ne sont jamais conservés en clair : une déconnexion vaut tout de suite.