Grooper MCP

2026 BETA

This article covers new or changed functionality in the current or upcoming beta version of Grooper. Features are subject to change before version 2026's GA release. Configuration and functionality may differ from later beta builds and the final 2026 release.

Model Context Protocol (MCP) support in Grooper allows the repository to act as both a provider and a consumer of MCP tools, resources, and prompts. These tools, resources and prompts are exposed in two ways.

This lets external AI agents (such as coding assistants or custom automation) call directly into a Grooper Repository to access these tools, resources and prompts.
This lets Grooper's own AI features (AI Assistants and Agent Actions) consume these same tools, resources and prompts and call out to external MCP servers and registries.

Overview

Model Context Protocol is an open standard for connecting AI applications to external tools, data sources, and prompts over a common interface. Grooper's implementation covers both directions:

Serving tools: A Grooper Repository can expose a curated set of its own capabilities (repository management, Batch/document operations, scripting, external content repositories, search, statistics, and more) as an MCP server that any MCP-compatible client can connect to.
Consuming tools: The Agent Planner used by AI Assistants and Agent Actions can connect out to external MCP servers and registries, bringing third-party tools into an agent's available toolset alongside Grooper's built-in tools.

Key objects involved

Display name	Object Type	Where you'll find it	Purpose
MCP Server	Node	Added inside a Project	Hosts a named collection of tools, resources, and prompts, and serves them to MCP clients.
MCP Registry	Node	Added inside a Project	Publishes local MCP Servers and/or aggregates outbound connections to other servers and registries.
AI Assistant	Node	Added inside a Project	A configurable chatbot whose Agent Planner can call MCP tools (via its own connections or a registry) alongside Grooper's built-in retrieval tools when answering a user.
Resource File	Node	Added inside a Project	A file-based resource (document, text, etc.) that can be added to an MCP Server's Resources list to expose it to MCP clients, or referenced by an Agent Planner as a knowledge resource.
Agent Action	Action	Submitted by an Action Scheduler or as a one-off Action Task by a user from the Actions page	Has an AI Assistant carry out a task following its own Instructions or a named MCP prompt. This allows the AI Assistant to run MCP tools without a live chat session.
Action Scheduler	Service Instance	Installed using GCC. Configured under Machines	The background service that runs "Scheduled Actions" (including Agent Actions) on a schedule or polling loop, and processes ad-hoc Action Tasks as they're submitted. This is what actually executes an unattended agent.

MCP Server

An MCP Server is added inside a Project and hosts three collections:

Tools – the callable operations exposed by the server. Grooper ships a large built-in catalog of tools (see Built-in tool catalog below); a given server exposes whichever tools it's configured with.
Resources – a list of Resource Files made available to clients.
Prompts – a list of Prompt Template or Prompt Expression entries, each with a name, title, description, and parameters.

Other notable properties:

Property	Description
Namespace	Combines with the server's own name to form its unique identifier, in the form `namespace/name`.
Instructions	Free-text guidance returned when a client connects, used to steer client/model behavior when using this server.
Grooper Tool Categories	Tool categories made available locally to the agent planner.
Structured Data Mode	Controls how tool results are returned: Enabled (structured data only), Disabled (plain text content only), or Hybrid (both).
Tool List / Resource List / Prompt List	Read-only previews of exactly what the server will report to a connecting client – useful for verifying configuration.

MCP Registry

An MCP Registry has two complementary jobs:

Publishing – it exposes one or more local MCP Servers to the outside world under a single registry endpoint.
Aggregating – through its list of MCP Connections and MCP Registry Connections, it pulls in tools from other MCP servers and registries – local or remote – and merges them into one logical toolset.

This makes the registry the natural place to centralize and reuse connection configuration across multiple AI Assistants or agents, rather than configuring the same outbound connections repeatedly.

Both MCP Connection and MCP Registry Connection entries support:

A Url and an Authentication method (Basic or OAuth Client Credentials) for reaching the remote server or registry.
A Tool Filter (and, for registries, a Server Filter) – text patterns that narrow which tools (or servers) are actually pulled in, so an agent isn't handed a wider toolset than it needs.

AI Assistants and the Agent Planner

Every AI Assistant has an Agent Planner, configured through its Planner property. This is the component that actually decides which tools to call, and in what order, before responding to the user – or, for an Agent Action, before finishing an unattended run.

Local tools vs external tools

Local tools

The Agent Planner's own Tools, Resources and Prompts are locally native to Grooper. They are build from the exact same building blocks as an MCP Server's.

Tools: The same built in tool catalog, including the "Grooper Tool Categories".
Resources: The same capability to reference Resource Files is present.
Prompts: The same capability to add Prompt Templates and Prompt Expressions is present.

In short, anything you can expose on a Grooper MCP Server, you can attach directly to an AI Assistant's Planner as a local tool resource or prompt. This is how Grooper's own agents get MCP-style tool access.

