Zum Hauptinhalt springen

MCP server overview

Casdoor has a built-in Model Context Protocol (MCP) server at /api/mcp. MCP clients, such as AI assistants and automation tools, call it to manage applications, users, and other Casdoor objects, without using the REST API directly.

MCP is a protocol on top of JSON-RPC 2.0 through which a client discovers the tools of a server and calls them.

Casdoor works with MCP in two directions:

  • As an MCP server: Casdoor offers its own management functions as tools. The pages of this section describe this server.
  • As a registry of external MCP servers: Casdoor stores the MCP servers that your organization uses, with their tokens and the tools that you allow. See Register an external MCP server.

Connect to the Casdoor MCP server​

The endpoint /api/mcp accepts POST requests with JSON-RPC 2.0 payloads. Before a client calls tools, it completes the initialization handshake.

  1. The client sends initialize:

    POST /api/mcp
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {
          "name": "my-client",
          "version": "1.0.0"
        }
      }
    }

  2. Casdoor answers with its capabilities:

    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "protocolVersion": "2024-11-05",
        "capabilities": {
          "tools": {
            "listChanged": true
          }
        },
        "serverInfo": {
          "name": "Casdoor MCP Server",
          "version": "1.0.0"
        }
      }
    }

  3. The client confirms that it is ready:

    POST /api/mcp
    {
      "jsonrpc": "2.0",
      "method": "notifications/initialized"
    }

MCP client libraries perform the handshake for you. To connect a specific client, see:

Register an external MCP server​

  1. In the Casdoor admin console, open the MCP Servers page and add a server.

  2. Fill in the following fields:

    FeldBeschreibung
    NameUnique identifier for this server entry
    AnzeigenameHuman-readable label shown in the UI
    URLThe external MCP server's endpoint
    ApplicationCasdoor application associated with this server (used for auth context)
    TokenBearer token used to authenticate with the external server
    ToolsList of tools fetched from the server; each tool can be individually allowed or blocked

  3. Save the server. Casdoor fetches the list of tools from the server and stores it.

Get a token from Casdoor​

If the external server trusts Casdoor as its OAuth 2.0 provider, you don't have to paste a token. Select an Application, and then click Get access token next to the Token field. Casdoor issues an access token for the signed-in user and that application and fills it in. The button is unavailable until you select an application, because Casdoor issues the token for that application.

If the server uses credentials from another issuer, enter the token by hand.

Refresh or clear the tool list​

On the edit page of the server:

  • Sync fetches the tool list again, without saving the rest of the configuration. Tools that already exist keep their allowed or blocked setting. New tools are allowed by default.
  • Clear removes all stored tools of the server, without fetching new ones. Use it to reset the list before a new sync or before you retire a server.

Add a server from the MCP Store​

The MCP Store page lists public MCP servers from an online registry.

  1. Search for a server by name or by tag.
  2. Click Add. Casdoor creates a server record with the URL and the metadata of the server.
  3. On the edit page of the new server, set the token and choose the allowed tools.

Scan your network for MCP servers​

To find MCP servers that run on your internal network:

  1. On the MCP Servers page, click Scan.

  2. Fill in the scan settings:

    FeldStandardBeschreibung
    CIDR / IP—One or more CIDR ranges or individual IPs to scan (e.g. 192.168.1.0/24). Erforderlich. Max 1024 hosts per scan.
    Schemehttphttp or https
    Ports3000, 8080, 80Ports to probe on each host
    Paths/, /mcp, /sse, /mcp/sseURL paths to try on each host/port combination

  3. Start the scan. Casdoor probes every combination of host, port, and path, with up to 32 connections at a time and a timeout of 1.2 seconds per probe. It lists every endpoint that answers with a valid MCP initialize response.

  4. Select the servers that you want and add them to the MCP Servers list.

See also​