Configuration schema

Use this page to scan the public Caplets configuration shape. The linked JSON Schema remains the canonical editor integration target.

Canonical schema: https://caplets.dev/config.schema.json

Status values are Required or Optional according to the schema’s top-level required array.

Common config

Minimal user config:

{
  "$schema": "https://caplets.dev/config.schema.json",
  "mcpServers": {}
}

Global HTTP serve defaults (user config only):

{
  "$schema": "https://caplets.dev/config.schema.json",
  "serve": {
    "host": "127.0.0.1",
    "port": 5387,
    "publicOrigins": ["https://caplets.example.com"]
  },
  "mcpServers": {}
}

Keep options.exposure at the default code_mode unless your client cannot run Code Mode. Add backend maps such as mcpServers, openapiEndpoints, googleDiscoveryApis, graphqlEndpoints, httpApis, cliTools, or capletSets only for the capability sources you actually want agents to see.

Stdio MCP server:

{
  "$schema": "https://caplets.dev/config.schema.json",
  "mcpServers": {
    "github": {
      "name": "GitHub",
      "description": "Inspect repositories, issues, pull requests, and workflow runs.",
      "command": "github-mcp-server",
      "args": ["stdio"]
    }
  }
}

Public OpenAPI endpoint:

{
  "$schema": "https://caplets.dev/config.schema.json",
  "openapiEndpoints": {
    "status-api": {
      "name": "Status API",
      "description": "Read public service health from the status API.",
      "specUrl": "https://api.example.com/openapi.json",
      "baseUrl": "https://api.example.com",
      "auth": { "type": "none" }
    }
  }
}

Top-level fields

Field	Status	Type	Description
$schema	Optional	string	Optional JSON Schema for editor validation.
version	Optional	number	Caplets config schema version.
defaultSearchLimit	Optional	integer	Default maximum number of same-server search results.
maxSearchLimit	Optional	integer	Maximum accepted search_tools limit.
telemetry	Optional	boolean	Set false to disable anonymous Caplets telemetry for this user config.
serve	Optional	object	User-owned HTTP serve defaults. Ignored from project config for security.
completion	Optional	object	Shell completion discovery timeout and cache settings.
options	Optional	object	Global Caplets runtime options.
namespaceAliases	Optional	object	Source-level namespace aliases for hash-qualified Caplet IDs.
mcpServers	Optional	object	Downstream MCP servers keyed by stable server ID.
openapiEndpoints	Optional	object	OpenAPI endpoints keyed by stable Caplet ID.
googleDiscoveryApis	Optional	object	Google Discovery APIs keyed by stable Caplet ID.
graphqlEndpoints	Optional	object	GraphQL endpoints keyed by stable Caplet ID.
httpApis	Optional	object	HTTP APIs keyed by stable Caplet ID.
cliTools	Optional	object	CLI tools keyed by stable Caplet ID.
capletSets	Optional	object	Nested Caplet collections keyed by stable Caplet ID.

Major sections

serve

User-owned HTTP serve defaults. Ignored from project config for security.

Field	Status	Type	Description
host	Optional	string	Default HTTP bind host for caplets serve.
port	Optional	integer	Default HTTP port.
path	Optional	string	Default HTTP base path.
remoteStatePath	Optional	string	Default remote credential state directory for HTTP serve.
upstreamUrl	Optional	string	Default upstream Caplets URL for stacked HTTP serve.
allowUnauthenticatedHttp	Optional	boolean	Opt in to unauthenticated HTTP serving; intended only for trusted local use.
trustProxy	Optional	boolean	Trust proxy headers when deriving public HTTP request URLs.
publicOrigins	Optional	array	Additional public HTTP origins.

completion

Shell completion discovery timeout and cache settings.

Field	Status	Type	Description
discoveryTimeoutMs	Optional	integer	Timeout in milliseconds for downstream discovery checks.
overallTimeoutMs	Optional	integer	Overall timeout in milliseconds for completion discovery.
cacheTtlMs	Optional	integer	Milliseconds successful discovery results stay fresh.
negativeCacheTtlMs	Optional	integer	Milliseconds failed discovery results stay cached.

options

Global Caplets runtime options.

Field	Status	Type	Description
exposure	Optional	“direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
exposureDiscoveryTimeoutMs	Optional	integer	Timeout in milliseconds for exposure discovery.
exposureDiscoveryConcurrency	Optional	integer	Maximum number of Caplets inspected concurrently during exposure discovery.

mcpServers

Downstream MCP servers keyed by stable server ID.