FYI

Note: The Agent Planner's Tools are a completely different mechanism from the Additional Tools property found directly on an AI Assistant.

Additional Tools (Ask User, Help Search, Load Schema, Load Web Page, Wiki Search) is an older, retrieval-augmented-generation (RAG) feature built specifically for document/knowledge retrieval. It is not part of the MCP tool system described in this article. Do not confuse the two when reading an AI Assistant's configuration.

External tools

On top of its local Tools/Resources/Prompts, the AI Assistant's Planner can also reach out to MCP Servers and Registries it doesn't own. These are the same kind of outbound connections described under MCP Registry above:

Servers: A list of MCP Connection entries, each pointing at one external MCP Server.
Registries: A list of MCP Registry Connection entries, each pointing at one external MCP Registry.

In short, this is a way of stacking external MCP functionality on top of Grooper's own native functionality.

Other notable properties

Property	Description
Instructions	Guidance for the planner to follow when generating execution plans.
Maximum Plan Depth	The maximum number of tool calls the planner will chain together before truncating the plan.
Tool Selector	The strategy the planner uses to decide which of its available tools to actually offer for a given request.
Grooper Tool Categories	Tool categories made available locally, letting you scope the built-in catalog by area instead of listing individual tools one by one.
Local Tools Description / Local Tools Instructions	Extra descriptive text and usage guidance covering the planner's own local Tools, on top of each tool's own built-in description.

This whole flow – whether triggered by a live chat with an AI Assistant or by the Action Scheduler kicking off an Agent Action – comes down to: AI Assistant/Agent Action → Agent Planner → local Tools, and/or MCP Connection/MCP Registry Connection → an external MCP Server or Registry. Once the plan is built, the underlying language model doesn't distinguish between local and external tools – it just sees one combined list it can call.

How agents consume MCP tools

MCP support runs in two directions in Grooper, and it's easy to mix them up because several of the same objects (MCP Servers, MCP Connections, MCP Registries, MCP tools, etc.) show up on both sides. The two flows are:

Grooper's own agents (AI Assistants and Agent Actions) consuming native Grooper tools and calling out to external MCP tools
External AI clients calling into a Grooper MCP Server to consume Grooper tools.

Grooper's own agents calling out to MCP tools

This is the direction where an AI Assistant or Agent Action uses its Agent Planner to reach tools that aren't built into the chat itself – whether those tools are attached locally or live on another server entirely.

A user starts a chat with an AI Assistant, or the Action Scheduler kicks off an Agent Action (a scheduled or one-off unattended run). Either way, it's that assistant's Agent Planner that builds the execution plan.
The planner assembles its available toolset from two places:
- Its own local Tools, Resources, and Prompts – see Agent Planner above.
- External tools pulled in through the planner's Servers (MCP Connection) and Registries (MCP Registry Connection) entries, each narrowed by its own Tool Filter (and Server Filter, for a registry connection).
The underlying language model doesn't distinguish between local and external tools once the plan is built – it just sees one combined list it can call to answer the question or complete the task.

In short: AI Assistant/Agent Action → Agent Planner → local Tools, and/or MCP Connection/MCP Registry Connection → an external MCP Server or Registry.

External AI clients calling into a Grooper MCP Server

This is the mirror image: something outside Grooper – an AI coding assistant, a custom agent harness, or any other MCP-compatible application – connects in to a Grooper MCP Server (directly, or via an MCP Registry that publishes it) the same way it would connect to any other MCP server.

The client connects to the MCP Server's endpoint. The server responds with its Instructions property, giving the client/model guidance on how to use what it's about to see.
The client asks what's available, and gets back exactly what the Tool List, Resource List, and Prompt List properties describe – whichever subset of the built-in tool catalog, Resource Files, and Prompt Templates/Expressions that particular server was configured with.
The client calls tools the same way it would call any MCP tool, and gets results shaped by the server's Structured Data Mode (structured data, plain text, or both).

In short: an external AI client → a Grooper MCP Server (or a Registry publishing one) → Grooper's own repository tools, resources, and prompts.

This is a very practical way to work with Grooper: rather than a person clicking through the UI or hand-writing scripts against it, an AI client can be handed direct, structured access to repository objects, batches, jobs, and configuration – and because a server only ever exposes the tools it's explicitly configured with, an administrator controls exactly how much of that surface any given client is allowed to touch. (This article itself was researched this way – an AI assistant connected to a Grooper MCP Server and used its built-in tools to look up the real property names and behavior described throughout this page.)

Built-in tool catalog

Grooper ships 113 built-in tools, organized into 18 categories.

There are two main areas where tools are added for both MCP Servers and an AI Assistant's Agent Planner.

