---
title: "Developers: API, MCP server and agent access"
description: "txt for building on the TCF Canada and TEF Canada content, with the authentication, idempotency and deprecation rules that apply."
canonical: https://francaisprep.com/developers
last-updated: 2026-09-30
---

Developers

# Build on the TCF Canada and TEF Canada content.

Everything Français Prep publishes for candidates is also available to programs and AI agents: an OpenAPI-described REST API, an MCP server, an NLWeb ask endpoint and a markdown twin of every page. Read access is public. Score conversion is a table lookup you can audit, never a model guess.

## REST API and OpenAPI spec

Full-text search over the preparation pages, page bodies, course tiers and the booking entry point. Every read endpoint is public; no key is needed.

[openapi.json](https://api.francaisprep.com/openapi.json)

## Interactive API reference

The same spec rendered as browsable documentation with example requests and responses for each operation.

[docs/reference](https://api.francaisprep.com/docs/reference)

## MCP server

Ten read-only tools over Streamable HTTP, including convert\_score, a fixed table lookup from TCF or TEF section scores to NCLC levels. Works without authentication.

[server card](https://mcp.francaisprep.com/.well-known/mcp/server-card.json)

## NLWeb ask endpoint

POST a natural-language question and receive ranked pages as JSON, or as Server-Sent Events when you ask for text/event-stream.

[/ask](https://francaisprep.com/ask)

## Markdown twins and llms.txt

Append .md to any page URL, or send Accept: text/markdown. Each twin opens with frontmatter and every HTML page advertises its twin with a Link header.

[/llms.txt](https://francaisprep.com/llms.txt)

## Authentication

Only the signed-in candidate's account endpoints need a bearer key. The auth.md walkthrough follows the WorkOS convention and the OAuth discovery metadata points at it.

[/auth.md](https://francaisprep.com/auth.md)

## Quick start

Four requests, no credentials.

\# Search the preparation pages
curl "https://api.francaisprep.com/v1/content/search?query=nclc+7+tcf&locale=en"

# Ask a question, JSON answer
curl -X POST https://francaisprep.com/ask \\
  -H "content-type: application/json" -H "accept: application/json" \\
  -d '{"query": "how is TEF Canada expression orale marked"}'

# Convert all four results with a plain GET
curl "https://api.francaisprep.com/v1/score/convert?exam=tcf\_canada&listening=512&reading=470&writing=12&speaking=11"

# Convert a score over MCP
curl -X POST https://mcp.francaisprep.com/mcp \\
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"convert\_score","arguments":{"exam":"tcf\_canada","skill":"listening","score":523}}}'

MCP tools available: search\_prep\_content, read\_prep\_page, get\_exam\_info, convert\_score, list\_course\_tiers, get\_booking, get\_practice\_questions, check\_answer, get\_flashcards, list\_practice\_topics.

## Policies you can rely on

### Versioning

Public endpoints live under a versioned path (https://api.francaisprep.com/v1/...). Additive changes, such as new optional fields or new endpoints, ship within a version. Anything that removes or renames a field, changes a type, or changes an error code starts a new version path.

### Deprecation

A deprecated operation keeps working for at least six months after the notice. During that window responses carry Deprecation and Sunset headers (RFC 9745 and RFC 8594) with the retirement date, the OpenAPI operation is marked deprecated, and the change is listed on this page. Nothing is removed without both signals.

### Idempotency

Write operations accept an Idempotency-Key header. Retrying with the same key returns the stored response with Idempotent-Replayed: true instead of repeating the side effect. Keys are scoped to the caller and expire after 24 hours.

### Errors and limits

Errors are JSON with a human-readable error, a machine-readable code and the request\_id to quote when reporting a problem. Rate limits are advertised in RateLimit-\* headers; a 429 or 402 carries Retry-After.

Questions, or a use case the API does not cover yet? Write to [bonjour@francaisprep.com](mailto:bonjour@francaisprep.com) or see the [contact page](/contact).

---

For agents: site index https://francaisprep.com/llms.txt, developer access https://francaisprep.com/developers, and TCF or TEF to NCLC conversion over a plain GET at https://api.francaisprep.com/v1/score/convert?exam=tcf_canada&listening=512&reading=470&writing=12&speaking=11 (exam is tcf_canada or tef_canada).