Field	Status	Type	Description
name	Required	string	Human-readable server display name.
description	Required	string	Capability description shown to agents before downstream tools are disclosed.
transport	Optional	“stdio” | “http” | “sse”	Downstream MCP transport. Defaults to stdio when command is present.
command	Optional	string	Executable command for stdio servers.
args	Optional	array	Arguments passed to the stdio command.
env	Optional	object	Environment variables for stdio servers. Supports ${VAR} and $env:VAR.
cwd	Optional	string	Working directory for stdio servers.
url	Optional	string	Remote MCP server URL for http or sse transport.
auth	Optional	object	Authentication settings for a remote MCP server.
tags	Optional	array	Optional tags for grouping or searching Caplets.
exposure	Optional	“direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
shadowing	Optional	“forbid” | “allow” | “namespace”	Whether attached local Caplets may shadow this remote Caplet ID.
useWhen	Optional	string	When agents should prefer this Caplet or configured action.
avoidWhen	Optional	string	When agents should avoid this Caplet or configured action.
setup	Optional	object	Optional setup and verification metadata.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.
startupTimeoutMs	Optional	integer	Timeout in milliseconds for starting or checking a downstream server.
callTimeoutMs	Optional	integer	Timeout in milliseconds for downstream tool calls.
toolCacheTtlMs	Optional	integer	Milliseconds downstream tool metadata stays fresh. Set 0 to refresh every time.
disabled	Optional	boolean	When true, omit this server from Caplets discovery and do not start it.

openapiEndpoints

OpenAPI endpoints keyed by stable Caplet ID.

Field	Status	Type	Description
name	Required	string	Human-readable OpenAPI display name.
description	Required	string	Capability description shown to agents before OpenAPI operations are disclosed.
specPath	Optional	string	Local OpenAPI specification path.
specUrl	Optional	string	Remote OpenAPI specification URL.
baseUrl	Optional	string	Override base URL for OpenAPI requests.
auth	Required	object	Explicit OpenAPI request auth config. Use {“type”:“none”} for public APIs.
tags	Optional	array	Optional tags for grouping or searching Caplets.
exposure	Optional	“direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
shadowing	Optional	“forbid” | “allow” | “namespace”	Whether attached local Caplets may shadow this remote Caplet ID.
useWhen	Optional	string	When agents should prefer this Caplet or configured action.
avoidWhen	Optional	string	When agents should avoid this Caplet or configured action.
setup	Optional	object	Optional setup and verification metadata.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for OpenAPI HTTP requests.
operationCacheTtlMs	Optional	integer	Milliseconds OpenAPI operation metadata stays fresh. Set 0 to refresh every time.
disabled	Optional	boolean	When true, omit this OpenAPI Caplet from discovery.

googleDiscoveryApis

Google Discovery APIs keyed by stable Caplet ID.

Field	Status	Type	Description
name	Required	string	Human-readable Google Discovery API display name.
description	Required	string	Capability description shown to agents before Google Discovery operations are disclosed.
discoveryPath	Optional	string	Local Google Discovery document path.
discoveryUrl	Optional	string	Remote Google Discovery document URL.
baseUrl	Optional	string	Override base URL for Google API requests.
includeOperations	Optional	array	Optional list of includeOperations.
excludeOperations	Optional	array	Optional list of excludeOperations.
auth	Required	object	Explicit Google API request auth config. Use {“type”:“none”} for public APIs.
tags	Optional	array	Optional tags for grouping or searching Caplets.
exposure	Optional	“direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
shadowing	Optional	“forbid” | “allow” | “namespace”	Whether attached local Caplets may shadow this remote Caplet ID.
useWhen	Optional	string	When agents should prefer this Caplet or configured action.
avoidWhen	Optional	string	When agents should avoid this Caplet or configured action.
setup	Optional	object	Optional setup and verification metadata.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for Google Discovery HTTP requests.
operationCacheTtlMs	Optional	integer	Milliseconds Google Discovery operation metadata stays fresh. Set 0 to refresh every time.
disabled	Optional	boolean	When true, omit this Google Discovery Caplet from discovery.

graphqlEndpoints

GraphQL endpoints keyed by stable Caplet ID.

