What Capabilities Can a Plugin Declare in Its Manifest? A Complete Guide to OpenAI Plugins

OpenAI Plugins recognize exactly three capability values—Read, Write, and Interactive—that a plugin can declare in the capabilities array of its plugin.json manifest.

The OpenAI Plugins repository uses a manifest-based configuration system where each plugin declares its intended permissions via a capabilities array inside the plugin.json file. Understanding which capability strings are valid—and how they constrain plugin behavior—is essential for building secure integrations that function correctly within the host environment.

The Three Valid Capability Values

The capabilities field in plugin.json accepts a strict enum of three strings. According to the source code analysis of the repository's manifest files, no other values are permitted.

Read

The Read capability indicates that the plugin can retrieve data or state from the host environment without causing side effects. This is appropriate for plugins that only fetch information to display to the user or the language model.

Write

The Write capability grants the plugin permission to create, modify, or delete resources in the host environment. Any plugin that alters data—such as creating calendar events or sending messages—must declare this capability.

Interactive

The Interactive capability signals that the plugin can open UI elements, launch dialogs, or otherwise interact with the user while it runs. This is required for plugins that render interfaces beyond simple text responses.

Declaring Capabilities in plugin.json

Each plugin stores its manifest in a .codex-plugin directory at the repository root. Inside this folder, plugin.json contains the capabilities array where you enumerate the required permissions.

Below are the syntactically valid configurations:

Declare only read capability:

{
  "name": "my-read-only-plugin",
  "capabilities": ["Read"]
}

Declare read and write capabilities:

{
  "name": "my-crud-plugin",
  "capabilities": ["Read", "Write"]
}

Declare interactive capability:

{
  "name": "my-ui-plugin",
  "capabilities": ["Interactive"]
}

Declare interactive and write capabilities:

{
  "name": "my-ui-writer-plugin",
  "capabilities": ["Interactive", "Write"]
}

No capabilities (empty array):

{
  "name": "my-simple-plugin",
  "capabilities": []
}

Real-World Examples from the OpenAI Plugins Repository

The OpenAI Plugins repository demonstrates all supported capability combinations in production manifests:

• Read & Write: The Twilio Developer Kit plugin declares both data retrieval and modification permissions in plugins/twilio-developer-kit/.codex-plugin/plugin.json with ["Read", "Write"].
• Interactive: The Zoom plugin only requires user interface interactions and lists ["Interactive"] in plugins/zoom/.codex-plugin/plugin.json.
• Interactive & Write: The Google Calendar plugin combines UI rendering with resource creation, declaring ["Interactive", "Write"] in plugins/google-calendar/.codex-plugin/plugin.json.
• No capabilities: Multiple plugins—including Stripe and Shopify equivalents—declare an empty array [] in their respective .codex-plugin/plugin.json files, indicating they do not request any special capabilities.

Summary

• The capabilities array in a plugin's plugin.json file strictly supports three string values: Read, Write, and Interactive.
• Plugins may declare any combination of these values or provide an empty array [] to request no special capabilities.
• Real-world implementations in the OpenAI Plugins repository demonstrate all valid configurations, from the Twilio Developer Kit's dual declaration to Zoom's single interactive flag.
• The manifest resides in the .codex-plugin directory at the plugin's root, and the system enforces this closed enum of capability strings.

Frequently Asked Questions

Can a plugin declare multiple capabilities?

Yes. A plugin can declare any combination of Read, Write, and Interactive in the capabilities array. For example, the Google Calendar plugin in the OpenAI Plugins repository declares both Interactive and Write permissions to render UI elements while also creating calendar events.

What happens if the capabilities array is empty?

An empty array [] is valid and indicates that the plugin does not request any special capabilities. Several plugins in the repository—including Stripe and Shopify examples—use this configuration to operate with default permissions only.

Can I create custom capability values?

No. The OpenAI Plugins system only recognizes the three enumerated values: Read, Write, and Interactive. No other strings appear in any manifest throughout the codebase, and attempting to use custom values would result in an invalid manifest configuration.

How do capabilities differ from API scopes?

Capabilities declared in plugin.json describe high-level behavioral permissions for the plugin runtime environment—such as whether it can render UI elements (Interactive) or modify data (Write). API scopes, typically defined in separate authentication configurations, govern specific endpoint access. The manifest capabilities tell the host what classes of operations the plugin intends to perform, while scopes control the granular permissions at the API level.

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