Skip to main content

Adding a Custom MCP Server

With a custom MCP server, you connect AI-School to your own application, data source, or specialized service. First, choose the transport that fits the place of use.

Choose the Right Transport​

TransportWebMobileDesktopUsage
Streamable HTTPYesYesYesRecommended for hosted servers
stdioNoNoYesLocal processes and desktop integrations
SSEExisting configurations onlyExisting configurations onlyYesDeprecated transport; choose Streamable HTTP for new servers

Requirements for Streamable HTTP​

Use the full public endpoint, including the MCP path, for example:

https://mcp.example.nl/mcp

The endpoint must:

  • Use HTTPS;
  • work without username or password in the URL;
  • require no redirect;
  • be reachable via public DNS;
  • respond with a valid MCP initialize handshake;
  • have an explicit set of allowed tools.

Local addresses, private network addresses, and cloud metadata endpoints are blocked. Therefore, you cannot register a server on localhost from the web app.

Adding a Server​

  1. Open Preferences → Tools.
  2. Choose Add Tools or Add MCP Server.
  3. First, review the available presets.
  4. Select Add a Custom MCP Server.
  5. Fill in the name, full endpoint, and authentication method.
  6. Save the configuration and wait for the connection check.
  7. Enable the server for your default toolset.

An administrator can also register a server for the entire environment via Admin → AI Settings → Tools → MCP.

Authentication and Secrets​

AI-School supports connector OAuth and static secrets. OAuth tokens, refresh tokens, API keys, and passwords are stored in server-only storage. A chat only receives the registered connectorId, never the secret configuration.

If the URL or authentication changes, the new configuration is first re-checked. If that check fails, a previously approved configuration can remain active until the issue is resolved.

Tool Permissions​

Only enable the tools that users actually need. An MCP server can offer both read and write actions, such as deleting files, sending emails, or modifying records. AI-School filters the discovered tools against the server-side allowlist, but the server administrator remains responsible for appropriate scopes and authorization.

Local Testing​

You can test a local stdio server in the desktop app. The renderer is not allowed to start arbitrary shell commands: installation proceeds via an approved preset or the secure desktop flow. Command, arguments, environment keys, and requested access are shown before installation.

Troubleshooting​

  • Endpoint not reachable: check HTTPS, DNS, firewall, and the full /mcp path.
  • Reconnection required: renew OAuth consent or the stored secret.
  • Belongs to another environment: re-register the connector within the current environment.
  • No tools visible: check the tool allowlist, your MCP access, and whether the server is enabled.
  • Works only on desktop: the server probably uses stdio or a local address.

Development Resources​

See Also​

WhatsApp