Custom Tools

Build custom tools and publish them privately. Only your organization can see and install them.

What are MCP servers?

MCP (Model Context Protocol) is how AI agents connect to external tools. An MCP server is a small program that gives the AI abilities like:

• Reading/writing files
• Querying databases
• Calling APIs
• Sending emails or Slack messages

ToolPlex comes with thousands of public MCP servers you can install. But you can also build your own for custom integrations - connecting to internal APIs, proprietary systems, or anything specific to your workflow.

Getting started

Use our example private tool as a template. It's a working MCP server you can clone and customize.

git clone https://github.com/toolplex/private-tool-example.git my-tool
cd my-tool

Setting up your tool

1. Get your scope ID

In ToolPlex Desktop, go to the Org Settings panel to find your organization's Scope ID.

Your scope ID looks like tp-org-abc123def45.

2. Update the template

Replace <YOUR_SCOPE_ID> with your actual scope ID in:

• package.json - the package name
• README.md - installation instructions

For example, if your scope ID is tp-org-abc123def45:

{
  "name": "@tp-org-abc123def45/my-tool",
  "version": "1.0.0"
}

3. Build your tool

Customize the code in src/ to do whatever you need. The template includes a product catalog with search, detail, and low-stock tools — replace the mock data with calls to your own systems.

Environment variables and authentication

Most custom tools need to authenticate with an internal API or database. Use environment variables for all credentials — never hardcode secrets in your tool's source code.

Reading environment variables

Validate required variables at startup so the tool fails immediately with a clear error:

const API_URL = process.env.MY_API_URL;
const API_TOKEN = process.env.MY_API_TOKEN;

if (!API_URL) throw new Error("MY_API_URL environment variable is required");
if (!API_TOKEN) throw new Error("MY_API_TOKEN environment variable is required");

Setting variables for cloud execution

In ToolPlex Desktop, go to Org Settings > Environment variables to add secrets. These are available to all cloud tools at runtime.

Variable names must use uppercase letters, numbers, and underscores (e.g. SLACK_WEBHOOK_URL). Values are masked in the UI.

Local development

For local testing, export variables in your shell or use a .env file:

export MY_API_URL=https://internal.example.com/api
export MY_API_TOKEN=your-token-here
node dist/index.js

Tip: Add .env to your .gitignore so credentials never end up in version control.

For a complete walkthrough, see the Build a Custom Tool tutorial.

Customizing how your tool appears

By default, ToolPlex auto-generates a display name, description, and keywords from your README. To override these, add a toolplex key to your package.json:

{
  "name": "@tp-org-abc123def45/my-tool",
  "version": "1.0.0",
  "toolplex": {
    "server_name": "Acme Internal Reports",
    "description": "Generate CSV reports from our internal data warehouse",
    "keywords": ["reports", "csv", "data-warehouse"]
  }
}

All three fields are optional — only the ones you include will override the auto-generated values:

To update these for an already-published tool, change the values, bump the version, and publish again.

Publishing

Login to the registry

npm login --registry=YOUR_REGISTRY_URL

Use the credentials shown in your Org Settings panel.

Find your registry URL in the Org Settings panel in ToolPlex Desktop.

Publish your tool

npm publish --registry=YOUR_REGISTRY_URL

Your tool will appear in ToolPlex Desktop within about 30 minutes.

Publishing updates

When you make changes, increment the version in package.json and publish again:

npm version patch  # or minor, or major
npm publish --registry=YOUR_REGISTRY_URL

Unpublishing

To remove a tool from the registry:

npm unpublish @tp-org-abc123def45/my-tool --force --registry=YOUR_REGISTRY_URL

This removes the tool entirely. It will no longer appear in search results or be installable. Users who already have it installed will keep their local copy, but won't receive updates.

Warning: Unpublishing is permanent. If you want to publish the same package name again, you'll need to use a new version number.

Installing custom tools

1. In ToolPlex Desktop, go to the Servers panel
2. Click the Private tab
3. Find your tool and click Install

Same process as installing any public tool.

Who can see what

Tools published to your organization scope (@tp-org-...) are visible to all members of your organization.

Only organization admins and owners can publish tools.