MCP Integration

After this guide Claude Code, or any MCP client, can register an account, generate courses, grade answers, and check the balance as tools, with no HTTP code.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets an AI agent discover and call tools on a server. Your agent gets typed tools with descriptions instead of raw HTTP calls.

TutorFlow runs a hosted MCP server:

https://mcp.tutorflow.io/api/mcp

It is stateless, HTTPS only, and speaks the Streamable HTTP transport. It forwards your key to the TutorFlow API on each call. The only thing it keeps is each key's classroom, for a minute, under a hash of the key.

Authenticate

Send your key in the Authorization header when you connect:

Authorization: Bearer tf_content_...

Use a Content key (tf_content_) from registration (contentApiKey) or from the Agent Platform dashboard. A test key (tf_content_test_) works too, in the sandbox classroom and without spending credits. See Authentication.

Connect with Claude Code

Add the server to .mcp.json in your project root:

{
  "mcpServers": {
    "tutorflow": {
      "type": "http",
      "url": "https://mcp.tutorflow.io/api/mcp",
      "headers": {
        "Authorization": "Bearer tf_content_..."
      }
    }
  }
}

Restart Claude Code. The tools are available at once.

Connect from code

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 
const transport = new StreamableHTTPClientTransport(
  new URL('https://mcp.tutorflow.io/api/mcp'),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${process.env.TUTORFLOW_CONTENT_API_KEY}` },
    },
  },
);
 
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

Tools

Account and billing

These call the Agent Platform account routes, /v1/platform/agent/* and /v1/platform/pricing-catalog.

The account routes take only a live key, so with a test key these tools answer with an error saying the key is too narrow.

Content

These call the Content API in your account's default classroom. With a test key they work in the sandbox classroom. Each takes an optional classroomId to work somewhere else.

The server finds the default classroom by reading defaultClassroomId from GET /v1/platform/agent/account, and keeps it for a minute per key. A test key, which cannot call the account routes, finds the sandbox classroom with GET /v1/content/classrooms instead.

Modules, tests, slides, videos, and games have no MCP tools yet. Call the Content API for them; see Generate Your First Content.

Onboarding through MCP

An agent can go from nothing to a course without writing HTTP. Connect without an Authorization header for the first step.

1. Register

Tool: register_organization
{
  "name": "My AI Tutor",
  "slug": "my-ai-tutor",
  "email": "operator@example.com",
  "agentIdentity": "claude-opus via Claude Code"
}

The answer has the live tf_content_ key, the default classroom id, and 50 trial credits ($1.00). The key is shown once. Store it, then reconnect with Authorization: Bearer <key>.

Register once and keep the key. Register allows 5 attempts per IP per rolling hour, and the hosted server calls it from Vercel, so every register_organization call shares Vercel's outbound IPs with other MCP users. A 429 platform_rate_limit_exceeded here may come from someone else's attempts; wait Retry-After seconds, or register with a direct POST /v1/platform/agent/register from your own network.

2. Generate a course

Tool: create_course
{
  "prompt": "Beginner Python for adult career changers",
  "lessonCount": 5,
  "level": "beginner",
  "language": "en"
}

The answer has a runId. Generation takes a few minutes. prompt is sent to the Content API as topic.

3. Follow the run

Tool: get_course_generation
{ "runId": "00000000-0000-4000-8000-000000000b01" }

Call it again until the status is completed or failed. A completed run comes back with the course id and its editorUrl. Pass editorUrl on only if a person should review the course; they open it with their own TutorFlow sign-in.

4. Grade an answer

Tool: run_evaluation
{
  "evaluationType": "open_ended",
  "questionText": "Explain photosynthesis",
  "learnerAnswer": "Plants use sunlight to make glucose from CO2 and water.",
  "maxScore": 10,
  "learnerExternalId": "learner-42",
  "language": "en"
}

5. Buy credits when the trial runs out

When a content tool cannot be paid for, the API answers 402 content_payment_required and the tool asks for a checkout link itself. If the account email is verified, the answer carries that link: send it to the person who owns the account. If it is not, the tool answers with an error saying buying credits needs a verified email; have that person open the verification link (get_account shows Email verified), then call create_billing_session and send them the link. They choose $5 to $5,000 and pay through Stripe. Then retry the tool.

Tool: create_billing_session
{}

check_billing_status and get_account show the new balance once the payment is through.

Legacy tf_platform_ keys

The content tools (create_course, get_course_generation, list_courses, run_evaluation, and list_evaluations) need a tf_content_ key. Called with a tf_platform_ key, they answer with an error that says tf_platform_ keys no longer create or read content and points you to the Agent Platform dashboard to create a tf_content_ key. They no longer fall back to the old /v1/platform content routes, which were removed on 2026-10-16. To fix it, put a tf_content_ key in the Authorization header; nothing else in your configuration changes. See Migrating to the Content API.

Prices

get_pricing returns the live catalog. The content tools charge Content API prices: a course 3 credits plus 3 per lesson, an evaluation 1 credit, at 2 cents per credit. See Pricing and Billing.

Without MCP

Every tool is a REST call you can make yourself:

# Account
POST /v1/platform/agent/register
GET  /v1/platform/agent/account
GET  /v1/platform/agent/billing/status
POST /v1/platform/agent/billing/session
GET  /v1/platform/pricing-catalog
 
# Content, under /v1/content/classrooms/{classroomId}
POST /courses/generate
GET  /runs/{runId}
GET  /courses
POST /evaluations
GET  /evaluations

See the Content API Reference for every route.