Study plan template MCP

Platform admins can connect external AI tools (for example Cursor or Claude Desktop) to Garrison’s study plan template MCP server. The server exposes read-only rubric and template lookup plus optional AI-assisted draft, review, and step-instruction tools—the same capabilities as the admin UI assistant, callable from an MCP client.

Cross-links: Study plans (designer), Study plans (planning), AI guidelines, Admin study plan AI.

What it is

Item	Value
Protocol	Model Context Protocol over HTTP
Server name	`study-plan-templates`
HTTP endpoint	`POST {APP_URL}/mcp/study-plan-templates`
Transport	Streamable HTTP (JSON-RPC)
Audience	Platform admins only

Example endpoint (local dev with bin/start):

https://api.garrison.test/mcp/study-plan-templates

Replace the host with your deployment’s public API URL in production.

Authentication

MCP clients cannot use the web app’s session cookies. Send an API token as a Bearer header:

Authorization: Bearer {plain-text-token}

Requirements:

Create the token on Profile → API tokens and select the Study plan MCP server permission (mcp:study-plan-templates).
The token’s user must be a platform admin (is_platform_admin).
The MCP route rejects tokens that do not include the study-plan MCP scope.
Other permissions you add to the same token in the future will apply only where those scopes are accepted—this route checks the study-plan scope only.

AI generation tools also require the admin_study_plan_ai feature flag (see below).

Unauthenticated requests receive 401 with a WWW-Authenticate: Bearer header. Non-admin users or tokens without the required scope receive 403.

Create and revoke tokens

Sign in as a platform admin.
Open Profile → API tokens.
Enter a name (for example Cursor laptop).
In the permissions tree, check Study plan MCP server (under Study plan templates).
Create token and copy the plain-text value immediately—it is shown once.
Revoke unused tokens from the same section.

Token lifetime defaults to 90 days (API_TOKEN_EXPIRATION_DAYS in api/.env).

GraphQL	Purpose
`apiTokenScopeTree`	Permission tree for the signed-in user
`apiAccessTokens`	List your API tokens (metadata only)
`createApiAccessToken(name, scopes)`	Issue a token; returns `plainTextToken` once
`revokeApiAccessToken(id)`	Revoke by token id

Available scopes are defined in config/api_tokens.php. New integrations add entries there and wire route middleware or resolver checks to the scope key.

Scope	Who can assign	Used for
`studies:read`	Any signed-in user	GraphQL `studies` and `study` queries with a bearer token
`mcp:study-plan-templates`	Platform admin	Study plan template MCP server (`POST /mcp/study-plan-templates`)

Feature flag and AI provider

Requirement	Config
AI tools enabled	Feature flag `admin_study_plan_ai` must be on (`feature_flags.default_enabled`)
LLM provider	`config/study_plan_ai.php` / `STUDY_PLAN_AI_*` env vars (default Ollama in dev)

Read-only tools (get-study-plan-template, rubric resource, review when AI is on) still require platform admin auth. AI generation tools are hidden from MCP tool lists when the feature flag is off.

Usage is logged to ai_usage like GraphQL AI mutations.

MCP client configuration

Add a server entry pointing at the HTTP endpoint and your Bearer token.

Cursor (api/.mcp.json, copied from .mcp.json.example):

{
  "mcpServers": {
    "study-plan-templates": {
      "url": "https://api.garrison.test/mcp/study-plan-templates",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_FROM_PROFILE"
      }
    }
  }
}

Use the API container’s reachable URL from your machine. For local dev with bin/start, https://api.garrison.test is typical.

Reload MCP in the client after saving. The server advertises name study-plan-templates and version 0.1.0.

Available MCP surface

Tool names use kebab-case derived from the server registration.

Tools

Tool	Read-only	Feature flag	Description
`get-study-plan-template`	Yes	—	Load a template by `id` (UUID) or `slug`, including unpublished drafts
`generate-study-plan-template-draft`	No	`admin_study_plan_ai`	Wizard brief → unpublished template draft (JSON)
`review-study-plan-template`	Yes*	`admin_study_plan_ai`	Rubric review; criticism only, no rewrites
`generate-study-plan-step-instructions`	No	`admin_study_plan_ai`	Markdown for one step and instruction lane