Field	Status	Type	Description
name	Required	string	Human-readable GraphQL display name.
description	Required	string	Capability description shown to agents before GraphQL operations are disclosed.
endpointUrl	Required	string	GraphQL HTTP endpoint URL.
schemaPath	Optional	string	Local GraphQL SDL or introspection path.
schemaUrl	Optional	string	Remote GraphQL SDL or introspection URL.
introspection	Optional	boolean	Load schema through endpoint introspection.
operations	Optional	object	Configured GraphQL operations keyed by stable tool name.
auth	Required	object	Explicit GraphQL request auth config. Use {“type”:“none”} for public APIs.
tags	Optional	array	Optional tags for grouping or searching Caplets.
exposure	Optional	“direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
shadowing	Optional	“forbid” | “allow” | “namespace”	Whether attached local Caplets may shadow this remote Caplet ID.
useWhen	Optional	string	When agents should prefer this Caplet or configured action.
avoidWhen	Optional	string	When agents should avoid this Caplet or configured action.
setup	Optional	object	Optional setup and verification metadata.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for GraphQL HTTP requests.
operationCacheTtlMs	Optional	integer	Milliseconds GraphQL operation metadata stays fresh. Set 0 to refresh every time.
selectionDepth	Optional	integer	Maximum depth for auto-generated GraphQL selection sets.
disabled	Optional	boolean	When true, omit this GraphQL Caplet.

httpApis

HTTP APIs keyed by stable Caplet ID.

Field	Status	Type	Description
name	Required	string	Human-readable HTTP API display name.
description	Required	string	Capability description shown to agents before HTTP actions are disclosed.
baseUrl	Required	string	Base URL for HTTP action requests.
auth	Required	object	Explicit HTTP API request auth config. Use {“type”:“none”} for public APIs.
actions	Required	object	Configured HTTP actions keyed by stable tool name.
tags	Optional	array	Optional tags for grouping or searching Caplets.
exposure	Optional	“direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
shadowing	Optional	“forbid” | “allow” | “namespace”	Whether attached local Caplets may shadow this remote Caplet ID.
useWhen	Optional	string	When agents should prefer this Caplet or configured action.
avoidWhen	Optional	string	When agents should avoid this Caplet or configured action.
setup	Optional	object	Optional setup and verification metadata.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.
requestTimeoutMs	Optional	integer	Timeout in milliseconds for HTTP action requests.
maxResponseBytes	Optional	integer	Maximum HTTP action response body bytes to read.
disabled	Optional	boolean	When true, omit this HTTP API Caplet.

cliTools

CLI tools keyed by stable Caplet ID.

Field	Status	Type	Description
name	Required	string	Human-readable CLI tools display name.
description	Required	string	Capability description shown to agents before CLI actions are disclosed.
actions	Required	object	Configured CLI actions keyed by stable tool name.
cwd	Optional	string	Default working directory for CLI actions.
env	Optional	object	Default environment variables for CLI actions.
tags	Optional	array	Optional tags for grouping or searching Caplets.
exposure	Optional	“direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
shadowing	Optional	“forbid” | “allow” | “namespace”	Whether attached local Caplets may shadow this remote Caplet ID.
useWhen	Optional	string	When agents should prefer this Caplet or configured action.
avoidWhen	Optional	string	When agents should avoid this Caplet or configured action.
setup	Optional	object	Optional setup and verification metadata.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.
timeoutMs	Optional	integer	Default timeout in milliseconds for CLI actions.
maxOutputBytes	Optional	integer	Default maximum combined stdout and stderr bytes to keep.
disabled	Optional	boolean	When true, omit this CLI tools Caplet.

capletSets

Nested Caplet collections keyed by stable Caplet ID.

Field	Status	Type	Description
name	Required	string	Human-readable Caplet set display name.
description	Required	string	Capability description shown before child Caplets are disclosed.
configPath	Optional	string	Child Caplets config.json path.
capletsRoot	Optional	string	Child Markdown Caplets root directory.
defaultSearchLimit	Optional	integer	Default maximum number of child Caplet search results.
maxSearchLimit	Optional	integer	Maximum accepted child Caplet search result limit.
toolCacheTtlMs	Optional	integer	Milliseconds child Caplet metadata stays fresh. Set 0 to refresh every time.
tags	Optional	array	Optional tags for grouping or searching Caplets.
exposure	Optional	“direct” | “progressive” | “code_mode” | “direct_and_code_mode” | “progressive_and_code_mode”	How this Caplet is exposed to agents.
shadowing	Optional	“forbid” | “allow” | “namespace”	Whether attached local Caplets may shadow this remote Caplet ID.
useWhen	Optional	string	When agents should prefer this Caplet or configured action.
avoidWhen	Optional	string	When agents should avoid this Caplet or configured action.
setup	Optional	object	Optional setup and verification metadata.
projectBinding	Optional	object	Project Binding requirements for Caplets that need an attached project.
runtime	Optional	object	Runtime feature and resource requirements for hosted execution.
disabled	Optional	boolean	When true, omit this Caplet set.