Grouper MCP server - administrator guide

Introduction

This guide is for Grouper administrators and operators who want to enable, configure, and manage the built-in MCP server. It covers enabling MCP, all configuration properties, authorization groups that control who can use MCP, registration security, and multi-container deployment considerations.

For a high-level introduction to the Grouper MCP server, see the overview. For end-user setup instructions and tool documentation, see the user guide. For architecture and protocol details, see the technical reference.

Enabling the MCP server

The MCP server and OAuth authentication are controlled by two separate configuration properties in grouper.hibernate.properties:

• grouper.is.mcp – Enables the MCP protocol.

  • On a WS environment (grouper.is.ws = true): loads the MCP protocol servlet.

  • On a UI environment (grouper.is.ui = true): enables the MCP info page.

• grouper.is.oauth – Enables OAuth 2.1 with PKCE authentication.

  • On a WS environment (grouper.is.ws = true): loads the OAuth token and registration servlets.

  • On a UI environment (grouper.is.ui = true): enables the OAuth consent page.

Both properties must be set to true on both the WS and UI containers for full MCP-with-OAuth functionality. If you only need MCP with WS authentication (HTTP Basic or container auth) and no OAuth, you can enable grouper.is.mcp alone on the WS container.

To enable MCP with OAuth, set the following in your Grouper configuration or as environment variables:

# In grouper.hibernate.properties (set on both UI and WS containers) grouper.is.mcp = true grouper.is.oauth = true

Or via environment variables (which the EL config expressions read automatically):

GROUPER_MCP=true GROUPER_OAUTH=true

The MCP protocol servlet requires grouper.is.ws = true because it is registered inside the WS servlet initialization block. The OAuth servlets also require grouper.is.ws = true. Both the WS module and the UI module must be running for the OAuth flow to work (WS handles token exchange; UI handles user authentication and consent). If using normal WS authentication (HTTP Basic or container auth) instead of OAuth, only the WS module with grouper.is.mcp = true is required.

Configuration

grouper.hibernate.properties

MCP settings (grouper.properties)

OAuth settings (grouper.properties)

These properties control the OAuth 2.1 token lifecycle used by MCP clients that authenticate via the OAuth flow.

OAuth registration settings (grouper.properties)

These properties control how MCP clients register as OAuth clients via dynamic client registration (RFC 7591). Registration is anonymous (no authentication required) and is protected by the redirect URI allowlist, IP-based rate limiting, and the fact that registration alone grants zero access — the user must still complete the OAuth consent flow and be in the proper MCP authorization groups.

Redirect URI patterns are required. If no grouper.oauth.redrectUri.*.regex patterns are configured, all OAuth client registrations will be rejected. For development, start with a localhost pattern:

# Allow localhost redirect URIs for development grouper.oauth.redrectUri.localhost.regex = ^http://localhost(:\\d+)?/.*$ # Allow a production application grouper.oauth.redrectUri.myApp.regex = ^https://myapp\\.example\\.edu/.*$

MCP authorization groups (grouper.properties)

See the Authorization groups section below for the full list of MCP authorization group properties and their defaults.

Auto-managed configuration (database-stored)

The following properties are automatically generated and stored in the database-backed grouper.properties configuration. They should not normally be set manually.

Authorization groups

MCP access is controlled by Grouper groups that are autocreated at startup. Membership in these groups determines what each user can do via MCP. Note that wheel group membership does not automatically grant MCP access — users must be explicitly added to the appropriate MCP groups.

Note: These groups are autocreated by Grouper at startup (when configuration.autocreate.system.groups = true, which is the default). Administrators populate these groups to grant MCP access to individual users or other groups.

OAuth provides additional consent-based restriction. When users authenticate via OAuth, the consent page only shows scope checkboxes for groups the user is actually a member of (read-write membership also shows the read-only scope, and admin read-write also shows admin read-only), and the user can choose to grant fewer scopes than their group memberships would allow. These consent choices are enforced on every MCP request in addition to group membership. For example, a user in the readwrite group can choose to grant only readonly access to a particular MCP client. With WS authentication (HTTP Basic, container auth) there is no consent flow, so authorization is based solely on group membership. This makes OAuth the preferred authentication method for interactive AI use.

Read-write scope restrictions. When a user selects the read-write scope on the OAuth consent page, they can specify scope restrictions: folder paths (limiting which folders the client can modify groups in, maximum 10), group paths (limiting which specific groups can be modified, maximum 10), or subject IDs/identifiers (limiting which subjects can be managed, maximum 50). Folders are validated for existence and the total number of groups across all specified folders must be less than 500. These restrictions are encoded in the JWT access token and enforced on every read-write tool call. Categories left blank are unrestricted — for example, if a user only enters folder paths but leaves subjects blank, the client can modify groups in those folders for any subject. Conversely, if a user only enters subject IDs, those subjects can be operated on with any group. At least one category must have a value; if all categories are left blank, no read-write operations are permitted. By default (grouper.mcp.oauth.requireReadwriteDataScope = true), at least one folder, group, or subject must be specified. Set to false to make data scope restrictions optional, allowing users to grant unrestricted read-write access.

Scope enforcement for assignment-on-assignment. When a read-write tool call uses an _asgn attribute assign type (e.g. group_asgn, stem_asgn), the MCP server resolves the owner attribute assignment to determine the underlying group, stem, or subject. Scope restrictions are then checked against that underlying owner, not just the assignment ID. This ensures that, for example, an OAuth client scoped to folder school:departments cannot assign metadata on a marker attribute that belongs to a group in school:clubs.

Trailing colon tolerance. Folder scope values entered with a trailing colon (e.g. school:departments:) are handled correctly — the trailing colon is stripped before matching. This prevents user confusion when entering folder paths.

Summary of tool access for authorization groups