One package, two complementary roles
A plugin can bundle skills, MCP configuration, or both. Skills describe how to approach a task; MCP servers expose callable capabilities. The plugin is a packaging mechanism, not a replacement for the managed harness, your application, or authorization at the connected service.
Package files with explicit paths
A plugin root contains .codex-plugin/plugin.json. The manifest points to its skills directory and MCP configuration. Relative paths start with ./ and remain inside the plugin. The plugin MCP file uses its own configuration format: do not paste it directly into agent.tools.
docs-helper/
├── .codex-plugin/plugin.json
├── .mcp.json
└── skills/docs-search/SKILL.mdLoad the package into an environment
For self-hosted compute, copy the package into the environment and register the absolute plugin root in environment.capability_directories. For OpenAI-hosted compute, follow the official ZIP upload flow. Ensure network reachability and local dependencies match the MCP connection you configured.
Check the trust boundary
Inspect scripts and server destinations before loading a package. Keep application credentials outside the sandbox. Test that the expected skill is available and its server can connect; a valid manifest alone does not establish that tools work. Use MCP authentication controls for protected services.
Read the official reference
Check the source for current API fields, account requirements, and service limits.
OpenAI: plugins