Grouper MCP server - user guide

Introduction

This guide is for end users who want to connect an AI tool (such as Claude, Cursor, or VS Code Copilot) to a Grouper instance via the built-in MCP server. It covers the UI info page where you can find your connection details, step-by-step client setup examples, and the full documentation for all available MCP tools.

For a high-level introduction to the Grouper MCP server, see the overview. For configuration and enabling instructions, see the administrator guide. For architecture and protocol details, see the technical reference.

All MCP tool calls are audited in a database table for security and compliance. The MCP server also enforces configurable per-category rate limits to protect system performance. See the administrator guide for details on audit logging and throttling configuration.

UI info page

All logged-in Grouper users can access the MCP info page from the Miscellaneous screen in the Grouper UI. Click Model Context Protocol (MCP) to view:

• MCP server URL: The URL to use when configuring your MCP client.

• Your MCP access: Shows which MCP operations you are authorized for (read-only, read-write, SQL read-only) and which authentication methods are available to you.

• Tool call history: Shows your recent MCP tool calls with timing and status.

• Connected applications: Shows AI applications you have authorized to access Grouper on your behalf, with the ability to remove them.

• Register confidential OAuth client: If you are a Grouper sysadmin or a member of the mcpUsersCanRegisterConfidentialOAuthClient group, you will see a form to register a confidential OAuth client (with client secret) for server-side applications like LibreChat. After registration, the page displays the client ID, client secret, authorization URL, token URL, and scope. Copy the client secret immediately — it is only shown once and cannot be retrieved later.

If MCP is not enabled on the environment, the page will display a warning. If OAuth is not enabled, the OAuth consent flow will not be available and users will need to use WS authentication instead. Contact your Grouper administrator to enable these features.

Client setup examples

The Grouper MCP server is a remote HTTP streaming MCP server with OAuth authentication. It is designed to work with agentic AI tools — AI assistants that can autonomously discover and call tools on your behalf. Market-leading agentic AI tools include Claude Code, Claude Desktop, OpenAI Codex, and Cursor.

In general, connecting to the Grouper MCP server involves two steps:

1. Add the MCP server — In your AI tool's settings or via a command, add a new remote MCP server using the URL shown on your Grouper MCP info page (e.g. https://grouper.example.edu/grouper-ws/mcp).

2. Authenticate — The first time you connect, the tool will open your browser for you to log in to Grouper and approve the requested permissions on a consent page.

Below are setup instructions for popular agentic AI tools.

Claude Code (command line)

Claude Code is Anthropic's agentic command-line tool. To add the Grouper MCP server:

1. Run the following command in your terminal:

   claude mcp add --transport http grouper https://grouper.example.edu/grouper-ws/mcp

2. Start a Claude Code session, then type /mcp to see your MCP servers and authenticate. Claude Code will open your browser to complete the OAuth login and consent flow.

3. Once authenticated, you can interact with Grouper by asking Claude questions in natural language (e.g. “What groups is jsmith a member of?”). Claude will automatically call the appropriate Grouper MCP tools.

Claude Desktop (app)

Claude Desktop is Anthropic's desktop application with built-in MCP support.

1. Open Settings (gear icon).

2. Go to Connectors.

3. Click Add custom connector at the bottom.

