Integration

OAuth & MCP documentation

Mynawoo Practice MCP exposes scoped OAuth endpoints and a remote MCP server so ChatGPT and other MCP-compatible AI apps can read learning context, generate private grammar exams, manage Leitner vocabulary cards, and review analytics after user approval.

Public endpoints

MCP endpoint

https://api.mynawoo.com/mcp

Authorization metadata

https://api.mynawoo.com/.well-known/oauth-authorization-server

Protected resource metadata

https://api.mynawoo.com/.well-known/oauth-protected-resource

MCP resource metadata

https://api.mynawoo.com/.well-known/oauth-protected-resource/mcp

Authorization endpoint

https://api.mynawoo.com/oauth/authorize

Token endpoint

https://api.mynawoo.com/oauth/token

Token revocation

https://api.mynawoo.com/oauth/revoke

Dynamic client registration

https://api.mynawoo.com/oauth/register

Scopes

learning:read — Read courses, lessons, grammar screens, and lesson progress.
exams:read — Read AI-generated grammar exams and previous grammar mistakes.
exams:write — Save or delete private grammar exams generated through connected AI apps.
leitner:read — Read Leitner sets, today practice words, and difficult vocabulary.
leitner:write — Create Leitner sets and save or edit MCP-generated vocabulary cards.
analytics:read — Read learning analytics, weakness context, and saved coaching suggestions.
analytics:write — Save AI coaching suggestions for the authenticated user.

Connector setup

Add https://api.mynawoo.com/mcp as the remote MCP endpoint.
Complete OAuth authorization with PKCE.
Approve the requested scopes on the Mynawoo consent screen.
Test get_current_learning_state or list_courses.
Load a grammar screen, confirm the lesson target, save a private exam, then review analytics or Leitner cards.

ChatGPT app behavior

After the user approves OAuth consent, ChatGPT can call only the Mynawoo tools allowed by the approved scopes. Read scopes allow course, lesson, grammar, Leitner, and analytics access. Write scopes allow saving private grammar exams, vocabulary cards, Leitner sets, coaching suggestions, and delete or archive actions for MCP-generated content. Connected AI apps do not submit exam answers for the user; answers are submitted only inside Mynawoo.

Security notes

Mynawoo uses authorization code flow with PKCE, scoped OAuth grants, refresh-token rotation, token revocation, idempotency protection for write tools, and audit logging for MCP tool calls.

Reviewer account

Directory reviewers should receive test credentials through the submission form. The reviewer account should include at least one active course, one grammar lesson, one Leitner set, and some learning history so read, write, analytics, and delete or archive tools can be tested end to end.

Troubleshooting

Authorization fails

Make sure the user is signed in to the correct Mynawoo account, the redirect URI is valid, and the OAuth client requested supported scopes.

Exam save is rejected

Confirm the user explicitly approved the course, level, unit, and lesson shown by get_grammar_screen_content, then pass matching confirmed_* fields to save_ai_grammar_exam.

Delete or archive returns archived instead of deleted

Exams and vocabulary cards created before today, or content not marked deletable today, may only be archived from MCP. Use the returned exam_code or card_id from the create step in the same review run.