MCP — connect an external AI agent to Omniscol

What the agent can do

The MCP agent performs very well on read-only questions where the data lives in Omniscol:

• "Give me the room occupancy rate against opening hours this week."
• "Find me a room available on three Mondays in October on the same 2-hour slot."
• "How many lesson hours has Jean Dupont taught over the current school year?"
• "What are all of today's math lessons?"
• "List the teachers who have completed less than 70% of their service hours this term."

These queries typically cross several tools: timetable, statistics dashboards, computed availability, teacher records. The agent orchestrates the calls and phrases the answer in natural language.

The exposed tools

The MCP server builds its tools from the Omniscol API routes authorized for MCP. Explicitly ignored routes, and some technical modules (for example, those related to user authentication) do not become tools. The list therefore reflects the API exposed to MCP, not the application's entire internal surface. It is nonetheless a very large part. What is more, a number of routes are dedicated to MCP and not used by Omniscol itself. This is the case for advanced search tools, so that free text naming an entity ("teacher Jean Dupont", "class 6A") is resolved by Omniscol to its technical identifier, then used to query the data precisely. It is also the case for complex tools where Omniscol has no graphical interface, because a prompt suits them better: entity occupancy and availability search, for example ("find me a room available for 2 hours in the afternoon on 3 Mondays in a row", "is a math teacher available in the week of 14 October for 3 hours?").

The tools notably cover:

• the Administration module (users, subjects, school years, settings),
• the Timetable management module (configuration, sites, rooms, classes, lessons),
• the Timetable module (schedule, dashboards, searches),
• the Absence management module (declaring absences, statistics),
• global search.

Read routes are the best suited to agentic use. Some write operations may exist in the catalog, depending on the token's rights and the available API, but they must remain supervised: a request that modifies several business objects must be verified by a user before being considered reliable.

Enabling the MCP server

The MCP server is available on Premium accounts. Everything starts from the MCP screen, opened from the Administration module with Configure: it shows the server URL for the chosen scope (global or restricted to one module) and provides, ready to copy, the configuration elements for your client.

MCP's standard authentication is OAuth2. A compatible client (such as Claude) simply connects to the server URL, discovers the account's OAuth2 configuration there, and the user approves the access through a consent screen: there is nothing to provide other than the URL. The granted scope follows the account's rights and its visibility restrictions. Omniscol's OAuth2 server, its client management screen and the details of consent are described on OAuth2 / OIDC (provider).

For a client that does not support OAuth2, the same screen generates a token (API key, expiry, optional associated user, write rights to tick) then offers, ready to paste, the formats useful for each case: Authorization: Bearer header, URL with token, Claude Desktop configuration block (free mode) and local proxy command. The token relies on the key system described in Omniscol API.

Security best practices

• OAuth2 authentication — more convenient, and to be preferred when your agent supports it (paid version of Claude).
• Token dedicated to the AI — create a token with a meaningful label (AI agent — Claude desktop) that you can revoke if needed.
• Minimal scope — with an API token, select only the API endpoints you need. With an OAuth token, limit the scopes to the actual need.
• Activity log (logs) — a call appears in the logs associated with the token when the route in question is logged. These logs trace the call; they keep neither the detail of the data returned nor a replayable copy of the request.
• Visibility restrictions — the agent sees what Omniscol returns to it. If you have configured strict visibility restrictions for the token's role, they apply.