Plugins
Prerequisites: Before reading this article, it is recommended to first understand Resources & Credentials and Extensions.
Plugins add new resource types to the Monstrum platform. All plugins on the platform are officially approved and reviewed by administrators to ensure security and quality. If you need to integrate custom tools, you can load plugins through a local Agent (see Local Agent Integration for details).
Overview
Two Ways to Use Plugins
| Method | Description | Execution Location |
|---|---|---|
| Platform Plugins | Officially approved plugins installed to the platform by administrators | Cloud (platform-side) |
| Agent Plugins | Plugins installed by users on their local Agent | Local (Agent-side) |
Platform Plugins are the focus of this article. They are officially reviewed and execute in the platform cloud after installation, making them available to all users.
Agent Plugins are managed by users themselves. Place the .mst plugin package in the local Agent’s configuration, and after the Agent connects to the platform, tools are automatically registered. This approach is suitable for private system integrations or plugins not yet listed in the official marketplace. See the tool registration section in Local Agent Integration for details.
What Are Platform Plugins
A Platform Plugin is a resource type extension package that contains:
- Resource type definition: declares the tool list, authentication methods, permission dimensions, and configuration forms
- Executor: the actual execution logic for tool calls
Installing a plugin = registering a new resource type on the platform. Afterward, you can create a Resource, add a Credential, and bind it to a Bot just like a built-in resource.
Plugin Resources vs. Built-in Resources
| Built-in Resources | Plugin Resources | |
|---|---|---|
| Source | Included with the platform | Official marketplace, installed by administrators |
| Types | SSH, MCP, Bot, Web, Web3, Agent | GitHub, GitLab, Notion, etc. |
| Configuration | Same | Same |
| Binding and permissions | Same | Same |
| Authentication | Type-specific | Plugin-specific (may include OAuth) |
After installation, plugin resources appear alongside built-in resources on the resource management page, providing a consistent user experience.
Plugin Marketplace
- In the left navigation bar, click Marketplace > Plugin Marketplace
- Browse the available plugin list
The page supports:
- Search: Search plugins by keyword
- Sort: Sort by downloads / favorites / newest
- Tag filter: Filter by tags (productivity, database, devops, etc.)
- Source filter: Official plugins / Community plugins
Click a plugin card to enter its details page and view:
- README: Plugin introduction and usage instructions
- Tool list: All tools provided by the plugin, including names, descriptions, and parameter definitions
- Version history: Version update records
Official vs. Community Plugins
The Plugin Marketplace displays two types of plugins:
| Official Plugins | Community Plugins | |
|---|---|---|
| Source | Published by the platform team | Submitted by community users |
| Review | Reviewed by administrators | Community-governed (ratings, reports) |
| Execution location | Platform cloud | User’s local Agent |
| Installation | Installed by administrators on the platform | Installed by users on their local Agent |
| Security responsibility | Platform | User |
Using official plugins: Confirm the administrator has installed it, then create a Resource directly in resource management.
Using community plugins: Copy the installation command from the plugin details page and run it on your local Agent. After the Agent connects to the platform, tools are automatically registered as resources.
Submitting Community Plugins
If you have developed a plugin and want to share it with the community:
- Package the plugin as a
.mstfile - Submit it to the community section in the Plugin Marketplace
- Other users can browse, rate, and install it on their own Agent
Using Official Plugin Resources
After an administrator installs an official plugin, the corresponding resource type appears in the “Available Resources” list on the resource management page. The usage flow is identical to built-in resources:
1. Create a Resource
On the resource management page, find the resource type provided by the plugin and click create. Fill in the configuration information (the form is defined by the plugin and varies between plugins).
2. Add Credentials
Add credentials based on the authentication methods supported by the plugin:
- API Key / Token: Enter the key directly
- OAuth: Authorize through an OAuth flow (see the OAuth section below)
- Other methods: Declared by the plugin; the platform automatically renders the form
3. Bind to a Bot
In the Bot details page under resource configuration, bind the Resource and configure permissions. The permission dimensions declared by the plugin will automatically appear in the configuration form.
OAuth Authentication
Some plugins support OAuth authentication (e.g., GitHub, GitLab, Slack). OAuth offers the following advantages over manually entering API keys:
- Automatic refresh: The platform automatically detects tokens nearing expiration and refreshes them
- Fine-grained access control: Limit access scope through OAuth scopes
- Security isolation: Users don’t need to hand long-lived credentials to the platform; authorization can be revoked at any time
Supported OAuth Flows
| Mode | Description | Typical Scenarios |
|---|---|---|
| Authorization Code | User authorizes in the browser; the most common flow | GitHub, GitLab, Slack integrations |
| Client Credentials | Machine-to-machine; no user interaction required | MCP server OAuth 2.1 |
| Device Code | Authorization in environments without a browser | Remote servers, CLI environments |
Creating an OAuth Application
Before using OAuth, you need to create an OAuth application (OAuth Provider) to store the client credentials assigned by the third-party platform:
- When creating a resource type that supports OAuth in resource management, select the OAuth authentication method
- If an OAuth application has not yet been configured, the platform will guide you through creating one
- Fill in:
| Field | Description |
|---|---|
| Provider name | e.g., github-corp, slack-team; must be unique within the workspace |
| Resource type | Select the resource type this OAuth application corresponds to |
| Client ID | Obtained after creating an OAuth App on the third-party platform |
| Client Secret | Client secret (stored with AES-256 encryption) |
| Callback URL | Leave blank to auto-generate; format is {platform-url}/api/oauth/callback |
| Additional scopes | OAuth scopes to append beyond the default scopes |
Callback URL Configuration
The callback URL (Redirect URI) is critical for the OAuth authorization code flow. After creating the OAuth application, you need to enter the same callback URL in the third-party platform’s OAuth App settings:
GitHub: Settings > Developer settings > OAuth Apps > Authorization callback URL
GitLab: Settings > Applications > Redirect URI
Slack: App management page > OAuth & Permissions > Redirect URLs
The callback URL must exactly match the configuration on the third-party platform (including protocol, domain, and path), or authorization will fail.
Authorization Flow
Authorization Code:
- When creating a resource, select OAuth Authorization Code authentication
- Select the configured OAuth application
- Click Authorize > the browser redirects to the third-party authorization page
- The user confirms authorization > callback to the platform > Credential is automatically created
Client Credentials:
- Select OAuth Client Credentials authentication
- Select the OAuth application
- Click Get Credentials > the platform automatically obtains a token using the Client ID + Secret
Device Code:
- Select OAuth Device Code authentication
- Click Authorize > the page displays a user code and verification URL
- Open the verification URL in a browser on any device and enter the user code to complete authorization
- The platform automatically detects that authorization is complete and creates the Credential
Token Lifecycle
The platform automatically manages the OAuth token lifecycle:
- Periodic checks: Automatically scans for tokens nearing expiration and refreshes them in advance
- Retry on execution: Automatically refreshes the token and retries when a tool call encounters a 401
- Refresh failure notification: When token refresh fails, the Credential is marked as expired and the platform sends a notification
| OAuth Mode | Refresh Method |
|---|---|
| Authorization Code | Uses the Refresh Token. If the Refresh Token expires, re-authorization is required |
| Client Credentials | Directly obtains a new token using Client ID + Secret |
| Device Code | Uses the Refresh Token when available; otherwise, the device code flow must be repeated |
To refresh immediately, click Refresh Token in the Credential section of the Resource details page.
Example: GitHub Plugin Configuration
Using the GitHub plugin as an example, here is the complete flow for using a Platform Plugin:
1. Confirm the plugin is installed
Check the Plugin Marketplace to confirm the GitHub plugin is installed. If not, contact your administrator.
2. Create an OAuth App on GitHub
- Go to GitHub Settings > Developer settings > OAuth Apps > New OAuth App
- Fill in Application name and Homepage URL
- Enter Monstrum’s callback URL in the Authorization callback URL field
- Record the Client ID and Client Secret
3. Create a GitHub resource in Monstrum
- Find the GitHub type in resource management and click create
- Select OAuth Authorization Code as the authentication method
- Create an OAuth application and enter the Client ID and Client Secret
- Click Authorize and confirm on the GitHub page
4. Bind to a Bot
- Bind the GitHub resource in the Bot’s resource configuration
- Select the allowed operations (e.g.,
issue.read,pr.read) - Configure repository allowlists (e.g.,
org/repo-*)
FAQ
Can I upload plugins to the platform myself?
No. Plugins on the platform are managed centrally by administrators. If you have custom tools to integrate, you have two options:
- Install the plugin on a local Agent and bridge it to the platform (see Local Agent Integration for details)
- Contact an administrator to request listing the plugin on the platform
How do I update an installed plugin?
Find the plugin in the Plugin Marketplace. If a new version is available, the page will display an update option. The update operation requires administrator privileges.
OAuth authorization succeeded but still shows “authentication required”
- Incorrect Client Secret: Edit the OAuth application and re-enter the correct secret
- Callback URL mismatch: Confirm both sides have an identical configuration
- Insufficient scopes: Some platforms reject authorization when scopes are insufficient; check if additional scopes are needed
Token expires frequently
- Access Token validity is determined by the third-party platform (it may be as short as 1-2 hours); the platform automatically refreshes when a Refresh Token is available
- If the Refresh Token has been revoked (user revoked authorization on the third-party platform), re-authorization is required
- If the Client Secret has been rotated by the third-party, it needs to be updated in the OAuth application
Client Credentials fails to obtain a token
- Verify that the Client ID and Secret are correct
- Confirm the token endpoint is accessible
- Check whether the requested scopes are supported by the third-party