AI Agent Integration

StudyPlug is designed to be consumed by AI agents. There are three integration paths depending on your agent platform: MCP for Claude-compatible agents, OpenAPI for GPT-based agents, and direct REST for custom agents.

1. MCP + Claude Desktop

The Model Context Protocol (MCP) lets Claude Desktop, Cursor, Windsurf, and other MCP-compatible agents call StudyPlug tools natively.

Configure Claude Desktop

Note

The @studyplug/mcp-server npm package is not yet published. During the beta, use the Running from Source instructions to build and run locally. The npx config below will work once the package is published.

Add StudyPlug to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "studyplug": {
      "command": "npx",
      "args": ["@studyplug/mcp-server"]
    }
  }
}

Restart Claude Desktop. You now have four tools available:

Tool	What It Does
browse_curriculum	Discover grades, subjects, topics, and skills
generate_problems	Generate practice problems for a skill
find_by_standard	Find skills by CCSS or NGSS standard code
get_skill_info	Get detailed metadata about a specific skill

Example Prompts

Try these prompts in Claude Desktop after connecting the MCP server:

“Generate 5 addition problems for grade 2.”

Claude will call browse_curriculum to find the right skill, then generate_problems with the skill slug. The result is formatted text with problems and answers.

“What skills align to standard 3.OA.C.7?”

Claude calls find_by_standard with code 3.OA.C.7 and returns matching skills with descriptions.

“Create a 10-problem multiplication quiz for grade 4, seed 99.”

Claude calls generate_problems with skill: "multiply-by-6", grade: "grade-4", count: 10, seed: 99.

MCP Tool Call Example

Under the hood, Claude sends a tool call like this:

{
  "name": "generate_problems",
  "arguments": {
    "skill": "add-within-20",
    "grade": "grade-2",
    "count": 5,
    "seed": 42
  }
}

The MCP server uses StudyPlug’s core generators directly (no HTTP round-trip) and returns formatted text.

2. OpenAPI + ChatGPT

ChatGPT custom GPTs and other OpenAPI-aware agents can discover and call the StudyPlug REST API automatically.

Point to the OpenAPI Spec

The spec is available at:

https://api.studyplug.org/api/v1/openapi.json

When creating a custom GPT, paste this URL in the Actions configuration. ChatGPT will import all endpoints and their schemas automatically.

What the Agent Sees

The OpenAPI spec includes x-agent-hint extensions on key endpoints. These provide natural-language guidance that helps the agent choose the right endpoint and parameters:

{
  "x-agent-hint": "Use this endpoint to generate practice problems. Start by browsing /skills to find the right skill slug, then POST here with the skill and count."
}

Example GPT Interaction

User: “Give me 8 fraction problems for a 5th grader.”

GPT actions:

1. GET /api/v1/skills?grade=grade-5&subject=math — find fraction skills
2. POST /api/v1/generate with { "skill": "add-fractions-diff-denom", "grade": "grade-5", "count": 8 }
3. Format the response and present it to the user

3. Direct REST API

Any agent or script can call the API directly. No SDK or MCP server required.

Browse the Catalog

# List all Grade 3 math skills
curl -s "https://api.studyplug.org/api/v1/skills?grade=grade-3&subject=math" \
  | jq '.data.skills[] | {slug, name}'

Generate Content

curl

curl -X POST https://api.studyplug.org/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "skill": "add-within-20",
    "grade": "grade-2",
    "count": 5,
    "seed": 42
  }'

Python

import requests

resp = requests.post(
    "https://api.studyplug.org/api/v1/generate",
    json={
        "skill": "add-within-20",
        "grade": "grade-2",
        "count": 5,
        "seed": 42,
    },
)
data = resp.json()["data"]
for item in data["items"]:
    c = item["content"]
    print(f"{c['operand1']} + {c['operand2']} = ?")

Generate a Single Item

curl -X POST https://api.studyplug.org/api/v1/generate/single \
  -H "Content-Type: application/json" \
  -d '{"skill": "multiply-by-3", "grade": "grade-3"}'

Tip

For agent workflows, the /generate/single endpoint is useful when you need one problem at a time in a conversational loop. Use /generate with count for batch generation.

Discovery Endpoints for Agents

The API also provides machine-readable discovery files:

URL	Purpose
https://api.studyplug.org/api/v1/openapi.json	Full OpenAPI 3.1 specification
https://api.studyplug.org/llms.txt	LLM-friendly plain text description of the API
https://api.studyplug.org/.well-known/ai-plugin.json	ChatGPT/agent plugin manifest

Choosing an Integration Path

Path	Best For	Latency	Setup
MCP Server	Claude Desktop, Cursor, Windsurf	Lowest (in-process)	npm install + config file
OpenAPI + GPT	ChatGPT custom GPTs, OpenAPI agents	Medium (HTTP)	Paste spec URL
Direct REST	Custom agents, scripts, any language	Medium (HTTP)	None — just HTTP calls

Next Steps

• MCP Installation — full MCP server setup guide
• MCP Tools Reference — detailed documentation for all 4 MCP tools
• Quickstart — first API call in 5 minutes
• Content Items — understand what the API returns