Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bruhsb/paperclip-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Plugins extend the Paperclip control plane with additional capabilities — custom integrations, workflow hooks, and third-party connectors are all delivered as npm packages installed into the Paperclip instance. The six plugin tools cover the full lifecycle: discover what’s available, install from the npm registry or a local path, inspect a specific plugin’s configuration and health, browse example implementations, and toggle plugins on or off without uninstalling them.
All plugin tools are board-only — they require a board (human-user) API key. Agent API keys will receive a 403 Forbidden response. Set your PAPERCLIP_API_KEY to a board key before using any plugin tool.

List Plugins

Audit installed plugins with optional status filter

Get Plugin

Inspect a specific plugin’s config and health

Install Plugin

Install a plugin from npm or a local path

List Examples

Browse reference plugin implementations

Enable Plugin

Re-activate a previously disabled plugin

Disable Plugin

Temporarily deactivate a plugin without uninstalling

paperclip_list_plugins

List installed plugins for the Paperclip instance. Supports filtering by lifecycle status and paginating through large plugin lists.
status
"installed" | "ready" | "disabled" | "error" | "upgrade_pending" | "uninstalled"
Filter by plugin lifecycle status. Omit to return all plugins regardless of status.
limit
integer
Maximum plugins per page. Range 1–100. Defaults to 50.
offset
integer
Number of plugins to skip for pagination. Defaults to 0.
response_format
"markdown" | "json"
Output format. markdown (default) produces a human-readable list; json returns a structured envelope.
Returns: Pagination envelope { items: Plugin[], total, count, offset, limit, has_more, next_offset }. Each Plugin item contains: pluginKey, packageName, displayName, description, status, version. Usage notes:
  • Use when auditing which plugins are installed or finding plugins in an error state that need attention.
  • For full plugin details including health and config, use paperclip_get_plugin with a specific pluginKey.
  • Filter by status: "error" to quickly surface plugins that need remediation.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedThis tool requires a board (human-user) API key
{
  "tool": "paperclip_list_plugins",
  "arguments": {
    "status": "error",
    "response_format": "json"
  }
}

paperclip_get_plugin

Get detailed information about a specific installed plugin by its key, including configuration and health status.
pluginKey
string
required
Plugin key (e.g. paperclip.hello-world-example or @acme/plugin-linear). The key is URL-encoded automatically before the API request.
response_format
"markdown" | "json"
Output format. markdown (default) or json for structured output.
Returns: Plugin object: pluginKey, packageName, displayName, description, status, version, config, health. Usage notes:
  • Use to inspect a plugin’s config and health before enabling or modifying it.
  • To list all plugins at once, use paperclip_list_plugins instead.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
404Plugin not foundVerify the key with paperclip_list_plugins
{
  "tool": "paperclip_get_plugin",
  "arguments": {
    "pluginKey": "paperclip.hello-world-example",
    "response_format": "json"
  }
}

paperclip_install_plugin

Install a plugin from the npm registry or a local filesystem path into the Paperclip instance. This is an open-world operation — the API fetches the package from npm when isLocalPath is false.
packageName
string
required
npm package name to install (e.g. @paperclipai/plugin-hello-world-example). When isLocalPath is true, this is instead a local filesystem path.
version
string
Specific package version to install (e.g. 1.2.3). Omit to install the latest published version.
isLocalPath
boolean
Set to true when packageName is a local filesystem path rather than an npm package name. Useful for testing locally built plugins.
Returns: Installation result object with: pluginKey, packageName, status, message confirming the install outcome. Usage notes:
  • Use when adding a new plugin capability from the npm registry or a local build.
  • If the plugin is already installed but disabled, use paperclip_enable_plugin to re-activate it instead of reinstalling.
  • For discovering available example plugins to install, use paperclip_list_plugin_examples first.
Errors:
CodeMeaningResolution
400Install failed (npm error)Verify the package name exists in the npm registry
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
{
  "tool": "paperclip_install_plugin",
  "arguments": {
    "packageName": "@paperclipai/plugin-hello-world-example",
    "version": "1.0.0"
  }
}

paperclip_list_plugin_examples

List available reference plugin implementations that can be installed to understand the plugin API surface.
response_format
"markdown" | "json"
Output format. markdown (default) or json for structured output.
Returns: Array of example plugin descriptors: packageName, pluginKey, displayName, description, localPath, tag. Usage notes:
  • Use when exploring the plugin API surface or looking for a reference implementation to base new work on.
  • To see the list of already-installed plugins, use paperclip_list_plugins instead.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
{
  "tool": "paperclip_list_plugin_examples",
  "arguments": {
    "response_format": "json"
  }
}

paperclip_enable_plugin

Enable a previously disabled plugin by its key. Safe to call even if the plugin is already enabled — the operation is idempotent.
pluginKey
string
required
Plugin key (e.g. paperclip.hello-world-example or @acme/plugin-linear). URL-encoded automatically.
Returns: Updated plugin object with new status confirming the plugin is now enabled. Usage notes:
  • Use when re-activating a plugin that was disabled without uninstalling it.
  • If the plugin is not yet installed, use paperclip_install_plugin first.
  • This call is idempotent — calling it on an already-enabled plugin is safe.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
404Plugin not foundVerify the key with paperclip_list_plugins
{
  "tool": "paperclip_enable_plugin",
  "arguments": {
    "pluginKey": "paperclip.hello-world-example"
  }
}

paperclip_disable_plugin

Disable an active plugin by its key without uninstalling it. The plugin’s configuration is preserved and it can be re-enabled later with paperclip_enable_plugin.
This tool has destructiveHint: true. Disabling a plugin will immediately stop it from processing events. If other workflows depend on the plugin, they may fail until it is re-enabled.
pluginKey
string
required
Plugin key (e.g. paperclip.hello-world-example or @acme/plugin-linear). URL-encoded automatically.
Returns: Updated plugin object with new status confirming the plugin is now disabled. Usage notes:
  • Use to temporarily deactivate a plugin without losing its installation or configuration.
  • To permanently remove a plugin, use the uninstall flow — disabling is always reversible.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
404Plugin not foundVerify the key with paperclip_list_plugins
{
  "tool": "paperclip_disable_plugin",
  "arguments": {
    "pluginKey": "paperclip.hello-world-example"
  }
}

Build docs developers (and LLMs) love