manifest.json reference

Every MCPB package contains a manifest.json file at its root. It describes the server’s runtime, transport, configuration requirements, and metadata that the registry and MCP hosts use to install and launch the tool. The manifest follows the MCPB spec with extensions added by tool-cli for HTTP transport, reference mode, OAuth, and host-managed system resources (documented under .mcpbx features).

Top-level fields

manifest_version

string

required

Spec version. Currently "0.3".

name

string

Machine-readable package name (e.g., "my-tool"). Defaults to the directory name during tool init.

version

string

Semantic version of the package (e.g., "1.0.0"). Update this before each tool publish.

description

string

Brief, single-line description shown in search results and the registry listing.

author

object

Author information.

Show author fields

author.name

string

required

Author’s full name.

author.email

string

Author’s email address.

author.url

string

Author’s website URL.

display_name

string

Human-readable name shown in the registry UI. Can contain spaces and mixed case.

long_description

string

Extended Markdown description for the registry listing page.

license

string

SPDX license identifier (e.g., "MIT", "Apache-2.0").

icon

string

Path to a single icon file, relative to the package root (e.g., "icon.png").

icons

array

Multiple icon variants with size and theme metadata.

Show icon object fields

src

string

required

Relative path or https:// URL to a PNG icon file.

size

string

Dimensions in "WIDTHxHEIGHT" format (e.g., "32x32", "128x128").

theme

string

Theme variant: "light", "dark", "high-contrast", or a custom string.

homepage

string

Project homepage URL.

documentation

string

Documentation URL.

support

string

Support URL (issue tracker, forum, etc.).

repository

object

Source code repository.

Show repository fields

repository.type

string

required

Repository type, typically "git".

repository.url

string

required

Repository URL.

keywords

array of strings

Search keywords used by tool search and the registry.

server

The server object is required and describes the runtime, transport, and how to launch the server.

server.type

string

Server runtime type. Omit in reference mode.

Value	Description
`"node"`	Node.js runtime
`"python"`	Python runtime
`"binary"`	Pre-compiled binary (Rust, Go, C++, etc.)

server.transport

string

Transport protocol. Defaults to "stdio" when omitted.

Value	Description
`"stdio"`	Standard input/output (default)
`"http"`	HTTP/SSE transport

server.entry_point

string

Path to the main file, relative to the package root (e.g., "server/index.js"). Absent in reference mode.

server.mcp_config

object

Execution configuration passed to the MCP host.

Show mcp_config fields

command

string

Executable to run (e.g., "node", "uv", "npx"). Required for stdio servers.

args

array of strings

Command-line arguments. Supports template variables like ${__dirname}, ${user_config.KEY}, and ${system_config.KEY}.

env

object

Environment variables as a string-to-string map. Supports template variables.

url

string

HTTP endpoint URL for HTTP transport servers. Supports template variables.

headers

object

HTTP request headers as a string-to-string map. Supports template variables.

oauth_config

object

OAuth configuration for HTTP servers that use OAuth 2.0.

Show oauth_config fields

clientId

string

Pre-registered OAuth client ID.

authorizationUrl

string

Custom authorization endpoint URL.

tokenUrl

string

Custom token endpoint URL.

scopes

array of strings

OAuth scopes to request.

platform_overrides

object

Per-platform overrides keyed by platform string (e.g., "darwin-arm64", "linux-x64"). Each value can override command, args, env, url, and headers. See Multi-platform publishing for details.

Capabilities

tools

array

Static list of tool declarations. Each entry has name (string) and description (string). Used when the manifest is inspected without launching the server.

prompts

array

Static list of prompt templates. Each entry has name, description, and optional arguments and template fields.

tools_generated

boolean

Set to true when the server generates its tool list dynamically at runtime (i.e., the tools array cannot be known statically).

prompts_generated

boolean

Set to true when the server generates its prompt list dynamically.

user_config

user_config declares fields that the user must supply before the server can run — API keys, base URLs, preferences, etc. MCP hosts and tool config set use this schema to prompt users interactively. Each key in the user_config map is a field name. The value is an object:

type

string

required

Field type. Determines validation and the UI widget shown to users.

Value	Description
`"string"`	Free-form text (use `sensitive: true` for secrets)
`"number"`	Numeric value, with optional `min`/`max`
`"boolean"`	True/false toggle
`"directory"`	Local directory path, validated to exist
`"file"`	Local file path, validated to exist

title

string

required

Human-readable label shown in prompts and UIs.

description

string

Additional help text for the field.

required

boolean

Whether the field must be supplied before the server starts.

default

any

Default value used when the user does not supply one.

sensitive

boolean

Mark as true for API keys and tokens. The value will be encrypted at rest and masked in output.

enum

array of strings

Restrict string fields to a fixed set of allowed values.

multiple

boolean

