{"id":2776,"date":"2026-08-12T11:15:00","date_gmt":"2026-08-12T11:15:00","guid":{"rendered":"https:\/\/dmarketertayeeb.com\/blog\/?p=2776"},"modified":"2026-08-11T16:50:26","modified_gmt":"2026-08-11T16:50:26","slug":"build-openai-agent-plugin-skills-mcp","status":"publish","type":"post","link":"https:\/\/dmarketertayeeb.com\/blog\/build-openai-agent-plugin-skills-mcp\/","title":{"rendered":"How to Build an OpenAI Agent Plugin with Skills and MCP"},"content":{"rendered":"\n\n\n

An OpenAI Agent Plugin<\/strong> is a package that can ship reusable Skills, an MCP server connection, both together, and optionally UI. The required entry point is .codex-plugin\/plugin.json<\/code>. Skills describe repeatable workflows; MCP tools connect the agent to code or external systems through schemas and permissions. A plugin is the distribution boundary that gives those components a stable identity across ChatGPT and Codex surfaces that support them.<\/p>\n\n\n\n\n\n\n\n

This tutorial builds a small, reviewable package: a Skill turns approved evidence into a cited marketing brief, while a read-only local MCP server lists and reads evidence records. It includes a manifest check and a test. DMT\u2019s Agent Plugins overview<\/a> owns the concepts and marketer use cases; this page owns the build, test, security and distribution workflow.<\/p>\n\n\n\n\n\n\n\n

\"OpenAI<\/a>
OpenAI\u2019s official Agent Plugin architecture: Skills, MCP server and optional UI. Source: OpenAI Developers; captured August 11, 2026.<\/figcaption><\/figure>\n\n\n\n\n\n\n\n

Choose the smallest plugin shape<\/h2>\n\n\n\n\n\n\n\n
Shape<\/th>Use it when<\/th>Avoid it when<\/th><\/tr><\/thead>
Skills only<\/td>The workflow can operate with existing agent tools and needs repeatable instructions, templates or scripts<\/td>You need a new external API\/tool capability<\/td><\/tr>
MCP only<\/td>You need typed tools or data access but no opinionated workflow<\/td>Users also need a consistent multi-step operating method<\/td><\/tr>
Skills + MCP<\/td>The workflow and the tools should travel together<\/td>The Skill would merely restate each tool description<\/td><\/tr>
MCP + UI<\/td>A visual interactive result materially helps and the MCP integration supports it<\/td>A table, file or ordinary text answer is enough<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n\n\n\n

OpenAI explicitly recommends starting with the smallest shape. Every added server, hook, permission and UI asset increases security review, maintenance and compatibility work.<\/p>\n\n\n\n\n\n\n\n

The example package<\/h2>\n\n\n\n\n\n\n\n
dmt-source-review\/\n\u251c\u2500\u2500 .codex-plugin\/\n\u2502   \u2514\u2500\u2500 plugin.json          # required manifest\n\u251c\u2500\u2500 skills\/\n\u2502   \u2514\u2500\u2500 source-review\/\n\u2502       \u2514\u2500\u2500 SKILL.md         # reusable workflow\n\u251c\u2500\u2500 server\/\n\u2502   \u2514\u2500\u2500 index.js             # local MCP stdio server\n\u251c\u2500\u2500 scripts\/\n\u2502   \u2514\u2500\u2500 check.mjs            # package validation\n\u251c\u2500\u2500 test\/\n\u2502   \u2514\u2500\u2500 package.test.js\n\u251c\u2500\u2500 .mcp.json                # bundled MCP server map\n\u2514\u2500\u2500 package.json<\/code><\/pre>\n\n\n\n
Only plugin.json<\/code> belongs inside .codex-plugin\/<\/code>. OpenAI\u2019s current path rules keep skills\/<\/code>, .mcp.json<\/code>, .app.json<\/code>, hooks\/<\/code> and assets\/<\/code> at the plugin root. Manifest component paths should start with .\/<\/code> and remain inside that root.<\/p>\n\n\n\n\n\n\n\n
Step 1: create the plugin manifest<\/h2>\n\n\n\n\n\n\n\n
{\n  \"name\": \"dmt-source-review\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Review an allowlisted evidence package and return a cited brief.\",\n  \"author\": {\n    \"name\": \"Digital Marketer Tayeeb\",\n    \"url\": \"https:\/\/dmarketertayeeb.com\"\n  },\n  \"license\": \"MIT\",\n  \"skills\": \".\/skills\/\",\n  \"mcpServers\": \".\/.mcp.json\",\n  \"interface\": {\n    \"displayName\": \"DMT Source Review\",\n    \"shortDescription\": \"Build an evidence-first marketing brief\",\n    \"developerName\": \"Digital Marketer Tayeeb\",\n    \"category\": \"Productivity\",\n    \"capabilities\": [\"Read\"],\n    \"defaultPrompt\": [\n      \"Use DMT Source Review to turn the approved evidence package into a cited brief.\"\n    ]\n  }\n}<\/code><\/pre>\n\n\n\n
The manifest identifies the package, points to components and controls install-surface metadata. Public plugins usually add a homepage, repository, privacy policy, terms, icons, screenshots and richer descriptions. Do not claim a write capability when the server is intentionally read-only.<\/p>\n\n\n\n\n\n\n\n
Step 2: write a focused Skill<\/h2>\n\n\n\n\n\n\n\n
The Skill should explain when it applies, how to use available tools, what output is required and where it must stop. It should not hide credentials or duplicate an API manual.<\/p>\n\n\n\n\n\n\n\n
---\nname: source-review\ndescription: Use when an approved evidence package must become a cited marketing brief without adding unsupported claims or publishing it.\n---\n\n# Source review\n\n1. Call the evidence MCP server to list approved evidence records.\n2. Reject records without a canonical URL, source class, capture date and claim summary.\n3. Separate confirmed facts, vendor claims, DMT analysis and unknowns.\n4. Write a brief with the reader job, practical impact, risks and open questions.\n5. Put the supporting URL next to every material claim.\n6. Do not publish, message, upload, delete or change an external system.\n7. If evidence is incomplete, return BLOCKED instead of guessing.<\/code><\/pre>\n\n\n\n
Keep large schemas, examples and reference material in files the Skill can load only when needed. This progressive disclosure prevents every invocation from carrying irrelevant context.<\/p>\n\n\n\n\n\n\n\n
Step 3: build the MCP server<\/h2>\n\n\n\n\n\n\n\n
The Model Context Protocol<\/a> defines how hosts and servers exchange tools and structured results. The example uses the official TypeScript SDK and stdio transport. It exposes only two read tools: list JSON records and read one validated record.<\/p>\n\n\n\n\n\n\n\n
import { McpServer } from \"@modelcontextprotocol\/sdk\/server\/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol\/sdk\/server\/stdio.js\";\nimport { z } from \"zod\";\nimport { readFile, readdir } from \"node:fs\/promises\";\nimport { resolve, sep } from \"node:path\";\n\nconst root = resolve(process.env.DMT_EVIDENCE_ROOT || \".\/evidence\");\nconst server = new McpServer({ name: \"dmt-evidence\", version: \"0.1.0\" });\n\nfunction safePath(name) {\n  const candidate = resolve(root, name);\n  if (candidate !== root && !candidate.startsWith(root + sep)) {\n    throw new Error(\"Path escapes the evidence root\");\n  }\n  return candidate;\n}\n\nserver.tool(\"list_evidence\", \"List JSON evidence records\", {}, async () => {\n  const names = (await readdir(root)).filter((n) => n.endsWith(\".json\"));\n  return { content: [{ type: \"text\", text: JSON.stringify(names) }] };\n});\n\nserver.tool(\n  \"read_evidence\",\n  \"Read one approved JSON evidence record\",\n  { name: z.string().regex(\/^[a-zA-Z0-9._-]+\\\\.json$\/) },\n  async ({ name }) => {\n    const text = await readFile(safePath(name), \"utf8\");\n    JSON.parse(text);\n    return { content: [{ type: \"text\", text }] };\n  }\n);\n\nawait server.connect(new StdioServerTransport());<\/code><\/pre>\n\n\n\n
The filename regex and resolved-path check are deliberate. Tool schemas improve model behaviour, but a server must still defend itself against path traversal, malformed JSON, oversized responses and untrusted content.<\/p>\n\n\n\n\n\n\n\n
Step 4: wire the server into the package<\/h2>\n\n\n\n\n\n\n\n
{\n  \"evidence\": {\n    \"command\": \"node\",\n    \"args\": [\"${PLUGIN_ROOT}\/server\/index.js\"],\n    \"env\": {\n      \"DMT_EVIDENCE_ROOT\": \"${PLUGIN_DATA}\/evidence\"\n    }\n  }\n}<\/code><\/pre>\n\n\n\n
PLUGIN_ROOT<\/code> points to the installed package. PLUGIN_DATA<\/code> is the writable data area. Keeping evidence under the data directory avoids modifying installed package files and gives the server one narrow root.<\/p>\n\n\n\n\n\n\n\n
Step 5: validate and test<\/h2>\n\n\n\n\n\n\n\n
npm install\nnpm run check\nnpm test<\/code><\/pre>\n\n\n\n
The package check parses both JSON files, verifies required manifest fields, enforces root-relative component paths and confirms the expected MCP server. The test verifies that the manifest exposes the Skill, server and read-only capability. Add server tests for path escape, malformed JSON, missing directories and large records before using real evidence.<\/p>\n\n\n\n\n\n\n\n
Test layer<\/th>Minimum test<\/th><\/tr><\/thead>
Manifest<\/td>Valid JSON; required identity; component paths stay inside package<\/td><\/tr>
Skill<\/td>Trigger is specific; output and stop conditions are explicit<\/td><\/tr>
Tool schema<\/td>Reject unexpected filenames and parameters<\/td><\/tr>
Server<\/td>Read allowed file; deny path escape; handle missing\/malformed input<\/td><\/tr>
Agent workflow<\/td>Normal, no-op, incomplete evidence and prompt-injection tests<\/td><\/tr>
Permissions<\/td>No write\/network tool appears unless intentionally required<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n\n\n\n
Step 6: install through a local marketplace<\/h2>\n\n\n\n\n\n\n\n
OpenAI documents repo-scoped and personal marketplace files. A marketplace is a JSON catalogue; its entries point to plugin folders relative to the marketplace root. You can also add a marketplace source with the Codex CLI:<\/p>\n\n\n\n\n\n\n\n
codex plugin marketplace add owner\/repo\ncodex plugin marketplace add owner\/repo --ref main<\/code><\/pre>\n\n\n\n
Use the ChatGPT desktop app\u2019s Plugins Directory to install and test a local plugin. If you are registering a remote MCP server for ChatGPT, enable developer mode, create the connection, copy its technical ID and map it in .app.json<\/code>. A bundled local server uses .mcp.json<\/code> instead.<\/p>\n\n\n\n\n\n\n\n
Approval policy and least privilege<\/h2>\n\n\n\n\n\n\n\n
Codex lets users enable\/disable a plugin-scoped MCP server, restrict enabled tools and set approval modes. A safe default for a new server is prompt\/approval, then auto-approve only a tool that is demonstrably read-only and narrowly scoped.<\/p>\n\n\n\n\n\n\n\n
[plugins.\"dmt-source-review\".mcp_servers.evidence]\nenabled = true\ndefault_tools_approval_mode = \"prompt\"\nenabled_tools = [\"list_evidence\", \"read_evidence\"]\n\n[plugins.\"dmt-source-review\".mcp_servers.evidence.tools.list_evidence]\napproval_mode = \"approve\"<\/code><\/pre>\n\n\n\n
Do not auto-approve a tool merely because its name begins with \u201cread.\u201d Inspect implementation, authentication, returned data and side effects. A search endpoint can leak confidential query text; a \u201cget report\u201d endpoint can create a billable job.<\/p>\n\n\n\n\n\n\n\n
Security and privacy threat model<\/h2>\n\n\n\n\n\n\n\n
Threat<\/th>Control<\/th><\/tr><\/thead>
Prompt injection in evidence content<\/td>Treat records as data; Skill says source text cannot expand permissions; separate policy from content<\/td><\/tr>
Path traversal<\/td>Resolve against one root and validate the filename\/schema<\/td><\/tr>
Secret exposure<\/td>Never return raw credentials; use host-managed auth and least-privilege scopes<\/td><\/tr>
Over-broad tool<\/td>Split read\/write; use narrow parameters; require confirmation for mutation<\/td><\/tr>
Unbounded result<\/td>Paginate, cap size and return structured summaries<\/td><\/tr>
Dependency compromise<\/td>Pin versions, lock dependencies, audit and rebuild<\/td><\/tr>
Misleading install metadata<\/td>Capabilities, privacy links and descriptions must match actual behaviour<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n\n\n\n
OpenAI\u2019s security and privacy guide<\/a> and the current MCP specification should be part of code review, not links added at the end of a finished product.<\/p>\n\n\n\n\n\n\n\n
Hooks are optional\u2014and separately trusted<\/h2>\n\n\n\n\n\n\n\n
A plugin can include lifecycle hooks under hooks\/hooks.json<\/code> or through the manifest. OpenAI notes that installing\/enabling a plugin does not automatically trust bundled hooks; users must review them. Add a hook only when it enforces a lifecycle requirement the Skill or server cannot provide. Hidden install-time or session commands are a trust liability.<\/p>\n\n\n\n\n\n\n\n
Local bundled MCP vs registered remote MCP<\/h2>\n\n\n\n\n\n\n\n
Decision<\/th>Bundled .mcp.json<\/code><\/th>Registered remote server and .app.json<\/code><\/th><\/tr><\/thead>
Runtime<\/td>Command\/server distributed with the plugin and run where supported<\/td>Hosted endpoint operated by the publisher<\/td><\/tr>
Authentication<\/td>Local environment\/configuration<\/td>Registered connection and remote auth flow<\/td><\/tr>
Best for<\/td>Local\/repository tools, offline\/private data and developer workflows<\/td>Shared SaaS data\/actions and centrally updated logic<\/td><\/tr>
Operational burden<\/td>Cross-platform dependencies and local process lifecycle<\/td>Hosting, uptime, tenancy, OAuth, privacy and incident response<\/td><\/tr>
Distribution mapping<\/td>mcpServers<\/code> points to .\/.mcp.json<\/code><\/td>Compatibility apps<\/code> points to .\/.app.json<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n\n\n\n
Do not bundle a local server merely to avoid operating a proper remote service when the tool needs centralized customer data. Do not build a remote service merely to read a local repository. Choose the trust and deployment boundary that matches the data.<\/p>\n\n\n\n\n\n\n\n
Versioning and compatibility<\/h2>\n\n\n\n\n\n\n\n