# Développeurs — API GraphQL & serveur MCP Pilotariak | Pilotariak

> Portail développeurs Pilotariak : l’API GraphQL publique Frontis et le serveur MCP Azkena pour les données de pelote basque. Endpoints, authentification, démarrage rapide et erreurs.

Développeurs

# Portail développeurs Pilotariak

Pilotariak publie les données de la pelote basque — clubs, compétitions, catégories, spécialités et résultats — via deux interfaces libres et gratuites : l’**API GraphQL Frontis** pour les applications et le **serveur MCP Azkena** pour les assistants IA. Les deux sont en lecture seule.

## Démarrage rapide

L’API GraphQL ne demande ni inscription ni clé d’API. Choisissez une ligue et envoyez une requête :

Lister les clubs de la ligue LCAPB

```
curl -s -X POST https://frontis-gateway.pilotariak.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Pilotariak-League: lcapb" \
  -d '{"query":"{ clubs { id name } }"}'
```

## API GraphQL Frontis

- Endpoint : `https://frontis-gateway.pilotariak.com/graphql` (HTTP `POST`, corps JSON)
- Authentification : aucune — l’API est publique et en lecture seule
- En-tête obligatoire : `X-Pilotariak-League` = `lcapb` (Côte d’Argent), `lidfpb` (Île-de-France) ou `ctpb` (Comité Territorial)
- Requêtes : `clubs`, `club(id)`, `competitions`, `competition(id)`, `categories`, `category(id)`, `specialties`, `specialty(id)`, `results(competitionId, specialtyId, categoryId, phase)`, `result(id)`, `version`
- Schéma : l’introspection GraphQL est activée, tout client ou générateur de code GraphQL peut le charger
- Référence complète : [skill graphql-api](/.well-known/agent-skills/graphql-api/SKILL.md) · code source sur [GitHub](https://github.com/Pilotariak/frontis) 

## Serveur MCP Azkena

Azkena expose les mêmes données sous forme d’outils [Model Context Protocol](https://modelcontextprotocol.io) afin que des assistants comme Claude, Cursor ou Codex puissent les interroger en langage naturel. Endpoint : `https://mcp.pilotariak.com/mcp` (Streamable HTTP, protocole `2026-07-28`).

Outils : `list_competitions`, `list_clubs`, `list_categories`, `list_specialties`, `list_results`. Chaque outil prend un argument `league`.

Configuration d’un client MCP

```
{
  "mcpServers": {
    "pilotariak": {
      "type": "http",
      "url": "https://mcp.pilotariak.com/mcp"
    }
  }
}
```

## Authentification

L’API GraphQL et tous les documents de découverte de pilotariak.com sont publics. Le serveur MCP exige un jeton d’accès OAuth 2.1 : le client s’enregistre dynamiquement, une personne autorise l’accès sur l’écran de consentement, puis le client échange le code avec PKCE (S256). Une requête non authentifiée reçoit un `401` avec un en-tête `WWW-Authenticate` pointant vers les métadonnées de la ressource protégée.

Le guide pas à pas pour les agents se trouve dans [auth.md](/auth.md). Métadonnées : [ressource protégée (RFC 9728)](https://mcp.pilotariak.com/.well-known/oauth-protected-resource/mcp) · [serveur d’autorisation (RFC 8414)](https://mcp.pilotariak.com/.well-known/oauth-authorization-server).

## Erreurs

Les erreurs GraphQL suivent la spécification GraphQL : la réponse contient un tableau `errors`, chaque entrée avec un `message` lisible et un code machine `extensions.code` (`BAD_REQUEST`, `GRAPHQL_VALIDATION_FAILED`, …). Le serveur MCP renvoie des erreurs JSON comme `{"error":"invalid_token"}` avec les codes d’erreur OAuth standard.

En-tête de ligue manquant

```
{
  "errors": [{
    "message": "Missing X-Pilotariak-League header",
    "path": ["clubs"],
    "extensions": { "code": "BAD_REQUEST", "serviceName": "clubs" }
  }],
  "data": null
}
```

## Limites, versions et environnements

- Azkena autorise 60 requêtes par minute et par adresse IP ; au-delà il répond `429`.
- Frontis n’a pas de quota publié — mettez les réponses en cache et évitez les sondages trop fréquents.
- Vérifiez la version déployée de la passerelle avec la requête `{ version }` ; les changements sont listés dans les releases GitHub de chaque projet.
- Il n’y a pas de bac à sable séparé : toutes les interfaces sont en lecture seule, aucun appel ne peut modifier les données. 

## Découverte automatisée

- [llms.txt](/llms.txt) — présentation du site pour les modèles de langage (index développeurs : [/developers/llms.txt](/developers/llms.txt))
- [Catalogue d’API (RFC 9727)](/.well-known/api-catalog) · [description OpenAPI](/.well-known/openapi.json) des documents de découverte
- [Catalogue Agentic Resource Discovery](/.well-known/ard.json) · [carte du serveur MCP](/.well-known/mcp/server-card.json) · [carte d’agent A2A](/.well-known/agent-card.json)
- [Index des skills d’agent](/.well-known/agent-skills/index.json) — fichiers SKILL.md pour l’API GraphQL, le serveur MCP, les projets et le contexte sportif
- Chaque page existe en markdown : ajoutez `.md` (par exemple [/fr/developers.md](/fr/developers.md)) ou envoyez `Accept: text/markdown` 

## Code source et SDK

Tout est sous licence Apache-2.0 sur [github.com/Pilotariak](https://github.com/Pilotariak), y compris ce site ([Pilotariak/website](https://github.com/Pilotariak/website), avec un [AGENTS.md](https://github.com/Pilotariak/website/blob/main/AGENTS.md) pour les agents de code). Il n’existe pas de SDK dédié : n’importe quelle bibliothèque cliente GraphQL ou MCP fonctionne. Issues et pull requests bienvenues.