What Are the Limitations on Claude Plugin Response Formats?

Claude plugins must return strictly JSON data under 40 KB that validates against a predefined schema, rejecting any HTML, Markdown, or non-UTF-8 content.

The anthropics/claude-plugins-community repository enforces a rigid contract for plugin communication to ensure the Claude model can parse responses reliably and securely. Every plugin response must conform to a JSON-only format with specific structural constraints defined in the repository’s configuration files.

Core Response Constraints

JSON Structure Requirements

Responses must be a single, well-formed JSON object. The platform validates the payload before passing it to the model, and any structural deviation causes immediate rejection.

Key structural rules include:

• Top-level object required: The root element must be an object ({ … }). Primitive values (strings, numbers, booleans, null) or arrays as the root element are invalid.
• No circular references: The JSON graph must be acyclic; self-referencing structures cause validation failures.
• UTF-8 encoding only: The entire payload must be valid UTF-8. Non-UTF-8 byte sequences trigger parsing errors.

Payload Size and Transport Limits

Performance and security constraints impose strict size limits on plugin responses:

• 40 KB maximum: The entire JSON payload may not exceed approximately 40 000 characters (40 KB). Exceeding this limit results in truncation or a hard error.
• Content-Type header: When served over HTTP, responses must include the header Content-Type: application/json. Any other MIME type causes the request to be rejected.

Content and Schema Restrictions

Prohibited Formats

The platform sanitizes all output to prevent injection attacks and ensure consistent rendering:

• No HTML or Markdown: Even text fields must contain plain text without markup. The model handles presentation logic; plugins cannot inject formatting.
• Binary data encoding: Raw binary data is not permitted. Files such as images must be encoded as Base64 strings or referenced via URLs within the JSON object.

Schema Validation via plugin.json

Each plugin declares its response contract in .claude-plugin/plugin.json. The platform enforces this schema strictly:

• Required fields: Missing keys defined as required in the schema cause validation errors.
• Ignored extra fields: Additional properties not declared in the schema are silently ignored.
• Type enforcement: Values must match the declared types (string, number, boolean, object, array) exactly.

The repository’s README.md links to these schema definitions, while .claude-plugin/marketplace.json aggregates the schemas for all listed community plugins.

Valid Response Structure Examples

Below are minimal, compliant payloads that satisfy all constraints.

Simple text reply:

{
  "type": "text",
  "content": "Your account balance is $1,245.67."
}

Image result with URL reference:

{
  "type": "image",
  "url": "https://example.com/generated-chart.png",
  "alt": "Bar chart of monthly expenses"
}

Both examples use a top-level object, contain only allowed primitive types, omit markup, and remain well under the 40 KB limit.

Summary

• JSON-only: Responses must be single, well-formed JSON objects; no arrays or primitives at the root.
• Size cap: Hard limit of 40 KB (≈ 40 000 characters) per response.
• Plain text: HTML and Markdown are prohibited; use plain text only.
• Schema-driven: Validity depends on the plugin.json schema declared in .claude-plugin/ directories.
• Encoding: UTF-8 is mandatory; binary data requires Base64 encoding.
• HTTP headers: Content-Type: application/json is required for network-delivered plugins.

Frequently Asked Questions

What is the maximum size for a Claude plugin response?

The platform enforces a strict limit of 40 KB (approximately 40 000 characters) for the entire JSON payload. Exceeding this size causes the response to be rejected or truncated, as defined in the repository’s validation logic referenced in README.md.

Can Claude plugins return HTML or Markdown formatting?

No. Plugins must return plain text only inside JSON strings. The model handles all presentation rendering internally, and any HTML tags or Markdown syntax in the payload will be treated as literal text or cause validation errors.

How are images and binary files handled in plugin responses?

Binary data cannot be returned raw. Images and files must be either embedded as Base64-encoded strings within a JSON field or referenced by URL. The plugin.json schema for each plugin in .claude-plugin/ directories defines which fields accept these references.

Where is the response schema defined for a Claude plugin?

Each plugin declares its response structure in .claude-plugin/plugin.json within its directory. The aggregate list of community plugins and their schemas resides in .claude-plugin/marketplace.json. The repository’s README.md provides high-level documentation linking to these schema files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}