# Developers — Pilotariak GraphQL API & MCP server | Pilotariak

> Pilotariak developer portal: the public Frontis GraphQL API and the Azkena MCP server for Basque pelota data. Endpoints, authentication, quickstart and errors.

Developers

# Pilotariak developer portal

Pilotariak publishes Basque pelota data — clubs, competitions, categories, specialties and match results — through two free, open-source interfaces: the **Frontis GraphQL API** for applications and the **Azkena MCP server** for AI assistants. Both are read-only.

## Quickstart

No sign-up or API key is needed for the GraphQL API. Pick a league and send a query:

List clubs in the LCAPB league

```
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 } }"}'
```

## Frontis GraphQL API

- Endpoint: `https://frontis-gateway.pilotariak.com/graphql` (HTTP `POST`, JSON body)
- Authentication: none — the API is public and read-only
- Required header: `X-Pilotariak-League` = `lcapb` (Côte d’Argent), `lidfpb` (Île-de-France) or `ctpb` (Comité Territorial)
- Queries: `clubs`, `club(id)`, `competitions`, `competition(id)`, `categories`, `category(id)`, `specialties`, `specialty(id)`, `results(competitionId, specialtyId, categoryId, phase)`, `result(id)`, `version`
- Schema: standard GraphQL introspection is enabled, so any GraphQL client or code generator can load it
- Full reference: [graphql-api skill](/.well-known/agent-skills/graphql-api/SKILL.md) · source on [GitHub](https://github.com/Pilotariak/frontis) 

## Azkena MCP server

Azkena exposes the same data as [Model Context Protocol](https://modelcontextprotocol.io) tools so assistants such as Claude, Cursor or Codex can query it in natural language. Endpoint: `https://mcp.pilotariak.com/mcp` (Streamable HTTP, protocol `2026-07-28`).

Tools: `list_competitions`, `list_clubs`, `list_categories`, `list_specialties`, `list_results`. Every tool takes a `league` argument.

MCP client configuration

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

## Authentication

The GraphQL API and every discovery document on pilotariak.com are public. The MCP server requires an OAuth 2.1 access token: clients register dynamically, a person approves access on the consent screen, and the client exchanges the code with PKCE (S256). An unauthenticated request returns `401` with a `WWW-Authenticate` header pointing at the protected-resource metadata.

The step-by-step agent walkthrough is in [auth.md](/auth.md). Metadata: [protected resource (RFC 9728)](https://mcp.pilotariak.com/.well-known/oauth-protected-resource/mcp) · [authorization server (RFC 8414)](https://mcp.pilotariak.com/.well-known/oauth-authorization-server).

## Errors

GraphQL errors follow the GraphQL specification: the response carries an `errors` array, each entry with a human-readable `message` and a machine-readable `extensions.code` (`BAD_REQUEST`, `GRAPHQL_VALIDATION_FAILED`, …). The MCP server returns JSON errors such as `{"error":"invalid_token"}` with standard OAuth error codes.

Missing league header

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

## Rate limits, versions and environments

- Azkena allows 60 requests per minute per client IP; beyond that it answers `429`.
- Frontis has no published quota — cache responses and avoid tight polling loops.
- Check the deployed gateway version with the `{ version }` query; changes are listed in each project’s GitHub releases.
- There is no separate sandbox: all interfaces are read-only, so no call can modify data. 

## Machine-readable discovery

- [llms.txt](/llms.txt) — site overview for language models (developer index: [/developers/llms.txt](/developers/llms.txt))
- [API catalog (RFC 9727)](/.well-known/api-catalog) · [OpenAPI description](/.well-known/openapi.json) of the discovery documents
- [Agentic Resource Discovery catalog](/.well-known/ard.json) · [MCP server card](/.well-known/mcp/server-card.json) · [A2A agent card](/.well-known/agent-card.json)
- [Agent skills index](/.well-known/agent-skills/index.json) — SKILL.md files for the GraphQL API, MCP server, projects and sport context
- Every page has a markdown version: append `.md` (for example [/developers.md](/developers.md)) or send `Accept: text/markdown` 

## Source code and SDKs

Everything is Apache-2.0 on [github.com/Pilotariak](https://github.com/Pilotariak), including this website ([Pilotariak/website](https://github.com/Pilotariak/website), with an [AGENTS.md](https://github.com/Pilotariak/website/blob/main/AGENTS.md) for coding agents). There is no dedicated SDK: any GraphQL or MCP client library works. Issues and pull requests are welcome.