*Review calls the LLM but does not mutate stored templates.

`get-study-plan-template`

Argument	Type	Required	Notes
`id`	string (UUID)	One of `id` / `slug`	Template primary key
`slug`	string	One of `id` / `slug`	Template slug

Returns JSON: metadata, participation flags, and steps with lane markdown fields.

`generate-study-plan-template-draft`

Argument	Type	Required
`studyMethod`	string	Yes — e.g. `Topical`, `Book`
`spiritualPhases`	string[]	Yes — e.g. `["Milk"]`
`focusKind`	string	Yes
`focusValue`	string	No
`variant`	string	No
`supportsMentoredParticipation`	boolean	Yes
`supportsIndividualParticipation`	boolean	Yes
`goals`	string	Yes — author brief
`referenceTemplateId`	string (UUID)	No
`referenceUrls`	string[]	No — up to three URLs

Returns an unpublished draft (isPublished: false). Same shape as GraphQL generateStudyPlanTemplateDraft.

`review-study-plan-template`

Accepts a full template draft: slug, title, description, studyMethod, spiritualPhases, focusKind, focusValue, variant, isPublished, participation flags, sortOrder, and steps[] (stepKey, title, optional instruction fields, position).

Returns { findings: [{ severity, category, message, stepIndex?, suggestion? }] }. Categories use rubric slugs.

`generate-study-plan-step-instructions`

Template context plus: stepIndex, stepKey, stepTitle, instructionRole (individual | mentee | mentor), optional currentInstructions, and required intent.

Returns { instructionsMarkdown: "…" }.

Resources

URI	MIME	Description
`garrison://study-plan/rubric`	`application/json`	Rubric dimensions (`slug`, `title`, `description`, `aiInstructions`, `sortOrder`)

Prompts

Prompt	Arguments	Description
`study-plan-template-authoring`	`goal` (optional)	System context: rubric, guardrails, optional author goal

Operator checklist

Confirm admin_study_plan_ai is enabled if operators need AI tools.
Configure STUDY_PLAN_AI_* / Ollama (or other provider) on the API service.
Ensure the API URL is reachable from the operator’s workstation (TLS, firewall, Traefik).
Platform admin creates an API token on Profile → API tokens with the study-plan MCP permission.
Configure the MCP client with url + Authorization: Bearer ….
Revoke tokens when a device or client is decommissioned.

Troubleshooting

Symptom	Cause	Fix
HTTP `500` on connect	MCP streamable HTTP requires `Accept: application/json, text/event-stream`. Clients that omit it used to crash the transport.	Upgrade API (middleware normalizes Accept) or add the header in `mcp.json`.
HTTP `504` on AI tools	Edge gateway timeout is shorter than study-plan AI runs (draft up to ~6 minutes with queue buffer).	Enable `httpRoute.mcpExtendedTimeout` in Helm (see `values-production.example.yaml`), or raise proxy timeouts on your Gateway / CDN for `/mcp/*`.
MCP tool error: timed out waiting for AI queue	Queue worker not running, GPU saturated, or inference slower than agent timeout.	Confirm `queue` deployment is healthy; check `STUDY_PLAN_AI_*` and Ollama; review `ai_usage` logs.
HTTP `403` from scripts / bots	Some CDNs block default Python or empty `User-Agent` on GraphQL.	Send a normal `User-Agent` header (Cursor and browsers are fine).

AI generation tools block the MCP HTTP request until the queued agent finishes. Read-only tools (get-study-plan-template, rubric) return quickly.

File	Purpose
`api/config/api_tokens.php`	Permission scopes, groups, token expiry
`api/config/mcp.php`	MCP route path and required scope key
`api/routes/ai.php`	Web route registration and middleware
`api/.mcp.json.example`	Example Cursor MCP config
`api/.env.example`	`API_TOKEN_EXPIRATION_DAYS`

Implementation reference: App\Mcp\Servers\StudyPlanTemplateServer in the API package.