Troubleshooting

Test the server#

This asks the server for its tool list, with no client in between. It should answer with event: message and a list that includes search_modules and get_exam.

curl -s https://ntumods.com/mcp \  -H 'content-type: application/json' \  -H 'accept: application/json, text/event-stream' \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

If that works, the server is up and the problem is in your client. If it fails with a status code, see MCP limits and errors.

The client says it cannot connect#

• Check that the URL is exactly https://ntumods.com/mcp, with https and nothing after it.
• Choose Streamable HTTP as the transport. A client set to SSE or stdio will fail.
• Choose no authentication. The server has no sign-in, so a client that insists on signing in is set to the wrong mode.
• Run the test below. If it works, the server is fine and the problem is in the client's setup.

It connected, but the tools do not show up#

• Turn the connector on for the chat. In Claude, click + in the chat box, open Connectors and switch NTUMods on.
• In Cursor, open Customize and check the toggle. In VS Code, open Configure Tools in the Chat view and tick ntumods. In Codex, type /mcp.
• Restart the client, or start a new chat. Many clients read the tool list only when a chat begins.

The assistant answers without using NTUMods#

• Name the source in your question: “Use NTUMods to find the exam date for SC1004”.
• Ask about something the tools cover: modules, class indexes and exams. They do not cover your timetable, grades or STARS.

The answer is wrong or out of date#

• Ask which semester the answer is for. Every answer names one, and an assistant can pick an older one if you do not say.
• Class changes made by NTU after the last data refresh are missing. The freshness page explains when the data updates.
• Always check STARS before you register, bid or drop a module.

429 or 503#

• 429 means too many requests from your network. Wait the seconds in the Retry-After header and try again.
• 503 means the server is switched off or temporarily unavailable. Try again in a few minutes.

403, 405, 413 or 415 from your own code#

• 403: the request came from a browser page on another site. Call the server from a backend or a client, not page JavaScript.
• 405: you used GET or another method. Every call is a POST.
• 413: the body is over 16 KB. Send one JSON-RPC message, not a batch.
• 415: the body is not JSON. Send Content-Type: application/json.

Your plan will not let you add it#

• Claude: a free plan can add one custom connector. On Team and Enterprise plans an Owner adds it for the organisation, then you connect it.
• ChatGPT: custom apps need Developer mode, which OpenAI limits to some plans. Check your workspace settings, or ask your workspace admin.
• An official listing in the Claude or ChatGPT directory avoids most of these limits once it is available for your plan.

Still stuck#

Tell me which client you use and what you see, through the feedback page or a GitHub issue. The steps for each client are under Adding to.