Grooper Tool Categories - This property allows you to select full categories of Grooper tools in bulk. These categories and the tools they expose are detailed below in the Grooper Tool Categories section.
- A given MCP Server or Agent Planner only exposes the categories (and, within them, the specific tools) it's configured with. The "Tool List" property shows exactly what will be reported to a connecting client.
Tools editor - At the time this article was written, the Tool editor exposes a set of general tools that are useful when interacting with a chat-based AI client. For example, the "Vector Search" tool performs a semantic language style query against an AI Search document index in a Grooper repository. The full list of general tools are detailed in the Tools - General section below.

Grooper Tool Categories

Batches

Tools for creating and inspecting batches – the root containers of Grooper's document processing workflow.

Tool	Description
Create Batch	Creates a new batch in the Grooper repository.
Get Batch Info	Retrieves detailed information about a specific batch by its node ID.
Get Batch Stats	Returns accumulated statistics for one or more batches.
List Batches	Lists batches in the Grooper repository, with optional filtering by process, step, or status.

CMIS

Tools for reading and writing content in external CMIS-compliant repositories connected to Grooper.

Tool	Description
Create Cmis Object	Creates a new CMIS document or folder in a repository.
Get Cmis Content Stream	Retrieves the content stream of a CMIS document.
Get Cmis Object	Retrieves the information for a given CMIS folder or document.
Get Cmis Repository Info	Retrieves the information for a given CMIS repository.
Get Cmis Type	Retrieves the information for a given CMIS type.
Get Cmis Type Tree	Retrieves the type and all descendant types for a given CMIS type.
List Cmis Child Objects	Retrieves the child objects of a given CMIS folder.
List Cmis Child Types	Retrieves the child types of a given CMIS type.
Run Cmis Query	Executes a CMIS query (CMISQL) against a CMIS repository and returns the matching results.
Set Cmis Content Stream	Sets or replaces the content stream of an existing CMIS document.
Update Cmis Object Properties	Updates the properties of an existing CMIS document or folder.

Documents

Tools for working with individual documents and pages inside a batch – their content, index data, and the Content Type schema behind them.

Tool	Description
Create Document	Creates a new child Batch Folder with an attachment inside a Batch or Batch Folder.
Create Page	Creates a new child Batch Page in a Batch or Batch Folder.
Get Content Type Schema	Returns the JSON schema for the data model associated with a Content Type.
Get Document Content	Returns the text content of a Batch Folder document.
Get Document Data	Returns the index data for a Batch Folder document using a specified Content Type.
List Documents	Lists the Batch Folder documents with a specific Content Type assigned.
Update Document Data	Updates the index data of a Batch Folder document by either replacing it wholesale or applying JSON Patch operations.

Known Limitation: AI agents cannot upload documents directly via Create_Document tool

Applies to: Create_Document, Create_Page, and similar Grooper MCP tools that accept file content inline.

These tools accept file content as base64 text in the tool call. This works fine for scripts and backend integrations, but AI chat agents can't practically use it to upload files on a user's behalf: the agent has to generate the entire base64 payload as output text, and base64 tokenizes very inefficiently for language models (~6 tokens/character). Even modest files exceed practical response limits well under 100KB.

This is not a tool defect — Grooper accepts any valid base64 content. The limit is purely a side effect of routing file bytes through a conversational AI interface.

Guidance: Don't ask an AI assistant to read a local file and upload it via chat-based tools. Instead, use a server-side Import Action with an Import Provider (FileSystemImport, FTP/SFTP/Mail/CMIS/HTTP) so Grooper reads the file directly from its source. An agent can still orchestrate this — triggering the scheduled task or job — without ever handling the file's bytes itself.

Events

Tools for reading and managing entries in the Grooper event log.

Tool	Description
Delete Log Events	Permanently deletes Grooper event log entries matching the specified filter criteria.
Get Log Event	Retrieves a single Grooper event log entry by its integer ID.
List Log Events	Lists entries in the Grooper event log, with optional filtering and pagination.

Help

Tools for looking up Grooper's own type documentation and help topics – useful for an agent discovering how to use the rest of the catalog.

Tool	Description
Get Type Help	Retrieves help topics for one or more specific Grooper types by their full .NET type name.
Get Type Info	Retrieves information about a Grooper object type and its properties, commands, and allowed child types.
List Type Derivatives	Lists all non-abstract types that derive from a given base type.
Search Help	Searches help for topics about Grooper types and user interface components.

Jobs

Tools for managing processing jobs and tasks – the units of work behind batch processing.

Tool	Description
Cancel Jobs	Cancels one or more processing jobs by removing their pending tasks and setting their status to Canceled.
Delete Jobs	Permanently deletes one or more processing jobs and all their associated tasks.
Delete Task	Deletes one or more Processing Task objects from the database.
Get Job	Retrieves detailed information about a specific processing job by its integer ID.
List Jobs	Lists processing jobs, optionally filtering by status, batch process name, step name, activity type, or batch ID.
List Tasks	Lists processing tasks with optional filtering, sorting, and pagination.

