API des outils et serveur MCP

Tous les outils de Bluesky.bot s’utilisent aussi gratuitement depuis du code et depuis des agents IA : comme API REST, et comme outils de notre serveur MCP. Sans inscription ni clé : appelez-les. Chaque réponse renvoie vers la page de l’outil.

Endpoints

OutilAPIOutil MCP
Trouver un DIDGET /api/v1/tools/did-finder?handle=…find_did
Trouver un handleGET /api/v1/tools/handle-finder?did=…find_handle
WhoisGET /api/v1/tools/whois?actor=…whois_lookup
Âge d’un compteGET /api/v1/tools/account-age?actor=…check_account_age
Convertisseur d’AT URIGET /api/v1/tools/at-uri-converter?uri=…convert_at_uri
Décodeur de TIDGET /api/v1/tools/tid-decoder?tid=…decode_tid
Compteur de caractèresGET /api/v1/tools/character-counter?text=…&numbered=truecount_post_characters
Générateur de facettes de texte enrichiGET /api/v1/tools/facet-builder?text=…&langs=enbuild_post_facets
Vérificateur de handle de domaineGET /api/v1/tools/custom-handle-checker?domain=…&expected=…check_custom_handle
Vérificateur de disponibilité de handleGET /api/v1/tools/handle-availability?name=…check_handle_availability
Historique PLCGET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=falseplc_history
Analyseur de starter packsGET /api/v1/tools/starter-pack-analyser?q=…analyse_starter_pack
Lecteur de posts et de filsGET /api/v1/tools/post-viewer?post=…&embed=falseview_bluesky_post
Inspecteur de fluxGET /api/v1/tools/feed-inspector?feed=…&check=falseinspect_bluesky_feed

L’URL de base est https://bluesky.bot/api/v1. Les paramètres et la réponse de chaque outil figurent dans la référence de l’API et dans le document OpenAPI, /api/v1/openapi.json.

Une réponse a toujours la même forme : le slug de l’outil, l’URL de sa page, et son result.

json
{
  "tool": "character-counter",
  "url": "https://bluesky.bot/tools/character-counter",
  "result": { "graphemes": 16, "bytes": 19, "over": false, "parts": [] }
}

