Reach120 MCP server

An MCP server that gives an AI agent a governed path to the Reach120 TOEFL iBT practice API: fetch Writing practice prompts, and score a learner's written response.

Reach120 is an independent practice platform. It is not affiliated with, endorsed by, or administered by ETS. TOEFL® is a registered trademark of ETS. Reach120 is not affiliated with, endorsed by, or approved by ETS.

Tools

Tool	What it does	Cost
list_practice_prompts	List Writing practice prompts, with the id used to score against one	Reads stored rows, runs no model
get_practice_prompt	Fetch one prompt with its full scenario or discussion context	Reads a stored row, runs no model
score_writing_response	Score a written response, returning an automated practice score and a short rationale	Runs the scorer; metered against your key

You bring the key

This server carries no credential. It forwards the key you place in REACH120_API_KEY and returns the API's answer unchanged.

That is a design decision, not an omission. Every limit that matters lives on the server side of the API and is evaluated on every call — a per-key request window, a per-key daily scoring allowance, and a service-wide spending gate. A client that enforced its own limits would only be enforcing them on people who chose to keep using the client, so this one enforces none and cannot be a way around any of them. Delete this package and call the endpoint directly and you get identical refusals.

There is no unauthenticated scoring path. An agent with no key receives a refusal naming where a key comes from, and nothing is sent.

Request a key and read the full limit, error-code and version policy at https://www.reach120.com/developers.

Install

This package is not published on npm. The install path is this repository, and it is the only one — @reach120/mcp-server does not resolve on the public npm registry and no other package name stands in for it.

npx -y github:reach120/reach120-mcp

npm compiles the TypeScript during that install through the prepare script, so there is no separate build step.

Or clone it and run it from source:

git clone https://github.com/reach120/reach120-mcp.git
cd reach120-mcp
npm install
npm run build
node dist/index.js

Configure

Claude Desktop (claude_desktop_config.json), Claude Code, or any MCP client that speaks stdio:

{
  "mcpServers": {
    "reach120": {
      "command": "npx",
      "args": ["-y", "github:reach120/reach120-mcp"],
      "env": {
        "REACH120_API_KEY": "r120_live_your_key_here"
      }
    }
  }
}

Variable	Required	Default	Meaning
REACH120_API_KEY	yes	—	Your Reach120 API key. Tools refuse without it.
REACH120_API_BASE_URL	no	https://www.reach120.com	Point at another deployment.
REACH120_API_TIMEOUT_MS	no	see readConfig in src/api.ts	Per-request timeout, in milliseconds.

What a refusal looks like

Limits refuse with a machine-readable code rather than degrading. A call that hits the key's daily allowance is not quietly scored on a cheaper engine and handed back as if it were the engine you asked for — the code names what happened, and the error table on /developers says what each one means.

Verify it locally

npm install
npm run build
npm run verify

npm run verify starts the built server over stdio, completes a real MCP handshake with the SDK client, prints the advertised tools, and calls one tool without a key to show the refusal path.

Scores are practice feedback

score_writing_response returns automated practice feedback produced by Reach120.

It is not an ETS score and is not reported on the official scale. This README deliberately does not name the scale the number is on: that fact is published beside a mandatory limitation the claims ledger requires, which a package page cannot render. The response shape is documented on https://www.reach120.com/developers.

TOEFL® is a registered trademark of ETS. Reach120 is not affiliated with, endorsed by, or approved by ETS.

Licence

MIT. See LICENSE.