Misc

Assorted configuration-related tools: database schema and queries, data element overrides, AI model listing, and label sets.

Tool	Description
Get Database Table Schema	Returns the column details for a database table on a Data Connection.
Get Overrides	Gets data element property overrides for a content type within a Content Model.
Inspect Expression	Returns instructions for editing a code expression property.
List AI Models	Lists the available AI models from the configured LLM connector in the Grooper repository.
List Database Tables	Lists the tables and views available on a specified Data Connection.
Load Label Set	Loads a labelset for a specific content type.
Run Database Query	Executes a SQL query against a Data Connection and returns the results as CSV data.
Save Label Set	Saves a labelset for a specific content type.
Set Overrides	Sets data element property overrides for a content type within a Content Model.

Nodes

The core tools for reading, creating, updating, moving, and deleting nodes – and their attached files – anywhere in the repository tree.

Tool	Description
Add Child Nodes	Adds one or more child nodes under a parent node.
Clear Child Nodes	Deletes all immediate child nodes from a parent node.
Copy Or Move Node	Copies or moves a node to a new parent.
Delete Node	Deletes a node.
Delete Node File	Deletes a file from a node.
Execute Node Command	Executes a command on a node and returns a success status.
Get Node	Fetches a node by ID or path, or fetches the root node if no ID or path is provided.
Get Node File	Retrieves the content of a file stored on a node.
Get Node References	Returns nodes that reference or are referenced by the specified node.
List Nodes	List the children of a node, or to search for nodes by name or type.
Load Descendant Nodes	Loads all descendant nodes beneath a given node in the Grooper repository.
Reorder Node	Moves a node to a new index within its parent.
Save Node File	Saves base64-encoded binary content or UTF-8 text to a file on a node.
Update Node	Updates the name and/or properties of a node.
Validate Node Properties	Validates the property configuration of a node in the Grooper repository.

Review

Tools for working the human review queue – claiming, completing, and listing review tasks in a Batch Process.

Tool	Description
Close Review Task	Closes or completes a locked Processing Task in a review step.
Get Next Review Task	Opens the next pending Processing Task for a review step in a Batch Process.
Get Review Task	Returns details for a Processing Task by its ID, optionally "opening" the task by obtaining an exclusive lock.
List Review Tasks	Lists Processing Task objects that are pending to a review step in a Batch Process.

Scheduler

Tools for managing scheduled and ad hoc tasks queued to the Action Scheduler service.

Tool	Description
Add Scheduled Task	Submits a new scheduled task to the Action Scheduler queue.
Cancel Scheduled Task	Cancels scheduled tasks that are currently queued or running.
Delete Scheduled Task	Deletes one or more scheduled tasks or scheduled actions from the Action Scheduler queue by ID.
Get Scheduled Task	Fetches a single scheduled task by its integer ID.
List Scheduled Tasks	Lists scheduled tasks in the Grooper repository, with optional filtering and pagination.

Scripts

Tools for creating, compiling, and inspecting script projects on Object Libraries and other scriptable nodes.

Tool	Description
Compile Script	Compiles the script project for an Object Library or other scriptable node.
Create Script	Creates a C# script project for an Object Library or other scriptable node.
Delete Script	Deletes a script project from an Object Library or other scriptable node.
Disable Script	Disables a script project for an Object Library or other scriptable node.
Get Implementation Details	Returns developer-facing implementation details for a base type so a derived class can be authored correctly.
List Members	Lists public members of a type so an agent can discover callable surface area.
List Script Files	Lists script source files for a node's script project.
List Scriptable Types	Lists base types that can be overridden in an Object Library script project.
List Scripts	Lists all nodes in the repository that have script projects attached.

Search

Tools for querying and inspecting Grooper's search indexes, both full-text and vector/semantic.

Tool	Description
Execute Lucene Query	Executes a Lucene full-text query against a search index.
Execute Vector Query	Executes a vector (semantic) query against a search index.
Get Index	Retrieves a search index.
Get Service Usage	Returns usage statistics for the connected AI Search service.
List Indexes	Lists the search indexes defined in the Grooper repository.

Skills

Guided, instructional tools that teach an agent how to perform a specific Grooper design task – creating a project, content model, or data model, for example – rather than performing it directly.

Tool	Description
Read Create Batch Process Skill	Instructions for creating a new Batch Process workflow to accomplish a specific processing objective.
Read Create Content Model Skill	Instructions for planning and creating a Grooper Content Model, which defines the taxonomy, classification, and data extraction structure for a set of documents.
Read Create Data Model Skill	Instructions for creating a Grooper Data Model inside a Content Type. Data Models define the data to be extracted from a document type.
Read Create Project Skill	Instructions for creating a new Grooper project, where document processing workflows are defined and managed.
Read Data Model Styling Skill	Instructions for styling a Grooper Data Model using CSS.
Read Review Document Skill	Instructions for performing a review task on a document in a Batch Process workflow.