Allow the user to supply multiple values (string fields only).

min

number

Minimum value for number fields.

max

number

Maximum value for number fields.

Values are referenced in mcp_config via the template ${user_config.FIELD_NAME}.

system_config

system_config declares resources that the host manages on behalf of the server — ports, temporary directories, and persistent data directories. The host allocates and injects these values; the user never configures them directly. Each key in the system_config map is a field name. The value is an object:

type

string

required

System resource type.

Value	Description
`"port"`	An available TCP port, allocated by the host
`"temp_directory"`	An ephemeral directory, cleaned up after the session
`"data_directory"`	A persistent directory that survives restarts

title

string

required

Human-readable label.

description

string

Additional context for host implementors.

required

boolean

Whether the field is required.

default

any

Default value (e.g., 3000 for a port).

Values are referenced in mcp_config via the template ${system_config.FIELD_NAME}.

Using system_config causes the package to be bundled as .mcpbx instead of .mcpb.

compatibility

object

Platform and runtime version requirements.

Show compatibility fields

platforms

array

Supported OS platforms. Values: "darwin", "win32", "linux".

runtimes

object

Minimum runtime versions.

runtimes.node

string

Minimum Node.js version (e.g., ">=18").

runtimes.python

string

Minimum Python version (e.g., ">=3.11").

claude_desktop

string

Minimum Claude Desktop version requirement.

_meta

The _meta field is a freeform extension namespace. tool-cli reads from the store.tool.mcpb key within it.

"_meta": {
  "store.tool.mcpb": {
    "scripts": {
      "build": "npm install",
      "test": "npm test",
      "lint": "eslint ."
    },
    "categories": ["developer-tools"],
    "runtime": "node20"
  }
}

_meta[store.tool.mcpb].scripts.build

string

Shell command run by tool build. Generated automatically by tool init based on the server type and package manager.

_meta[store.tool.mcpb].scripts.test

string

Shell command run by tool test.

_meta[store.tool.mcpb].scripts.*

string

Any additional custom script name maps to tool <script-name> (e.g., "lint" → tool lint).

_meta[store.tool.mcpb].categories

array of strings

Registry category tags for discoverability.

_meta[store.tool.mcpb].runtime

string

Runtime identifier hint for the registry (e.g., "node20").

Init modes: bundled vs. reference

A manifest operates in one of two modes determined by the presence of server.entry_point:

Mode	`entry_point`	`server.type`	Bundle format
Bundled	Present	Required	`.mcpb` (or `.mcpbx` for HTTP)
Reference	Absent	Optional	`.mcpbx`

In bundled mode the package contains all the server code. In reference mode it only contains the manifest and points to an external command (mcp_config.command) or URL (mcp_config.url).

Complete example: Node.js stdio server

{
  "manifest_version": "0.3",
  "name": "my-tool",
  "version": "1.0.0",
  "description": "An example MCP server built with Node.js",
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "display_name": "My Tool",
  "license": "MIT",
  "homepage": "https://example.com",
  "repository": {
    "type": "git",
    "url": "https://github.com/example/my-tool"
  },
  "keywords": ["example", "mcp"],
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  },
  "tools": [
    { "name": "hello", "description": "Says hello" }
  ],
  "user_config": {
    "API_KEY": {
      "type": "string",
      "title": "API Key",
      "description": "Your service API key",
      "required": true,
      "sensitive": true
    }
  },
  "compatibility": {
    "platforms": ["darwin", "linux", "win32"],
    "runtimes": {
      "node": ">=18"
    }
  },
  "_meta": {
    "store.tool.mcpb": {
      "scripts": {
        "build": "npm install",
        "test": "npm test"
      }
    }
  }
}

Example: reference-mode HTTP server with OAuth

{
  "manifest_version": "0.3",
  "name": "my-remote-tool",
  "version": "1.0.0",
  "description": "Connects to a remote MCP HTTP endpoint with OAuth",
  "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"]
      }
    }
  },
  "tools_generated": true
}

Get Started

Using Tools

Building Tools

Advanced

manifest.json reference

Top-level fields

server

Capabilities

user_config

system_config

compatibility

_meta

Init modes: bundled vs. reference

Complete example: Node.js stdio server

Example: reference-mode HTTP server with OAuth

Build docs developers (and LLMs) love

Get Started

Using Tools

Building Tools

Advanced

Documentation Index

​Top-level fields

​server

​Capabilities

​user_config

​system_config

​compatibility

​_meta

​Init modes: bundled vs. reference

​Complete example: Node.js stdio server

​Example: reference-mode HTTP server with OAuth

Build docs developers (and LLMs) love

Top-level fields

server

Capabilities

user_config

system_config

compatibility

_meta

Init modes: bundled vs. reference

Complete example: Node.js stdio server

Example: reference-mode HTTP server with OAuth