4. Enter your Grouper MCP server URL (e.g. https://grouper.example.edu/grouper-ws/mcp).

5. Click Add. Claude will open your browser to complete the OAuth login and consent flow when you first use a Grouper tool.

OpenAI Codex (command line)

OpenAI Codex is OpenAI's agentic command-line tool. To add the Grouper MCP server:

1. Add the server:

   codex mcp add grouper --url https://grouper.example.edu/grouper-ws/mcp

2. Log in to the server via OAuth:

   codex mcp login grouper

   This will open your browser to complete the Grouper OAuth login and consent flow.

3. Once authenticated, you can ask Codex questions about Grouper and it will call the appropriate MCP tools automatically.

Cursor

Cursor is an AI-powered code editor with built-in MCP support.

1. Open Cursor Settings.

2. Navigate to Tools & Integrations.

3. Click New MCP Server.

4. Enter the server name (e.g. grouper) and your Grouper MCP server URL (e.g. https://grouper.example.edu/grouper-ws/mcp).

5. Click Connect to authorize. Cursor will open your browser to complete the OAuth login and consent flow.

Other AI tools

Any agentic AI tool that supports remote MCP servers with HTTP streaming transport should work with the Grouper MCP server. Look for an option to add or connect to a remote MCP server in your tool's settings, and enter the URL shown on your Grouper MCP info page. The tool will handle the OAuth authentication flow automatically.

Server-side applications (confidential clients)

Server-side applications like LibreChat can securely store a client secret, so they use a confidential OAuth client instead of the public PKCE flow used by CLI tools. To set up a server-side application:

1. Go to the MCP info page in the Grouper UI (Miscellaneous → Model Context Protocol).

2. In the Register confidential OAuth client section, enter a client name (e.g. LibreChat) and the redirect URI for your application.

3. Click Register confidential client.

4. Copy the displayed Client ID, Client Secret, Authorization URL, Token URL, and Scope into your application's OAuth configuration. The client secret is only shown once.

This section is only visible to Grouper sysadmins and members of the mcpUsersCanRegisterConfidentialOAuthClient group. The redirect URI must match one of the allowed patterns configured by your Grouper administrator.

Consent and read-write scope restrictions

When you first connect, your browser will open a Grouper consent page where you choose which permissions to grant. You will only see permission options that your Grouper administrator has authorized for you.

If you check the Read-write operations checkbox, you are required to specify the scope of the read-write access by entering at least one of the following:

• Folder ID paths – Comma-separated list of folder paths (e.g. school:departments, org:teams). The AI tool can modify any group within these folders (recursively). Maximum 10 folders, and the total number of groups across all specified folders must be less than 500.

• Group ID paths – Comma-separated list of specific group paths (e.g. school:departments:faculty, org:teams:admins). The AI tool can modify these specific groups. Maximum 10 groups.

• Subject IDs or identifiers – Comma-separated list of subject IDs or identifiers / login names (e.g. jsmith, jdoe). The AI tool can only add or remove these specific subjects as members. Maximum 50 subjects.

These restrictions are enforced on every read-write tool call. If both folders and groups are specified, a group is in scope if it matches a listed group path or is within a listed folder. If subjects are specified, every subject involved in a read-write operation must also be in the list. Categories left blank are unrestricted — for example, if you only enter folder paths but leave subjects blank, the AI tool can modify groups in those folders for any subject. Conversely, if you only enter subject IDs but leave folders and groups blank, 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.

The consent page validates your entries before submission. It verifies that the folders and groups you entered exist in Grouper, and that the total number of groups across all specified folders does not exceed 500.

Available MCP tools

The MCP server exposes Grouper operations as tools that MCP clients can auto-discover and auto-invoke. By interacting with AI in natural language the AI will decide when to call a tool. If you can enable consent so you can approve the AI when it runs a command, that is recommended. There is no way to undo an operation that AI invokes.

admin_config_search

Search Grouper configuration properties. Supports two search modes: lucene (default) for full-text search on config keys and values using a Lucene in-memory index, and regex for Java regex matching against config key names only. Sensitive values (passwords, secrets, private keys) are automatically masked as *******. Optionally filter by a specific config file. Requires membership in the MCP admin readonly group. For OAuth users, the admin_readonly consent scope must also be granted.

The Lucene config index is built in-memory on each WS node from all Grouper configuration files and rebuilt periodically (every hour). It indexes config keys (with dots tokenized as separate words) and non-sensitive values for full-text search.

Response: Returns a JSON object with matchCount, searchType (lucene or regex), and a configs array of objects. Each config entry contains:

• key — the configuration property key

• value — the current value (masked as ******* for sensitive configs)

• configFile — which config file this property belongs to

• sensitive — true if the value is a password/secret (only present when true)

When using Lucene search, each entry may also include:

• configuredIn — where the value is set: base properties file, override file, or database

• defaultValue — the default/base value for the property

• elScript — the Expression Language script if the property uses EL configuration

• comment — documentation comment from the properties file

• valueType — the expected type (e.g. boolean (true or false), text, integer, password)

• required — true if the property is required (only present when true)

If more than 500 results match (regex mode), the list is truncated with a truncated flag and message.

admin_daemon_job_message

Retrieve the job message for a specific daemon job log entry by its row ID. Returns the first 20,000 characters of the message (from the job_message column, or job_message_clob if job_message is null). Also returns the job name, status, and start time for context. Use admin_daemon_logs first to find the id of the log entry you want. Requires membership in the MCP admin readonly group. For OAuth users, the admin_readonly consent scope must also be granted.

Response: Returns a JSON object with jobName, status, startedTime, jobMessage (first 20,000 characters), and truncated (true if the message was longer than 20,000 characters).

admin_daemon_job_run

Trigger a daemon job to run on the Grouper daemon server. The job is triggered asynchronously via the Quartz scheduler. Use admin_daemon_names to find valid job names, and admin_daemon_logs to check the status after triggering. Requires membership in the MCP admin readwrite group. For OAuth users, the admin_readwrite consent scope must also be granted.

Response: Returns a JSON object with jobName, status (TRIGGERED), and a message confirming that the job was triggered on the daemon server.

admin_daemon_logs

Retrieve daemon job log entries from the grouper_loader_log table. Returns the most recent 100 rows ordered by start time (descending). Does not return the job_message (use admin_daemon_job_message for that). At least one of jobName or status must be provided. Requires membership in the MCP admin readonly group. For OAuth users, the admin_readonly consent scope must also be granted.

Response: Returns a JSON object with rowCount and a rows array of log entries. Each entry includes: id, job_name, status, started_time, ended_time, millis, job_type, job_description, host, insert_count, update_count, delete_count, total_count, unresolvable_subject_count, parent_job_name, last_updated. If more than 100 results match, only the most recent 100 are returned with a truncated flag.

admin_daemon_names

Search for daemon job names in the Grouper loader log. Takes a search string that is split by whitespace into terms, where each term is matched against the job_name column using case-insensitive LIKE. You can include % as a wildcard in each term; if a term does not contain %, it is automatically wrapped with % on both sides. All terms must match (AND logic). Returns distinct job names. Requires membership in the MCP admin readonly group. For OAuth users, the admin_readonly consent scope must also be granted.