Stats

Tools for exploring and querying Grooper's retained processing statistics.

Tool	Description
Explore Stats	Explores saved queries and exact filter values available to Grooper statistics tools.
List Stats Sessions	Lists individual stored statistics sessions with optional selected custom values.
Run Stats Query	Runs a saved or ad hoc Grooper stats query.

System

Tools for managing service instances and repository licensing.

Tool	Description
Check In License	Checks in (releases) one or more active license checkouts.
Get License Package	Retrieves the active license package and current checkouts for this repository.
List Services	Lists service instances in the repository, with optional machine filtering and live status lookup.
Run GCC	Runs a command using the Grooper Command Console (GCC) and returns the output.
Start Service	Starts one or more service instances by ID.
Stop Service	Stops one or more service instances by ID.
Update Service	Updates editable properties of a service instance.

Testing

Tools for test-running a Batch Process Step, Data Element, or Extractor against a sample document.

Tool	Description
Test Batch Process Step	Runs a single Batch Process Step against a specified Batch Object.
Test Data Element Extraction	Tests data extraction for a Data Element using a specified Batch Object as the test document.
Test Extractor	Tests data extraction for an Extractor Node using a specified Batch Object as the test document.

Tools - General

These can be added using the MCP Server or Agent Planner's Tools property editor. They are a grab-bag of broadly useful tools that don't belong to a specific Grooper subsystem – prompting the user, analyzing images, calling web services, querying a database table, searching a directory, sending email, and semantic search.

Tool	Description
Ask	Requests additional information from the user which is needed to generate an execution plan or a response.
Ask VLM	Analyzes an image and extracts information according to a provided schema.
HTTP Call	Invokes a web service endpoint and returns the response.
HTTP Load	Loads the content of a web page and returns it as cleaned HTML or Markdown.
Query Database Table	Runs a query against a database table and returns the results.
Search Entra Recipients	Searches Microsoft Entra ID for active internal users or mail-enabled groups.
Send Email	Sends an email through a configured SMTP server.
Vector Search	Performs vector (semantic) search against a configured search index.

Best practices

Part of what makes an AI agent capable is its ability to adapt and try different solutions to the problem in front of it. This lets an agent surprise you when you give it tasks. Generally, this is a good thing! However, sometimes an agent can surprise you in the wrong way. It is critical for you to understand what your agents have access to both inside and outside of Grooper, and what effects that can produce.

Specifically, consider the risks an agent can introduce:

Normal actions that may have unintended consequences

Data loss - deleting nodes, batches, or documents; overwriting configuration or content files.
Mass mutation - submitted jobs and commands can touch whole batches of documents at once. Furthermore, confirming fields marks invalid values as valid, hiding the very errors that would flag the damage.
Service disruption - stopping services or submitting work that alters live batches.
Remote code execution - some tool categories let an agent compile and run code on the Grooper server.
Data exfiltration - exporting or uploading Grooper content and configuration to external systems.
Credential pivot - Data Connections and CMIS Connections allow Grooper to interoperate with external systems, and other configurations such as Import Providers hold stored remote paths. Through these, an agent may reach systems beyond the Grooper Repository outside of the indented scope.
Unattended work - an agent schedules actions and job submissions that keep running (and keep spending) after the session.

Indirect routes to instability or confusing results

Prompt injection - the content an agent processes is untrusted input. A document's text or a prompt or resource from an external MCP server can potentially carry instructions that steer an agent with write access toward the actions above.
Silent partial overwrite - a write that succeeds while dropping configuration the agent never read.
Stuck review work - claiming a review task and not closing it, which holds an exclusive lock other reviewers cannot take.
Loss of the audit trail - deleting log events, jobs, or scheduled tasks removes the evidence you need to understand what happened.
Escaping the tool surface - the Grooper Command Console and database queries work even when tool categories are restricted, and an agent's host-side tools can bypass Grooper entirely.

Remember: An agent's privileges are its operator's privileges. An administrator driving an agent has an administrator agent. Every practice in the rest of this section exists to limit the damage from the risks above. The practices below are ordered from the broadest controls (environment and identity isolation) down to per-agent tool restrictions.

Start in development environments

Beginners should only use MCP in development environments.

Until you have experience with what AI agents can do with Grooper MCP, isolate their deployment to development Grooper Repositories.

This gives you the freedom to explore agent capabilities without interrupting production systems.
This works well with standard dev/test/prod deployments. Use MCP to create and configure resources in a dev environment, push those resources to a test environment to test them, and then either move them back to dev for further MCP-assisted development or promote them to the production environment.

Agents can make mistakes

An agent is an AI, and AI gets things wrong at some point. To mitigate this:

Scrutinize what an agent tells you closely.
- Don't approve its actions without understanding what it's going to do. Follow up with questions if you need to.
- Read summaries of its actions closely to determine whether it did what it said it did.
Evaluate actions the agent takes outside of Grooper closely.
- Agents have tools they can use outside of Grooper too, and they will use these tools to solve the task when possible.
- This can produce unexpected results if the agent attempts to edit the Grooper database or file store directly with its own tools. Just like you wouldn't want a user to edit the database or file store directly, you wouldn't want an agent to do so either. Within Grooper, agents should work through MCP tools and the Grooper APIs, not raw database access.
Plan for recovery before letting an agent work. See Protect recovery and audit trails.

Isolate access by Grooper Repository and by identity

By Grooper Repository

The easiest way to limit an agent's access to content and configuration in Grooper is to restrict the repositories it can reach.

Beginners should at least isolate agents to development repositories.
Even seasoned users should consider granting MCP access only to development and testing repositories.
This technique can also keep agents out of sensitive environments entirely.

By identity

Understand that an agent acts as its operator. Grooper authenticates with Windows/Entra ID. There is no separate Grooper account system. When a user connects an AI client to Grooper MCP, the agent can do anything that user's account can do.

An administrator driving an agent has an administrator agent. Do not assume the agent is less privileged than you are.

Grooper Permission Sets are your control surface here. A Permission Set applies to Windows or Entra ID users and groups, depending on how you are authenticating Grooper. Permission Sets restrict which pages, node types, and commands they can use. To constrain an agent:

Assign the user/group running the agent a restrictive Permission Set:
- Most importantly grant access only to the tools the agent should use.
- For additional safety, grant only the Page Access its role needs (for example, no Design access for a review or operations agent) and limit Node Permissions to the node types it should interact with and command-level permissions to the commands it requires.
In most cases, you can assume a Grooper user's rights should be similar to the agent's rights. If the user can access the Design page, their agent should have broader access to tools than a user restricted to only the Batches page.
- You still need to review tool access for each Permission Set.
- Do not assume a Permission Set restricting users to the Batches page have a restricted tool set. You will need to curate the tool rights for each Permission Set.
- Do not assume a Permission Set allowing Design page access should have an unrestricted tool set.
If necessary, create a dedicated user or security group for agent-driven work, such as an "AI Agents" group. Run the agent's Grooper session under that identity rather than your own, so its actions are checked against the restrictive set.
Watch for cumulative permissions: a user's effective rights are the union of every Permission Set that applies to them or their groups. A dedicated agent account is only safe if it is not also a member of any group that grants broader access.
Note: Permission Sets restrict MCP tools only when OAuth (Entra ID) authentication is configured. MCP is exposed through the Grooper Web Services (GWS) API set. GWS runs as an IIS application alongside Grooper that can authenticate with Windows, OAuth, or anonymous access. Under Windows authentication, standard AI clients cannot complete the IIS authentication handshake and receive 401. The MCP endpoint effectively fails closed rather than running unpermissioned. Do not treat that as a control. Configure GWS for OAuth, which is the only supported mode in which MCP tool related Permission Sets apply.

Attribution caveat: When connecting via OAuth, the Event Log records actions under the connecting Windows account. When an agent operates as your own identity, its actions are indistinguishable from yours in the log. When using anonymous authorization, the Event Log records actions under the GWS App Pool's service account in IIS.

Use custom MCP Servers to instruct agents and restrict tool categories

The default MCP endpoint exposed from GWS includes every Grooper tool category and no custom instructions. It is also a network-exposed administrative surface - treat it like one and restrict which accounts can reach it. Adding your own MCP Server nodes gives you more control over how an agent acts and which tools it can reach.

Use Instructions to guide behavior.
Limit tool access by selecting only the Tool Categories relevant to the agent.
- Example: The Scripts category exposes tools for authoring and compiling Object Libraries. Compiling a script executes C# code on the machine hosting Grooper. Do not expose this category in a production repository.
- Example: The Search category exposes tools for querying document indexes in Grooper. If your repository does not use this feature, remove these tools so the agent doesn't waste its time evaluating whether it should attempt to use them.
Gate destructive and operational tools unless the agent genuinely needs them:
- Node deletion and cleanup, including deleting log events (this erases the audit trail you rely on for recovery and investigation).
- Starting, stopping, or updating service instances, which can halt processing.
- Job submission with Execute or Launch Process activities, which run external processes on the server.
- File and archive writes: saving node files, importing ZIP archives (which can overwrite configuration or inject nodes), and creating ZIPs uploaded to external URLs.
Build one MCP Server per agent role. For example, a review agent only needs the review-queue tools (get and close review tasks) and should not see configuration or deletion tools at all.
Remember that an agent's reach is not limited to Grooper. MCP Server nodes can also connect Grooper outbound to external MCP servers, and agents keep whatever tools their host runtime provides.

Protect recovery and audit trails

