Skip to main content

Add a custom MCP server

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

Choose the right transport​

TransportWebMobileDesktopUse
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 a username or password in the URL;
  • not require a 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. This means you cannot register a server on localhost from the web app.

Add a server​

  1. Open Preferences → Tools.
  2. Choose Add tools or Add MCP server. You only see this button if you have MCP access.
  3. First review the available presets.
  4. Choose Add a custom MCP server.
  5. Enter 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.

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

Tool permissions​

Only grant the tools users actually need. An MCP server can offer both read and write actions, such as deleting files, sending email, or changing 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 test a local stdio server in the desktop app. The renderer may not start arbitrary shell commands: installation happens through an approved preset or the secure desktop flow. Command, arguments, environment keys, and requested access are shown before installation.

Troubleshooting​

  • Endpoint unreachable: check HTTPS, DNS, firewall, and the full /mcp path.
  • Reconnect required: refresh OAuth consent or the saved secret.
  • Belongs to another environment: register the connector again within the current environment.
  • No tools visible: check the tool allowlist, your MCP access, and whether the server is active.
  • Works only on desktop: the server probably uses stdio or a local address.

Development resources​

See also​

When editing, the registered server configuration is retrieved. The stored key remains hidden: leave the key field empty to keep it. If the URL or authentication method is different, reconnecting is required. An error in one MCP tool does not mean all tools from that server are unreachable.

On this page