MCP tools | CourseMCP

Connection

Use Streamable HTTP at https://coursemcp.com/mcp. Your MCP client handles initialization and tool calls.

Connect the server, then follow your client's browser sign-in and authorization prompt. OAuth discovery and dynamic client registration are supported. You do not need to paste an access token. See the setup guide for client instructions.

Call tools/list for the current tool schemas. Search first, read selected passages for context, and request original pages when the text is insufficient. Course discovery is optional when you already know the course ID.

list_courses

Discover imported courses and indexing coverage. Skip this when a course_id is already known; search can search all your courses.

No arguments. Returns imported courses with IDs and indexing coverage.

Example tools/call params

{
  "name": "list_courses",
  "arguments": {}
}

search

Find course evidence or named files. Auto handles numbered sources and questions (e.g. question 6 from assignment 2), practice, and topic searches. Defaults: 3 results, 4000 excerpt characters; metadata is additional. Scope with course_id or resource_id. Read selected chunk_ids for more context. evidence_role labels each passage direct, related, or historical; these are retrieval heuristics, not verification. related_only cannot support an answer alone; past papers do not establish current exam policy. Browse with target:resources and course_id, no query. kind/module_name require target:resources.

course_id: string · uuid
cursor: integer · default: 0 · min: 0 · max: 250
kind: string · one of: file, page, assignment, announcement, syllabus, module
limit: integer · default: 3 · min: 1 · max: 10
max_chars: integer · default: 4000 · min: 2000 · max: 16000
module_name: string · min length: 1 · max length: 1000
query: string · min length: 2 · max length: 500
resource_id: string · uuid
target: string · one of: auto, content, resources, questions · default: auto

Example tools/call params

{
  "name": "search",
  "arguments": {
    "query": "question 6 from assignment 2"
  }
}

read

Read up to six selected chunk_ids together, or page through a resource_id. By default, question reads follow up to two continuation chunks and stop before a different question; other passages get one following chunk. Set after explicitly (0–2) for broader or narrower context. before defaults to 0. Shared citations and overlapping chunks appear once. max_chars bounds total passage text. Resume remaining items with chunk_ids:[chunk_id], text_offset, after:0; follow next for source pagination. Prefer selected evidence to whole files.

Supply either chunk_ids or resource_id, never both. cursor and limit apply only to resource reads.

after: integer · min: 0 · max: 2
before: integer · default: 0 · min: 0 · max: 2
chunk_ids: array · min items: 1 · max items: 6 · items: string · uuid · unique items
cursor: integer · default: 0 · min: 0 · max: 100000
limit: integer · default: 4 · min: 1 · max: 8
max_chars: integer · default: 12000 · min: 2000 · max: 24000
resource_id: string · uuid
text_offset: integer · default: 0 · min: 0 · max: 100000

Example tools/call params

{
  "name": "read",
  "arguments": {
    "chunk_ids": [
      "00000000-0000-4000-8000-000000000001"
    ]
  }
}

Replace the example UUID with an ID returned by CourseMCP.

get_course_source

Inspect original evidence when equations, diagrams or extraction are unclear. Request one to four PDF page images; omit pages for a short-lived original-file link.

resource_id is required. Page images are supported for original PDFs. Omitting pages returns a temporary download link to the original file.

pages: array · min items: 1 · max items: 4 · items: integer · min: 1 · unique items
resource_id: string · uuid

Example tools/call params

{
  "name": "get_course_source",
  "arguments": {
    "pages": [
      1
    ],
    "resource_id": "00000000-0000-4000-8000-000000000002"
  }
}

Replace the example UUID with an ID returned by CourseMCP.

Results and citations

Successful calls return structuredContent and the same data as JSON text. Search and read results include a shared sources dictionary with titles, source URLs, and provenance. max_chars bounds passage text; metadata adds to the total response size.

Use next_cursor to continue a search. Reads return remaining items and next pagination information. Search evidence_role values are retrieval hints, not a guarantee of correctness. A related_only result is insufficient evidence for an answer on its own.

Original-source calls also return a resource link or page images in MCP content. Image display depends on your client. Download links expire; request a new link when needed.

Usage limits

Free accounts include 10 searches per calendar month and one course. The $4 USD/month plan includes 5,000 searches per calendar month and unlimited courses. Reads, course listings, and source requests do not consume the search allowance. Request rate and storage limits still apply.

Search defaults to 3 results and 4,000 excerpt characters, capped at 10 results and 16,000 characters. Reads allow up to 24,000 passage characters. Original PDF requests accept at most 4 pages per call.

Errors

Tool failures return isError: true and a text message containing a reason code. Authentication and rate-limit failures use HTTP status codes instead.

unauthorized · HTTP 401: Sign in or authorize the connection again. The WWW-Authenticate header points to OAuth discovery metadata.
rate_limited · HTTP 429: Back off before retrying. Avoid repeated immediate requests.
invalid_arguments: Check the tool schema, argument combinations, IDs, and bounds before retrying.
unknown_tool: Refresh tools/list or reconnect the client.
not_found: The resource is unavailable to this account. Discover an accessible resource rather than retrying the same ID.
not_ready: The source is not ready to read. Check indexing coverage before trying again.
monthly_query_limit_reached: The monthly search allowance is exhausted. Wait for the next calendar month or review your plan.