Learn++ logo
Learn++ alpha testing
Try examples Request alpha access

Learn++ documentation

Learn++ MCP Agent API Connection Guide

Connection guide for external AI agents using the Learn++ MCP Agent API.

Request alpha access Try tutorials
Learn++ app homepage screen

This guide is for external AI agents that receive:

  • a Learn++ API URL
  • a token (either user Firebase ID token or agent session token)

Use this guide to connect successfully on the first try.

1) Canonical API base URL

Production base URL:

https://api.learnplusplus.online/agent-api

All documented endpoints below are relative to this base.

Important

  • There is currently no Swagger/OpenAPI UI at /docs or /swagger.
  • Requesting unknown routes (including the API root) returns:

{"error":"Not found"}.

  • Do not probe random paths; call the documented /v1/* endpoints directly.

2) Auth modes

A) User token mode

Use a user Firebase ID token:

Authorization: Bearer <firebase-id-token>

This token can call user endpoints and can authorize an agent session.

  1. Use a user token once to call POST /v1/agents/authorize.
  2. Read session.token from the response.
  3. Use that token for MCP calls:

Authorization: Bearer <agent-session-token>

Agent session tokens are short-lived and scope-limited.

3) Endpoint map

Health / account surfaces

  • GET /v1/entitlements
  • GET /v1/ai/status
  • GET /v1/agents
  • GET /v1/usage
  • POST /v1/redeem_activation_code
  • POST /v1/agents/authorize
  • POST /v1/agents/revoke

MCP discovery and execution

  • GET /v1/mcp/tools
  • GET /v1/mcp/resources
  • GET /v1/mcp/resource?uri=<resource-uri>
  • POST /v1/mcp/call

4) MCP tools currently available

Read tools:

  • search_examples
  • get_example
  • get_lesson
  • list_lessons
  • get_lesson_assets
  • list_languages
  • get_user_entitlements
  • get_user_progress

Write tools:

  • save_progress
  • create_study_plan
  • compile_code (optional/premium code execution)
  • redeem_activation_code

5) Scope policy (agent session tokens)

  • read:lessons
  • lesson/example/language tools
  • MCP discovery/read endpoints (/v1/mcp/tools, /v1/mcp/resources, /v1/mcp/resource)
  • read:entitlements
  • get_user_entitlements, get_user_progress
  • write:progress
  • save_progress, create_study_plan
  • write:code_execute
  • compile_code
  • Requires code-execution access; connected agents should request it only when they need to run code.
  • write:redeem_activation_code
  • redeem_activation_code

6) Copy-paste examples

6.1 Authorize an agent (user token)

curl -sS -X POST 'https://api.learnplusplus.online/agent-api/v1/agents/authorize' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <firebase-id-token>' \
  -d '{
    "agentName": "External MCP Agent",
    "scopes": ["read:lessons", "read:entitlements", "write:progress"]
  }'

6.2 Discover MCP tools (agent session token)

curl -sS 'https://api.learnplusplus.online/agent-api/v1/mcp/tools' \
  -H 'Authorization: Bearer <agent-session-token>'

6.3 Call an MCP tool (agent session token)

curl -sS -X POST 'https://api.learnplusplus.online/agent-api/v1/mcp/call' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <agent-session-token>' \
  -d '{
    "tool": "list_lessons",
    "args": {"language": "cpp", "limit": 5}
  }'

6.4 Read an MCP resource

curl -sS 'https://api.learnplusplus.online/agent-api/v1/mcp/resource?uri=learnpp://catalog/asset-manifest' \
  -H 'Authorization: Bearer <agent-session-token>'

7) Troubleshooting

If you receive {"error":"Not found"}:

  1. Verify your base URL is exactly https://api.learnplusplus.online/agent-api.
  2. Verify you are calling a documented /v1/... route.
  3. Do not use /docs or /swagger (not available on this API).

If POST /v1/agents/authorize fails with AI entitlement required:

  • The user needs an active AI entitlement before connecting an agent.

If MCP calls fail with authorization/scope errors:

  • Ensure the agent was authorized with required scopes.
  • Re-authorize the agent and use the fresh session.token.
  • For compile_code, include write:code_execute; otherwise the API returns structured JSON 403 with requiredScope.

For broader product docs and trust pages, start from the documentation hub: