This server provides an MCP interface to search, read, and use a library of 180+ expert skills (codex-skills) via 8 tools, including discovering skills, planning workflows, loading skill files, and monitoring status.
Search & Discover: Use search_skills (natural language query) and list_categories to find relevant skills across 14 categories.
Plan Workflows: plan_workflow suggests skill combinations for a given task description.
Read Skills: read_skill downloads a skill to local cache and returns its full instructions (SKILL.md), file structure, and dependencies.
Access Skill Files: load_skill_file reads specific files (e.g., scripts, configs) within a skill; list_skill_files browses the file tree.
Verify & Diagnose: skill_status checks cache integrity; diagnostics audits recent calls, errors, cache stats, and configuration.
Automatic caching & syncing: Skills download on demand, with incremental caching and network fallback for reliability.
Dual operation modes: Use locally (via --skills-dir) or remotely (default, pulling from GitHub) with stdio or HTTP transport.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codex-skills-mcp find a skill to translate video subtitles"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Codex Skills MCP is a production-oriented Model Context Protocol server and an installable Codex/ChatGPT desktop plugin for a continuously updated expert-skill library. It indexes a lightweight catalog, searches locally, downloads selected skills on demand, verifies every file, and keeps the working set auditable on disk.
Available as: ChatGPT/Codex desktop plugin · standalone stdio MCP server · self-hosted Streamable HTTP MCP server.
Capability | What it means |
Progressive loading | Search costs tokens; full instructions and assets are downloaded only after a skill is selected. |
Small model surface by default | Standard MCP clients receive 8 focused tools. ChatGPT/Codex MCP Apps hosts can opt into the 22-tool UI surface. |
Integrity-first downloads | Known files are checked against size and Git blob SHA before entering the cache. |
Local-first cache | Skills materialize under |
Resilient installation | Direct GitHub, the official read-only mirror, jsDelivr and fallback mirrors can race without exposing credentials. |
Agent keeps judgment | Search results are candidates, not mandatory loading instructions. The agent can use none, one, or several skills. |
Related MCP server: studiox-skills-mcp
Requirements: Node.js 22 or newer.
npx -y codex-skills-mcp@betaThe current main line is 1.5.0-beta.17. Use the beta dist-tag to test
the features described here. The latest tag still points to stable 1.4.2 and
may lag behind the current MCP Apps and host-detection work.
codex mcp add codex-skills -- npx -y codex-skills-mcp@betaOr add this to ~/.codex/config.toml:
[mcp_servers.codex-skills]
command = "npx"
args = ["-y", "codex-skills-mcp@beta"]{
"mcpServers": {
"codex-skills": {
"command": "npx",
"args": ["-y", "codex-skills-mcp@beta"]
}
}
}Create .cursor/mcp.json in the project:
{
"mcpServers": {
"codex-skills": {
"command": "npx",
"args": ["-y", "codex-skills-mcp@beta"]
}
}
}More client and self-hosting setups are in Installation.
flowchart LR
A["MCP client"] --> B["Codex Skills MCP"]
B --> C["Local manifest + BM25 index"]
C --> D["Tool result: candidate skills"]
D --> E["read_skill: selected skill only"]
E --> F["Verified local cache"]
F --> G["Agent executes SKILL.md"]
F --> H["MCP App / resources"]The server never downloads the entire library at startup. It loads a compact manifest, builds a keyword/task index locally, then materializes complete skill directories only after selection. See Architecture and Agent protocol.
The screenshot uses the deterministic preview host. Live skill, domain and usage counts come from the current manifest and local usage history.
All standard MCP clients receive these 8 tools:
Tool | Purpose |
| Keyword or task-oriented skill discovery |
| Browse current categories and counts |
| Produce a candidate shortlist for a task |
| Materialize and read a selected skill |
| Read a supporting file from the cache |
| Browse files, nested skills, or a bounded file tree |
| Verify cache completeness |
| Inspect recent calls, errors, cache and configuration |
Host | Core tools | Interactive library / skill tray |
|
ChatGPT desktop app (local plugin) | Yes | Yes | Yes |
Codex desktop app | Yes | Yes | Yes |
ChatGPT web/mobile with a compatible remote MCP server | Yes | Depends on MCP Apps support | Depends on host |
Codex CLI, Claude Desktop, Cursor, Windsurf and other standard MCP clients | Yes | No | No |
中文兼容提示： 可视技能库和技能托盘（
skills.tray）是 MCP Apps 界面，不是标准 MCP 能力。安装本项目本地插件时，它们只会在支持 MCP Apps 的 ChatGPT 桌面端或 Codex 桌面端出现。Codex CLI、Claude Desktop、Cursor、 Windsurf 等客户端仍可使用 8 个核心工具和skill://资源，但不会显示技能托盘。 本地插件在 ChatGPT 中也只应在本地执行线程里使用，@提及不会出现在云端线程。
The bundled local plugin is Desktop only. Its UI library, skills.tray skill
tray, attachment handoff, @ mentions and native settings panel require a
ChatGPT/Codex desktop host that supports MCP Apps and OpenAI MCP extensions.
The local plugin can only be installed from the ChatGPT desktop app, and the
manifest is marked with requires_local_executor.
Standard MCP clients still receive the complete agent workflow through the 8
core tools and skill:// resources; they do not display the visual skill tray.
ChatGPT/Codex MCP Apps hosts additionally receive the interactive library, settings, mentions and app-facing tools. This includes:
skills.library, skills.tray, skills.browse and skills.query;
shared search history and progress tools;
inline image preview and per-skill cache removal;
settings.read, settings.update and refresh_skills_list;
search_mentions and the skill://{name} resource family.
Use --tool-profile core|full|auto to override host detection. The complete
reference is in Tools and
Host extensions.
The defaults work without a config file. Common options:
--cache-dir <path> Cache location
--skills-dir <path> Use a local skill library
--http Start Streamable HTTP transport
--host <addr> HTTP bind address
--port <port> HTTP port
--tool-profile <mode> auto | core | full
--manifest-ttl <seconds> Manifest refresh age
--manifest-poll <seconds> Background freshness poll
--download-concurrency <n> Parallel skill file downloads
--no-official-mirror Disable the official CN endpoint
--no-hedge Race all endpoints immediatelyFull flags, environment variables and persisted settings are documented in Configuration.
HTTP mode binds to 127.0.0.1 by default and validates Host/Origin allowlists.
GitHub credentials are sent only to GitHub endpoints, never to mirrors.
Skill paths are checked for traversal and symlink escapes.
Downloaded files are validated before they are accepted as cache content.
App Markdown is sanitized, and external links open with noopener noreferrer.
See SECURITY.md for vulnerability reporting and the threat model.
Personal, educational, open-source and internal business use is free. Commercial sale, paid deployment/support, paid hosting, or bundling with a paid product requires the official logo, non-original-source notice and source link defined by the license.
非原创：本项目基于 codex-skills-mcp（合塑研工）二次开发，由 [销售方名称] 独立提供，非原作者官方发行版。
Read Commercial licensing, the controlling LICENSE, and the ready-to-use brand assets. This is a source-available license, not a standard OSI-approved license.
Document | Contents |
Client setup, local mode, HTTP deployment | |
CLI, environment and persisted settings | |
Runtime components, cache and network design | |
Core, app and extension tool surface | |
Recommended discovery and execution flow | |
MCP Apps and OpenAI extension integration | |
Design constraints and reproducible benchmarks | |
Free use and commercial conditions | |
Release checklist and maintainer workflow |
npm ci
npm test
npm run build:plugin
npm run check:packageThe default suite is offline and covers search, cache validation, hedging, HTTP safety, MCP Apps, extension registration and real stdio flows. CI runs on Node.js 22 and 24.
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Use Support for operational questions.
src/ MCP server, search, loader, transport and tools
app-src/ MCP App frontend source
assets/ Built app asset
plugin/ Codex plugin distribution
brand/ Official logo and commercial attribution kit
docs/ User and maintainer documentation
examples/ Ready-to-copy MCP client configurations
scripts/ Build, verification and benchmark utilities
test/ Offline regression suitesCodex Skills MCP Commercial Attribution License 1.0, with an unofficial Chinese reference. Third-party content remains under its own terms; see NOTICE.
Codex Skills MCP is an independent project and is not an official product of OpenAI, Anthropic, Cursor or any other MCP host vendor.
List all skill categories in the codex-skills library with their skill counts. Use this to get an overview of available domains.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. The verb 'List' implies a read-only operation, and the description transparently states what is returned (categories with counts). It adds useful context about the library. No hidden behaviors are indicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and includes a clear usage hint. Every word earns its place with no redundancy or wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity, zero-parameter tool with no output schema. The description sufficiently explains what it does and when to use it, and it clearly separates itself from sibling tools. No additional context is needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, which earns a baseline of 4. The description adds no parameter-specific information because none is needed; the schema is empty and fully covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies the resource 'skill categories in the codex-skills library' with additional detail about skill counts. It clearly distinguishes itself from sibling tools like list_skill_files and search_skills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this to get an overview of available domains.' This provides clear context, though it does not mention when not to use it or name specific alternatives, which would warrant a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the file tree of a skill or a subdirectory within it. Use this to understand a large skill's structure before deciding which files to load.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Subdirectory path within the skill (default: root) | |
| max_depth | No | Directory scan depth (default: 2) | |
| skill_name | Yes | Skill name, e.g. 'KrillinAI' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It clarifies that the tool returns a file tree (not file contents), supports subdirectories, and is intended for structural exploration. However, it does not mention output format, pagination, or any side effects. As a read-only listing tool, this is acceptable but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and includes a usage hint. No unnecessary words or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with fully documented parameters and a clear purpose, the description is adequate. It does not explain the response format, but no output schema exists and the tool's behavior is straightforward. The usage guidance adds contextual value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all three parameters with descriptions and defaults (path, max_depth, skill_name). The description adds no extra parameter semantics beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List the file tree of a skill or a subdirectory within it') and identifies the specific resource (skill file tree). It also distinguishes this tool from siblings by positioning it as a pre-loading exploration step, contrasting with read/load tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage advice: 'Use this to understand a large skill's structure before deciding which files to load.' This implies when to use (before loading) and differentiates from load/read siblings. However, it does not name alternatives explicitly or state when not to use, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a specific file from within a skill's directory. Use this after read_skill when you need to access scripts, configs, README, or other resources referenced in the skill instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Relative path within the skill directory, e.g. 'README.md' or 'scripts/run.py' | |
| skill_name | Yes | Skill name, e.g. 'MediaCrawler' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full transparency burden. It clarifies the read-only nature and the target within the skill directory, but it lacks details on return format, error handling for missing files, or path traversal limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the core purpose and followed by a single usage guideline. No word is wasted, and it maintains clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read operation, the description covers the what, when, and how to locate file paths via the skill instructions. It could mention discovering file paths with list_skill_files or error behavior, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters with descriptions and examples, so the baseline is 3. The description adds meaningful context by specifying the types of files (scripts, configs, README) and that paths come from the skill instructions, enriching the file_path semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read a specific file from within a skill's directory', with a specific verb and resource. It distinguishes itself from sibling tools by referencing usage after read_skill and targeting scripts, configs, README, and other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use this tool after read_skill when accessing referenced files, providing a clear use case. It implicitly names read_skill as the alternative for reading the skill's main instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given a task description, suggest relevant skills that could be combined to accomplish it. Returns a list of recommended skills — the actual orchestration and execution order should be decided by you (the Agent).
| Name | Required | Description | Default |
|---|---|---|---|
| task_description | Yes | Full description of the task to accomplish, e.g. '把技术博客文章转换成小红书图文并发布' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description carries the burden well. It explicitly states that the tool only suggests skills and returns a list, while the actual orchestration/execution order is left to the agent. This sets clear expectations about the tool's advisory nature and lack of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and every word earns its place. It avoids redundancy and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is complete. It covers the input, output, and the agent's responsibility for orchestration, giving enough context for correct selection and invocation without extra fluff.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the description's 'task_description' aligns with the schema's 'Full description of the task to accomplish'. The description adds no additional meaning beyond what the schema already captures, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('suggest') and resource ('relevant skills') to state its function clearly. It distinguishes from sibling tools (search_skills, read_skill) by focusing on combining skills for a task rather than searching or reading individual skills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly implies when to use: given a task description, to get skill recommendations. It also clarifies the agent retains control over orchestration and execution order, which is important guidance. However, it does not explicitly mention when not to use it or alternative tools for specific skill lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a skill's full instructions (SKILL.md), file structure, and dependency info. Call this after search_skills to load a skill you want to use. The instructions contain the role and execution rules you should follow.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact skill name from search results, e.g. 'MediaCrawler' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool reads instructions, file structure, and dependency info, and notes that instructions contain role and execution rules. This is a read operation with no side effects implied, and the description gives meaningful context beyond a bare 'reads skill'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and every sentence adds value. The first sentence specifies what the tool does, the second gives usage guidance and context about the content. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single parameter, no output schema, no annotations), the description is adequately complete. It explains what is read and when to use it. It does not describe the return format, but for a simple read operation this is a minor gap, not a major deficiency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'name' is fully described in the schema (100% coverage), including the requirement for an exact name from search results. The description adds no additional parameter semantics beyond reinforcing the workflow context, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a skill's full instructions (SKILL.md), file structure, and dependency info. It uses a specific verb (read) and resource (skill), and distinguishes from siblings like list_skill_files and load_skill_file by explicitly mentioning the full instructions and broader scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to call this after search_skills to load a skill, providing clear when-to-use guidance. It does not explicitly exclude alternatives like load_skill_file or list_skill_files, but the workflow context is helpful and sufficient for a simple read operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the codex-skills library by natural language query. Returns matching skills ranked by relevance. Use this as the primary entry point to discover skills for a task.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of results to return (default: 8) | |
| query | Yes | Natural language description of what you need, e.g. '前端性能优化' or 'video subtitle translation' | |
| category | No | Optional category filter, e.g. '05_多媒体与设计资产' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that results are 'matching skills ranked by relevance' and implies a read-only search, but does not cover edge cases, result structure, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the verb and resource, and no wasted words. Each sentence carries meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity search tool with a complete input schema, the description provides adequate return semantics ('ranked by relevance') and usage context. It lacks output structure details since no output schema exists, but this is not critical for selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the schema with defaults and examples, so the description adds no additional parameter-level detail. The baseline of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('codex-skills library') with clear scope ('by natural language query'). It differentiates from siblings like list_categories and read_skill by focusing on discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it: 'Use this as the primary entry point to discover skills for a task.' It provides clear context but doesn't name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.6list_categorieslist_skill_filesload_skill_fileplan_workflowread_skillsearch_skillsScored across 6 tools
search_skills and plan_workflow both return skill recommendations, which could cause slight confusion, but the descriptions clarify that search_skills is for finding a single skill while plan_workflow is for combining multiple skills. The other tools (list_categories, read_skill, load_skill_file, list_skill_files) have clearly distinct purposes.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (search_skills, list_categories, read_skill, load_skill_file, list_skill_files, plan_workflow). No mixing of styles or irregular naming.
Six tools is well-scoped for a skill library server, covering discovery, browsing, reading, and planning without excess or deficiency.
The tool set fully covers the lifecycle of using a skill library: discovering skills (search_skills), exploring categories (list_categories), reading skill instructions (read_skill), accessing files (list_skill_files, load_skill_file), and planning multi-skill workflows (plan_workflow). No obvious gaps for a read-only skill consumption server.
Governed AI agent skills — one library, distributed to devs and exposed to remote agents over MCP.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Hosted MCP server for live public-data APIs and Skills for AI agents.
