intersective practera mcp server

An MCP (Model Context Protocol) server that gives AI agents direct access to Practera's GraphQL API and local project brief data. Connect Cursor, Claude Desktop, or any MCP client to author learning programs, manage assessments, submit work as a learner, conduct reviews, and run test suites across the Practera monorepo.

With this MCP server, an agent can:

• Analyse and restructure existing projects for different audiences or grade levels
• Generate assessment blueprints and create questions automatically
• Import/export programs between institutions or LMS data formats
• Submit assessments and manage review workflows
• Search a library of 5400+ experiential learning project briefs by skill
• Run test suites across all Practera repos directly from Cursor

1. Clone this repo alongside the other Practera repos.
2. Install dependencies: npm install
3. Add .cursor/mcp.json to any Practera repo (see Cursor Configuration).
4. Reload the Cursor MCP panel — the practera server will appear.

No separate server process needed. Cursor spawns the MCP server via stdio automatically.

Cursor spawns the server as a subprocess. No separate npm run dev needed.

# For manual testing / debugging
npm run dev:stdio

An HTTP server with Server-Sent Events — use when multiple clients share one instance.

npm run dev        # → http://localhost:3000/sse

Connect an MCP client to http://localhost:3000/sse.

Create .cursor/mcp.json in your repo (or add to ~/.cursor/mcp.json for all workspaces):

{
  "mcpServers": {
    "practera": {
      "command": "node",
      "args": [
        "/absolute/path/to/practera-mcp-server/dist/stdio.js"
      ],
      "env": {
        "PRACTERA_REGION": "local",
        "AUTH_EMAIL": "your@email.com",
        "GRAPHQL_URL": "http://localhost:8000",
        "WORKSPACE_ROOT": "/absolute/path/to/practera-workspace"
      }
    }
  }
}

Run npm run build in practera-mcp-server after any source changes to rebuild dist/stdio.js.

For production regions, omit AUTH_EMAIL/GRAPHQL_URL and pass apikey in each tool call instead.

Pass apikey in each tool call. The key is forwarded as the apikey HTTP header to the GraphQL API.

Omit apikey and set AUTH_EMAIL (or pass email per tool call). The server calls the devLogin GraphQL mutation to obtain a JWT automatically. Only works with region=local or region=stage.

# Build
npm run build       # compiles TS + copies src/data → dist/

# Run SSE server (compiled)
npm start

# Run stdio (compiled — use in production Cursor config)
npm run start:stdio

The apprunner.yaml configures an App Runner service running the SSE server on port 80.

serverless.yml exists but the Lambda handler export is not currently wired up. Use App Runner for production deployment.

• GraphQL read access (project, assessment)
• Author CRUD tools (create experience, milestone, activity, assessment, questions, tasks, enroll)
• Import/export experience JSON
• Student tools (list, submit, feedback)
• Reviewer tools (list pending, submit review)
• Project brief search (5400+ briefs, skill-based)
• stdio transport for Cursor integration
• run_tests tool for cross-repo test execution
• Metrics API (generate LLM-readable reports from calculateMetrics)
• OAuth 2.1 (currently scaffolded, not active)
• Thread auth context through MCP Resources
• assign_reviewer, handle_review tools for reviewer workflow management
• Media asset generation

MIT