MCP Integration

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents discover and call tools exposed by a server. Instead of writing raw HTTP calls, your agent gets structured tools it can invoke directly, with typed inputs, validation, and clear descriptions.

TutorFlow provides a hosted MCP server so Claude Code and any other MCP-compatible agent or client can integrate with the platform in minutes.

MCP Server

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

The server is stateless, HTTPS-only, and accepts requests over the Streamable HTTP transport.

Connect with Claude Code

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

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

Restart Claude Code. The tools become available immediately.

Connect Programmatically

Any MCP client can connect using the Streamable HTTP transport:

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 tf_platform_...' },
    },
  },
);
 
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

Available Tools

Tools that require an API key read it from the Authorization: Bearer header passed when connecting.

Agent Onboarding Flow via MCP

An agent can complete the entire onboarding without any HTTP knowledge:

Step 1: Register

Tool: register_workspace
{
  "name": "My AI Tutor",
  "slug": "my-ai-tutor",
  "email": "agent@example.com",
  "agentIdentity": "claude-3-5-sonnet"
}

Returns an API key. Store the key. It is shown only once.

Step 2: Verify Email

After registration, the workspace must verify its email before making API calls. A verification email is sent automatically. The recipient clicks the link to verify. Until verified, API calls return a 403 error with code email_verification_required.

Step 3: Run an Evaluation

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

On the first call without credits the server returns a checkout page URL instead of a result. Forward that URL to a human operator to purchase credits.

Step 4: Purchase Credits

Tool: create_billing_session
{}

Returns a url field pointing to a TutorFlow-hosted checkout page. Send this URL to a human (via Slack, email, or any channel). The human opens the page, chooses how much to add ($5 minimum, $5,000 maximum), and is then redirected to Stripe to complete payment. No card data passes through the agent or TutorFlow servers.

Step 5: Verify and Retry

Tool: check_billing_status
{}

Once hasPaymentMethod is true, retry run_evaluation to get the actual result:

{
  "evaluationId": "uuid",
  "status": "COMPLETED",
  "score": 8,
  "maxScore": 10,
  "feedbackSummary": "Strong grasp of the concept..."
}

Pricing

Call get_pricing to retrieve live pricing at any time.

Without MCP: REST API

Prefer raw HTTP? Every tool maps 1:1 to a REST endpoint:

# register
POST /v1/platform/agent/register
 
# evaluate
POST /v1/platform/evaluations
 
# billing session
POST /v1/platform/agent/billing/session
 
# billing status
GET  /v1/platform/agent/billing/status

See the Agent Self-Service Onboarding guide for the full REST flow.