Repository Public
1# Plugins23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45A plugin packages skills, MCP configuration, or both. Load its files into your own environment or upload a ZIP to an OpenAI-hosted environment.67## Package the plugin89This plugin combines a documentation-search skill with the OpenAI documentation MCP. It needs network access but no credentials or local server dependencies.1011```text12docs-helper/13├── .codex-plugin/plugin.json14├── .mcp.json15└── skills/docs-search/SKILL.md16```1718Declare the skill directory and MCP configuration in `.codex-plugin/plugin.json`:1920```json21{22 "name": "docs-helper",23 "version": "1.0.0",24 "description": "Find answers in OpenAI developer documentation.",25 "skills": "./skills/",26 "mcpServers": "./.mcp.json"27}28```2930Paths resolve from the plugin root. They must start with `./`, stay inside the plugin, and contain no `..` components. See [Package your plugin](https://developers.openai.com/plugins/build/plugins) for the full manifest format.3132Add the server to `.mcp.json`. This file uses the plugin format, which differs from `agent.tools`:3334```json35{36 "mcpServers": {37 "openai_docs": {38 "type": "http",39 "url": "https://developers.openai.com/mcp"40 }41 }42}43```4445Add the instructions to `skills/docs-search/SKILL.md`:4647```markdown48---49name: docs-search50description: Find answers in OpenAI developer documentation.51---5253Use the openai_docs MCP server to find relevant documentation.54Answer the question and link to the sources you used.55```5657## Register plugins in a self-hosted sandbox5859Copy the plugin to `/workspace/plugins/docs-helper` and add that absolute path to `environment.capability_directories`. Select the plugin root, which contains `.codex-plugin/plugin.json`.6061Register a plugin6263```javascript64import OpenAI from "openai";65const client = new OpenAI();6667const result = await client.beta.agents.sessions.create({68 agent: {69 model: "gpt-6-astra",70 },71 environment: {72 type: "self_hosted",73 workspace_directory: "/workspace",74 capability_directories: ["/workspace/plugins/docs-helper"],75 },76});77console.log(result.id);78```7980```python81from openai import OpenAI8283client = OpenAI()8485result = client.beta.agents.sessions.create(86 agent={"model": "gpt-6-astra"},87 environment={88 "type": "self_hosted",89 "workspace_directory": "/workspace",90 "capability_directories": ["/workspace/plugins/docs-helper"],91 },92)93print(result.id)94```9596```go97import (98 "context"99 "fmt"100101 "github.com/openai/openai-go/v3"102)103104ctx := context.Background()105client := openai.NewClient()106result, err := client.Beta.Agents.Sessions.New(ctx,107 openai.BetaAgentSessionNewParams{108 Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")},109 Environment: openai.EnvironmentParamUnion{110 OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{111 WorkspaceDirectory: "/workspace",112 CapabilityDirectories: []string{"/workspace/plugins/docs-helper"},113 },114 },115 })116if err != nil {117 panic(err)118}119fmt.Println(result.ID)120```121122```java123import com.openai.client.OpenAIClient;124import com.openai.client.okhttp.OpenAIOkHttpClient;125import com.openai.models.beta.agents.EnvironmentParam;126import com.openai.models.beta.agents.sessions.SessionCreateParams;127import java.util.List;128129OpenAIClient client = OpenAIOkHttpClient.fromEnv();130var result =131 client132 .beta()133 .agents()134 .sessions()135 .create(136 SessionCreateParams.builder()137 .agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())138 .environment(139 EnvironmentParam.SelfHosted.builder()140 .workspaceDirectory("/workspace")141 .capabilityDirectories(List.of("/workspace/plugins/docs-helper"))142 .build())143 .build());144System.out.println(result.id());145```146147```ruby148require "openai"149150client = OpenAI::Client.new151result = client.beta.agents.sessions.create(152 agent: { model: "gpt-6-astra" },153 environment: {154 type: "self_hosted",155 workspace_directory: "/workspace",156 capability_directories: ["/workspace/plugins/docs-helper"]157 }158)159puts result.id160```161162163[Connect the executor](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted) before the agent uses the plugin. Allow the environment to reach `https://developers.openai.com/mcp`.164165For multiple plugins, list each root. A parent directory can discover nested skills, but does not load every child plugin's MCP configuration.166167## Upload plugins to an OpenAI-hosted sandbox168169Supply one ZIP per plugin in `environment.plugins`. Each ZIP must contain one plugin folder with `.codex-plugin/plugin.json` inside it. The request's name and description must match the manifest.170171This helper packages your folder and creates a session. Pass your API client and the path to `docs-helper`. OpenAI extracts and registers the plugin automatically.172173Upload a plugin folder174175```python176import base64177import json178import shutil179from pathlib import Path180from tempfile import TemporaryDirectory181182183def upload_plugin(client, plugin_directory):184 plugin_directory = Path(plugin_directory).resolve()185 manifest = json.loads((plugin_directory / ".codex-plugin/plugin.json").read_text())186 with TemporaryDirectory() as temporary:187 archive = shutil.make_archive(188 str(Path(temporary) / "plugin"),189 "zip",190 root_dir=plugin_directory.parent,191 base_dir=plugin_directory.name,192 )193 return client.beta.agents.sessions.create(194 agent={"model": "gpt-6-astra"},195 environment={196 "type": "openai_hosted",197 "plugins": [198 {199 "type": "inline",200 "name": manifest["name"],201 "description": manifest["description"],202 "source": {203 "type": "base64",204 "media_type": "application/zip",205 "data": base64.b64encode(206 Path(archive).read_bytes()207 ).decode(),208 },209 }210 ],211 },212 )213```214215216## Reuse a hosted plugin setup217218[Create an environment template](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/environments/subresources/templates/methods/create) with the plugin list. For later sessions, set `environment.environment_template_id` to the saved template ID.219220Omit `environment.plugins` to inherit the template's plugin list. Supplying a list replaces it. Each session gets its own environment; the root agent and its subagents share it.221222## Authenticate MCP servers223224The example needs no authentication. For other plugin MCP servers:225226- **HTTP:** `bearer_token_env_var` reads an environment variable and sends its value as a bearer token. Other `http_headers` values are literal; `env_http_headers` is not supported.227- **Stdio:** `env_vars` lists environment variables to pass to the server process. Install the executable and its dependencies in the environment. A relative `cwd` resolves from the plugin root.228229Keep secrets out of plugin files and archives. Plugin MCP connections run from the session's environment. See [MCP authentication](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp#add-authentication) for credential boundaries.230231For hosted stdio MCPs, omit the network policy or set it to `enabled`. The `disabled` and `restricted` network policies are not supported for these connections.232233## Test a plugin234235Send a normal session message that asks for the skill:236237> Use docs-search to explain how to stream Responses API output. Include links to the documentation.238239Check that the turn completed and that its [saved items](https://developers.openai.com/api/docs/guides/agents-api/sessions/events#fetch-items-and-turns) include a successful call to `openai_docs`. The answer should follow the skill's instructions and cite the documentation. For a skill-only plugin, check its output against the instructions; an MCP call is not required.240241Create a new session after changing plugin files or a template. Existing sessions do not reload the tools. For connection errors, see [MCP troubleshooting](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp#troubleshoot-connections). [Delete test sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage) and stop self-hosted compute when finished.