Limites

  • Gratuit et anonyme : 60 appels par minute et 2 000 par jour par adresse IP. Un outil qui envoie plusieurs requêtes en coulisses compte pour plus d’un appel ; la référence de l’API le précise.
  • Avec un jeton d’API : 10 fois plus, compté par compte. Les créateurs qui ont au moins un bot sur Bluesky.bot en créent un dans le tableau de bord, sous Paramètres → Accès API et CLI ; un jeton de l’outil en ligne de commande fonctionne aussi. Envoyez-le dans Authorization: Bearer <token>. Un jeton dure 30 jours ; gardez-le hors du code public.
  • Ce que peut faire un jeton du tableau de bord : appeler les outils, rien d’autre. Il a la portée tools : il ne peut ni gérer vos bots, ni réserver ou libérer un handle, ni utiliser les routes /api/v1/me/* de la CLI, qui lui répondent 401.
  • Au-delà d’une limite, la réponse est 429 avec un en-tête Retry-After, en secondes.
  • Un jeton inconnu, expiré ou révoqué reçoit 401 : retirez l’en-tête pour appeler de façon anonyme.

Les erreurs gardent la forme habituelle de l’API, { "error": { "code", "message" } }, avec bad_request (et le parameter), unauthorized, not_found, rate_limited et upstream_error (le service qu’interroge un outil n’a pas répondu). Les réponses portent des en-têtes CORS, pour qu’une page web puisse les appeler, et un en-tête de cache : un calcul pur, comme le compteur, est mis en cache pour de bon.

Exemples

Avec curl, qui encode le texte pour vous :

bash
curl -G "https://bluesky.bot/api/v1/tools/character-counter" \
  --data-urlencode "text=Hello Bluesky! 👋"

En JavaScript ou TypeScript (Node.js 18 ou plus, Deno, Bun ou un navigateur) :

tools-api.ts
// tools-api.ts : compte un post avec l’API gratuite des outils.
// Sans clé.
const url = new URL("https://bluesky.bot/api/v1/tools/character-counter");
url.searchParams.set("text", "Hello Bluesky! 👋");

// Un jeton d’API créé dans les paramètres du tableau de bord
// multiplie les limites par dix.
const token = process.env.BSBOT_TOKEN;
const response = await fetch(url, {
  headers: token ? { Authorization: `Bearer ${token}` } : {},
});
if (response.status === 429) {
  const wait = response.headers.get("Retry-After");
  throw new Error(`Rate limited: retry in ${wait} s.`);
}
const answer = (await response.json()) as {
  url: string;
  result: { graphemes: number; graphemesLeft: number; over: boolean };
};

const { graphemes, graphemesLeft } = answer.result;
console.log(`${graphemes} graphemes, ${graphemesLeft} left. ${answer.url}`);

// Fait de ce fichier un module ES, ce qu’exige le await de premier niveau.
export {};

En Python, avec requests :

tools-api.py
# tools_api.py : compte un post avec l’API gratuite des outils.
# Sans clé.
import os

import requests

# Un jeton d’API créé dans les paramètres du tableau de bord
# multiplie les limites par dix.
token = os.environ.get("BSBOT_TOKEN")
headers = {"Authorization": f"Bearer {token}"} if token else {}

response = requests.get(
    "https://bluesky.bot/api/v1/tools/character-counter",
    params={"text": "Hello Bluesky! 👋"},
    headers=headers,
    timeout=10,
)
if response.status_code == 429:
    wait = response.headers["Retry-After"]
    raise SystemExit(f"Rate limited: retry in {wait} s.")
response.raise_for_status()

answer = response.json()
result = answer["result"]
print(f"{result['graphemes']} graphemes, {result['graphemesLeft']} left. {answer['url']}")

Serveur MCP

Le serveur MCP liste les mêmes outils, avec leurs schémas d’entrée et de sortie, pour les agents IA et les éditeurs : https://bluesky.bot/api/mcp (Streamable HTTP, sans session). Tous les outils sont en lecture seule. Les mêmes limites s’appliquent ; un jeton dans l’en-tête Authorization les relève.

Connexion en un clic

Plutôt vous connecter que coller un jeton ? Ajoutez https://bluesky.bot/api/mcp/connect à la place. Votre app d’IA ouvre une page de Bluesky.bot : connectez-vous avec votre compte Bluesky (nous ne demandons jamais votre mot de passe), vérifiez le nom de l’app et l’adresse vers laquelle elle vous renvoie, et autorisez. L’app reçoit alors son propre jeton, et le renouvelle seule.

Dans Claude Code :

bash
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp/connect

Dans Claude Desktop ou sur claude.ai, ajoutez un connecteur personnalisé avec cette URL et choisissez Connecter. Dans Cursor ou VS Code, mettez-la comme url de la configuration ci-dessous, puis connectez-vous quand l’éditeur le demande.

  • L’app reçoit la portée tools : les outils, avec les limites plus hautes de votre compte si vous avez un bot sur Bluesky.bot. Elle ne peut ni publier, ni gérer vos bots, ni réserver un handle.
  • Une app autorisée est mémorisée. Révoquez-la quand vous voulez dans Paramètres → Apps connectées ; Se déconnecter partout et la suppression de votre compte révoquent toutes les apps.
  • Seules quelques apps bien connues sont marquées Vérifiée. Pour les autres, vérifiez l’adresse vers laquelle elles vous renvoient avant d’autoriser.
  • https://bluesky.bot/api/mcp fonctionne toujours sans connexion.

Dans Claude Code :

bash
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp

Dans Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json, avec "servers" au lieu de "mcpServers") et la plupart des autres clients :

json
{
  "mcpServers": {
    "bluesky-bot": { "url": "https://bluesky.bot/api/mcp" }
  }
}

Dans Claude Desktop ou sur claude.ai, ajoutez-le comme connecteur personnalisé avec la même URL. Avec un jeton, ajoutez un en-tête : --header "Authorization: Bearer $BSBOT_TOKEN" dans Claude Code, ou "headers": { "Authorization": "Bearer …" } à côté de url dans une configuration JSON. Ne versionnez jamais un fichier de configuration qui contient un jeton : gardez-le dans une variable d’environnement, ou dans les réglages privés de votre client.

Ce qui est envoyé, ce qui est gardé

Ce que vous envoyez à un outil sert uniquement à répondre : ce n’est jamais stocké, et c’est retiré de nos rapports d’erreur. Un appel à l’API le porte dans son adresse : les journaux de requêtes de notre serveur ignorent ces adresses, mais elles passent par le réseau de Cloudflare qui achemine le trafic du site. MCP l’envoie dans le corps de la requête, qu’aucun journal de requêtes ne garde : vous pouvez le préférer pour un texte sensible. Les statistiques comptent seulement quel outil a été appelé, depuis où (une page, l’API ou MCP) et comment cela s’est terminé. Un outil qui recherche quelque chose envoie l’entrée aux services publics dont il a besoin, comme sa page. Voir la politique de confidentialité.