Back up the database and file store regularly. This is the only reliable recovery path for deleted or corrupted content, including Batches and documents an agent cannot recover on its own.
Node configuration changes can be rolled back manually. Furthermore, the Event Log records configuration changes for audit purposes, and some node types (such as Batch Processes) retain working, published, and archived versions you can restore. Treat the Event Log as evidence for investigation, not as a guaranteed undo.
By setting a custom MCP Server's Instructions you can ask the agent to require confirmation before irreversible operations such as deleting nodes or disposing Batches. A human-in-the-loop checkpoint is cheap insurance.
- Be aware, instructions are guidance not mandates. Agents are not guaranteed to follow instructions to the letter. Particularly for log running sessions, an agent may lose context for the original instruction. This could lead an agent to delete a node, without asking for permission first, despite that instruction being made on the MCP Server node.

Connecting a Grooper MCP Server to an AI client

Connecting Grooper MCP Servers to AI clients such as Claude Code or GitHub Copilot varies slightly from client to client. However, the broad strokes involve editing some kind of config file (either directly or indirectly) and entering a URL for the MCP Server.

The MCP Server's URL always takes the following form, depending on if you're using the default MCP Server or a custom MCP Server:

Default MCP Server - Exposed by GWS

http(s)://<GROOPER-HOST>/gws/<GROOPER-REPOSITORY>/mcp

Custom MCP Server - Added and edited from the Design page

http(s)://<GROOPER-HOST>/gws/<GROOPER-REPOSITORY>/mcp/servers/<MCP-SERVER-NAME>

In either case, replace the following:

<GROOPER-HOST>: Replace this with the server host where the Grooper and GWS apps are installed.
<GROOPER-REPOSITORY>: Replace this with the Grooper Repository's URL friendly name or Repository ID (You can grab this by going to the Design page, selecting the Root node and copying the GUID value from the "Repository ID" property).
<MCP-SERVER-NAME>: Replace this with whatever you named your MCP Server in Grooper.
http(s): Use http or https depending on your environment. The majority of users will enter https. http is only acceptable for dev environments.

The sections below walk through connecting a Grooper MCP Server to specific AI clients.

Claude Code/Claude Desktop

This guide will list the basic steps for hooking up a Grooper MCP Server to Claude Code. This will let you use Grooper tools from a Grooper MCP Server from:

A terminal window, by typing claude directly (the "Claude Code CLI").
The Code tab in Claude Desktop.

To get started:

Open Windows PowerShell.
Run the following command to install Claude Code. This may take a moment. Wait for the "Installation complete!" message at the end.

irm https://claude.ai/install.ps1 | iex

Close the PowerShell window and open a brand new one.
Run the following command to double-check Claude Code was installed. It should print a version number

claude --version

Run this command to add the Grooper MCP Server connection.

claude mcp add --transport http --scope user <NAME-IN-CLAUDE> "http(s)://<GROOPER-HOST>/gws/<GROOPER-REPOSITORY>/mcp"

http(s): Use http or https depending on your environment. The majority of users will enter https. http is only acceptable for dev environments.
<NAME-IN-CLAUDE>: Replace this with whatever you want to name the MCP server, as seen in Claude, for example grooper or grooper-prod or grooper-dev.
<GROOPER-HOST>: Replace this with the server host where the Grooper and GWS apps are installed.
<GROOPER-REPOSITORY-ID>: Replace this with the Grooper Repository's ID (You can grab this by going to the Design page, selecting the Root node and copying the GUID value from the "Repository ID" property).
<MCP-SERVER-NAME>: If using a custom MCP Server, add /servers/<MCP-SERVER-NAME> to the end of the URL. Replace this with whatever you named your MCP Server in Grooper.
--scope user: This is recommended to make the server available everywhere for your account, not just locally to a single folder (--scope local).

Run this command to verify you've registered the server and show its status.

claude mcp list

If Claude Desktop is open, close and re-open it.
Go to the Code tab, start a new session and enter "/mcp". You should see the MCP Server you just added in the list.
Start prompting requests! The following are safe, read-only requests that will get you started.
- List the Projects in my Grooper Repository and describe each Content Model.
- Show me the steps in the list specific process name here Batch Process and what each Activity is configured to do.
- List the most recent Production Batch and tell me what step it is on.
- Read the Create Batch Process skill from the Grooper server and summarize the recommended step order for scanned paper documents.

VS Code (GitHub Copilot)

VS Code with the GitHub Copilot extension supports MCP servers in Agent mode. VS Code is a popular platform by itself, making it a good option for users who already have it installed and are familiar with it.

These instructions assume you already have VS Code installed with the GitHub Copilot extension, and that you're signed in to GitHub with an active Copilot license.

You can install the GitHub Copilot extension from the VS Code Marketplace

Note for Copilot Business/Enterprise orgs: The "MCP servers in Copilot" policy must be enabled by an admin before MCP servers will work. This is off by default. If the MCP commands below are missing entirely from the Command Palette (rather than just failing to connect), this is likely why.

