PrivateBot
DEVELOPER DOCS

Connect an MCP service

This starter declares a remote MCP service; it does not host one. You need an HTTP endpoint implementing MCP.

Declare supported platforms

To publish, extension.json must declare a non-empty supportedHosts array containing web, desktop, or both. These values identify the product host: the desktop app remains desktop even when Electron renders its interface in a browser engine. Each MCP or Skill contribution may narrow supportedHosts to a subset of the extension’s platforms; omitting it inherits the top-level declaration. Every MCP listed in a Skill’s requiresMcp must be available on every platform that Skill supports. Web and Desktop each select the latest published release compatible with their own host, so they may use different versions.

Download starter ZIP

1. Prepare your service

Use MCP development tools to check connection, tool discovery, and calls. Production services use HTTPS; loopback HTTP is allowed for local development. A loopback address is not a public service endpoint.

2. Describe the connection

Replace the namespace, extension metadata, and example.com URL. That URL is a placeholder, not a working service. The current extension protocol supports HTTP MCP, not packaged stdio launch commands.

{
  "schemaVersion": 1,
  "id": "your-name/service-tools",
  "version": "1.0.0",
  "name": "Service tools",
  "description": "Connect an existing remote MCP service.",
  "supportedHosts": [
    "web",
    "desktop"
  ],
  "tags": [
    "tools"
  ],
  "license": "MIT",
  "contributes": {
    "mcp": [
      {
        "id": "service-tools",
        "transport": "http",
        "url": "https://example.com/mcp",
        "auth": {
          "type": "none"
        }
      }
    ],
    "skills": []
  }
}

3. Declare authentication

auth.type may be none, bearer, or oauth. Bearer authentication needs a label; an OAuth service must implement its authorization flow. Users provide credentials; never include them in the manifest or README.

"auth": { "type": "bearer", "label": "Service API token" }

4. Optionally add a Skill, then package

Add a Skill when your tools need instructions, using requiresMcp to reference an MCP ID in the same manifest. ZIP contents are limited to extension.json, README.md, icon.png, and files under skills/. Deploy service code separately.

zip extension.zip extension.json README.md

Local development: current support

The client currently installs published marketplace extensions; importing a local extension package is not yet available. Validate your service with MCP development tools and review Skill instructions and example outputs first. Website checks validate package format, not execution in PrivateBot. Do not publish an unverified extension just to debug it.