Using Custom Tools

You can write and publish your own components to your Pipedream workspace to use with Connect. This complements the public actions available in Pipedream’s global registry.

Overview

Custom tools are Node.js modules that you develop using the Pipedream Components API and publish to your Pipedream workspace. Once published, they become available across all Connect APIs, including the list, retrieve, run endpoints, etc.

Publishing custom tools is available to Pipedream customers on the Business plan.

Creating custom tools

Custom tools use the same development workflow as standard Pipedream components:

Write your component using the Pipedream Components API
Follow component guidelines outlined in the component development docs
Use the Pipedream CLI to publish your component with a Connect-specific flag

Custom tools are actions. Check out the actions quickstart guide for step-by-step development instructions. Support for custom sources (triggers) is coming soon.

Publishing for Connect

To make your custom components available in Connect, use the pd publish command with the --connect-environment flag:

pd publish my-custom-action.mjs --connect-environment development

Environments

The --connect-environment flag accepts two values:

development: makes the component available to your Pipedream workspace in Connect in development
production: makes the component available to your Pipedream workspace in Connect in production

⚠️

Components published to development will only be available in the development environment, and vice versa for production.

Using custom tools

Once published, your custom tools appear alongside public components in Connect APIs:

List endpoints: Custom tools are included in component listing responses
Retrieve endpoints: You can fetch details about your custom components
Run endpoints: Execute your custom tools with the same API calls used for public components

Referencing custom tools

Custom tools are identified with a ~/ prefix in their component ID. For example, if you publish a component with the key google_sheets-update-file, it will appear in Connect APIs as ~/google_sheets-update-file.

When making API calls to list, retrieve, or run custom tools, use the prefixed ID:

# List all components (includes custom tools with ~/ prefix)
GET /v1/components
 
# Retrieve a specific custom tool
GET /v1/components/~/google_sheets-update-file
 
# Run a custom tool
POST /v1/components/~/google_sheets-update-file/run

The Connect API treats custom tools identically to public components, ensuring a consistent integration experience.

Custom tools in MCP

Custom actions that you publish are automatically exposed as tools in the Pipedream MCP server for the relevant app.

Example workflow

Here’s a typical workflow for creating and using a custom tool:

Develop locally using your preferred editor
Test your component using local testing for actions
Publish to Connect with the appropriate environment flag
Integrate via Connect APIs in your application

Test your custom tools in your application directly or run Pipedream’s SDK playground locally with your Pipedream credentials.

Best practices

Follow naming conventions: Use clear, descriptive names for your tools
Include proper documentation: Add helpful descriptions and prop labels for easier configuration
Test thoroughly: Validate your components work as expected before publishing to production
Version management: Update component versions when making changes
Environment separation: Use development environment for testing, production for live integrations

Getting help

For component development questions, visit the Pipedream Support. For Connect-specific integration help, refer to the Connect docs.

Working with Files Overview