MCP servers are added by editing a config file called mcp.json.

Press Ctrl+Shift+P to open the Command Palette.
Type and select MCP: Open User Configuration. This opens (or creates) your global mcp.json file.
If no "servers" block exists in the JSON config, add the following entry (before the ending } in the JSON):

  "servers": {
    "<NAME-IN-COPILOT>": {
      "type": "http",
      "url": "http(s)://<GROOPER-HOST>/gws/<GROOPER-REPOSITORY>/mcp"
    }
  }

<NAME-IN-COPILOT>: Replace this with whatever you want to name the MCP server, as seen in Copilot, for example grooper or grooper-prod or grooper-dev.
<GROOPER-HOST>: Replace this with the server host where the Grooper and GWS apps are installed.
<GROOPER-REPOSITORY-ID>: Replace this with the Grooper Repository's ID (You can grab this by going to the Design page, selecting the Root node and copying the GUID value from the "Repository ID" property).
<MCP-SERVER-NAME>: If using a custom MCP Server, add /servers/<MCP-SERVER-NAME> to the end of the URL. Replace this with whatever you named your MCP Server in Grooper.
http(s): Use http or https depending on your environment. The majority of users will enter https. http is only acceptable for dev environments.

If there are other servers already listed in the "servers" block, do not delete any existing entries. Simply add yours as a new entry in the object.
Important: The root key must be "servers", not "mcpServers". VS Code silently ignores the wrong key with no error message, so this is the single most common mistake when setting this up.
Save the file. Look for a "Start" link above your server's entry in the file (VS Code adds this automatically) and click it.
Open Copilot Chat and switch the mode dropdown from Ask to Agent. MCP tools are not available in Ask or Edit mode.
Click the tools icon in the chat box and confirm your server appears in the list.
Start prompting requests! The following are safe, read-only requests that will get you started.
- List the Projects in my Grooper Repository and describe each Content Model.
- Show me the steps in the list specific process name here Batch Process and what each Activity is configured to do.
- List the most recent Production Batch and tell me what step it is on.
- Read the Create Batch Process skill from the Grooper server and summarize the recommended step order for scanned paper documents.

OpenCode

OpenCode is an open source AI coding agent available as a terminal-based interface or a desktop app. It's an effective and cost effective way to get connected to a Grooper MCP Server. OpenCode uses the AI SDK and Models.dev to support 75+ LLM providers and supports running local models on-premises.

These instructions assume you already have OpenCode installed and connected to a model provider.

You can download OpenCode at opencode.ai/download
You can refer to information on how to set up and configure OpenCode at opencode.ai/docs

MCP servers are added by editing the OpenCode config file on your machine.

Open Windows File explorer and go to C:\Users\<YOUR-USER-NAME>\.config\opencode
Open opencode.json in a text editor.
If no such "mcp" block in the JSON config exists, add the following entry to the bottom (before the ending } in the JSON):

  "mcp": {
    "<NAME-IN-OPENCODE>": {
      "type": "remote",
      "url": "http(s)://<GROOPER-HOST>/gws/<GROOPER-REPOSITORY>/mcp",
      "enabled": true
    }
  }

<NAME-IN-OPENCODE>: Replace this with whatever you want to name the MCP server, as seen in OpenCode, for example grooper or grooper-prod or grooper-dev.
<GROOPER-HOST>: Replace this with the server host where the Grooper and GWS apps are installed.
<GROOPER-REPOSITORY-ID>: Replace this with the Grooper Repository's ID (You can grab this by going to the Design page, selecting the Root node and copying the GUID value from the "Repository ID" property).
<MCP-SERVER-NAME>: If using a custom MCP Server, add /servers/<MCP-SERVER-NAME> to the end of the URL. Replace this with whatever you named your MCP Server in Grooper.
http(s): Use http or https depending on your environment. The majority of users will enter https. http is only acceptable for dev environments.

If there are other MCP servers listed in the "mcp" block, do not delete any entries in the block. Simply add your server (<NAME-IN-OPENCODE>": {...}) in the object.
Fully quit and reopen OpenCode for the changes to take effect.
In the desktop app, if you have "Server status" enabled in the Settings (General > Advanced), you can verify your MCP Server is connected by pressing the "Status" button in the top tool bar.
Start prompting requests! The following are safe, read-only requests that will get you started.
- List the Projects in my Grooper Repository and describe each Content Model.
- Show me the steps in the list specific process name here Batch Process and what each Activity is configured to do.
- List the most recent Production Batch and tell me what step it is on.
- Read the Create Batch Process skill from the Grooper server and summarize the recommended step order for scanned paper documents.

Tool	Description
Activate Tool Connection	Activates a tool connection, bringing its tools into scope so they can be called.
List Tool Connections	Lists all connections to external tools.
List Tools	Lists the tools available.
Search Tools	Searches for additional tools.