Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/superradcompany/tool-cli/llms.txt

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

MCPB was designed for bundled servers that run locally over stdio. But many real-world MCP servers don’t fit that model: they run via npx or uvx (nothing to bundle), they’re remote HTTP endpoints, or they need host-managed ports and OAuth flows the base spec doesn’t cover. MCPBX (.mcpbx) is a superset of MCPB that fills those gaps. It adds:
  • HTTP transport — connect to servers via url instead of spawning a subprocess
  • Reference mode — point to an external command (npx, uvx) or remote URL without bundling any code
  • OAuth configuration — client ID, authorization URL, token URL, and scopes for browser-based auth flows
  • system_config — host-managed resources like port assignment and temp/data directories
  • Template functions — construct auth headers dynamically using ${user_config.*} and ${system_config.*} interpolation
The separate file extension lets hosts know upfront whether they can handle the manifest. tool-cli picks the right format automatically — you never set it manually.

​
When to use .mcpb vs .mcpbx

Use .mcpb for bundled servers that run locally over stdio. These are the most common case:
  • Node.js or Python servers with a bundled entry_point
  • Rust or Go binaries compiled into the bundle
  • No HTTP endpoint, no OAuth, no system_config
manifest.json
{
  "manifest_version": "0.3",
  "name": "my-tool",
  "version": "0.1.0",
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"]
    }
  }
}

​
MCPBX features

​
HTTP transport

Set server.transport to "http" and provide a url in mcp_config. The host connects to that URL instead of spawning a subprocess.
manifest.json
{
  "manifest_version": "0.3",
  "name": "my-http-tool",
  "version": "0.1.0",
  "server": {
    "type": "node",
    "transport": "http",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": [
        "${__dirname}/server/index.js",
        "--port=${system_config.port}",
        "--host=${user_config.host}"
      ],
      "url": "http://${user_config.host}:${system_config.port}/mcp"
    }
  },
  "user_config": {
    "host": {
      "type": "string",
      "title": "Bind Address",
      "default": "127.0.0.1"
    }
  },
  "system_config": {
    "port": {
      "type": "port",
      "title": "Server Port",
      "default": 3000
    }
  }
}

​
Reference mode

Reference mode lets you point to an external command or remote URL without bundling any code. Omit entry_point (and optionally type) from the server block.
Reference-mode .mcpbx bundles don’t need multi-platform publishing — they contain no compiled code.
{
  "manifest_version": "0.3",
  "name": "my-npx-tool",
  "version": "0.1.0",
  "server": {
    "mcp_config": {
      "command": "npx",
      "args": ["-y", "@example/my-mcp-server"]
    }
  }
}

​
OAuth configuration

HTTP tools that require user authentication declare an oauth_config inside mcp_config. See OAuth for HTTP tools for the full flow.
manifest.json (HTTP with OAuth)
{
  "manifest_version": "0.3",
  "name": "my-saas-tool",
  "version": "0.1.0",
  "server": {
    "transport": "http",
    "mcp_config": {
      "url": "https://api.example.com/mcp/",
      "oauth_config": {
        "clientId": "abc123",
        "authorizationUrl": "https://example.com/oauth/authorize",
        "tokenUrl": "https://example.com/oauth/token",
        "scopes": ["read", "write"]
      }
    }
  }
}

​
system_config

system_config declares resources the host manages on behalf of the tool. The host allocates these values and injects them via template substitution at runtime.
TypeDescription
portA free network port for the server to bind
temp_directoryAn ephemeral scratch directory
data_directoryA persistent storage directory
manifest.json
{
  "system_config": {
    "port": {
      "type": "port",
      "title": "Server Port",
      "description": "Port for the MCP HTTP endpoint",
      "default": 3000
    }
  }
}
Reference the value in mcp_config using ${system_config.port}.

​
Template functions

Both mcp_config fields and HTTP headers support template interpolation at runtime:
VariableResolves to
${__dirname}Absolute path to the unpacked bundle
${user_config.<key>}User-provided config value for <key>
${system_config.<key>}Host-managed config value for <key>
{
  "mcp_config": {
    "command": "node",
    "args": ["${__dirname}/server/index.js", "--port=${system_config.port}"],
    "headers": {
      "Authorization": "Bearer ${user_config.api_key}"
    }
  }
}

​
Automatic format selection

tool-cli checks requires_mcpbx() on your manifest before packing. You don’t choose the format — it’s determined by what your manifest uses: 
tool pack          # produces .mcpb or .mcpbx automatically
tool publish       # same
To check which format your manifest will use: 
tool validate      # reports the bundle extension in output

Build docs developers (and LLMs) love

Get started for freeTalk to us