MCP Skill Server

Most coding assistants now support skills natively, so an MCP server just for skill discovery isn't necessary. Where this package adds value is making skills' execution deterministic and deployable — with a fixed entry point and controlled execution, skills developed in your editor can run in non-sandboxed production environments. It also supports incremental loading, so agents discover skills on demand instead of loading everything upfront.

---

MCP Skill Server

Build agent skills where you work. Write a Python script, add a SKILL.md, and your agent can use it immediately. Iterate in real-time as part of your daily workflow. When it's ready, deploy the same skill to production — no rewrite needed.

Why?

Most skill development looks like this: write code → deploy → test in a staging agent → realize it's wrong → redeploy → repeat. It's slow, and you never get to actually *use* the skill while building it.

MCP Skill Server flips this. It runs on your machine, inside your editor — Claude Code, Cursor, or Claude Desktop. You develop a skill and use it in your real work at the same time. That tight feedback loop (edit → save → use) means you discover what's missing naturally, not through artificial test scenarios. The premise is if the skill doesn't work well with Claude Code, it's unlikely to work with a less sophisticated agent.

How skills mature to survive in the outside world

Claude skills can already have companion scripts, but there's no formalized entry point — the agent decides how to invoke them. That works for local use, but it's not deployable: a production MCP server can't reliably call a skill if the execution path isn't fixed.

MCP Skill Server enforces a declared `entry` field in your SKILL.md frontmatter (e.g. entry: uv run python my_script.py). This gives you a single, fixed entry point that the server controls. Commands and parameters are discovered from the script's --help output — that's the source of truth, not the LLM's interpretation of your code.

1. Claude/coding agent skill                → SKILL.md + scripts, but no fixed entry — agent decides how to run them

1. Local MCP skill (+ entry) → Fixed entry point, schema from --help, usable daily via this server
2. Production → Same skill, same entry — deployed to your enterprise MCP server

Sharpen locally, then harden for production

Every agent that connects to the MCP server gets the same interface — list_skills, get_skill, run_skill — so the skill's description, parameter names, and help text are identical regardless of which agent calls them. That said, different agents have different strengths — a skill that works locally still needs testing with your production agent.

1. Use it yourself — build the skill, use it daily via Claude Code or Cursor. Fix descriptions and param names when the agent misuses the skill.
2. Test with a weaker model — try a smaller model to surface interface ambiguity.
3. Add a deterministic entry point — declare entry in SKILL.md for reliable, secure execution. Use skill init to scaffold it, skill validate to check readiness.
4. Test with your production agent — verify end-to-end in your target environment, then deploy.

Install

Claude Desktop (one-click)

After installing, edit the skills path in your Claude Desktop config to point to your skills directory.

Claude Code

claude mcp add skills -- uvx mcp-skill-server serve /path/to/my/skills

Cursor

Add to .cursor/mcp.json in your project (or Settings → MCP → Add Server):

{

"mcpServers": { "skills": { "command": "uvx", "args": ["mcp-skill-server", "serve", "/path/to/my/skills"] } } }

Manual install

# From PyPI (recommended)

uv pip install mcp-skill-server

Or from source

git clone https://github.com/jcc-ne/mcp-skill-server cd mcp-skill-server && uv sync

Run the server

uvx mcp-skill-server serve /path/to/my/skills

Then add to your editor's MCP config:

{

"mcpServers": { "skills": { "command": "uvx", "args": ["mcp-skill-server", "serve", "/path/to/my/skills"] } } }

Creating a Skill

Option A: Use skill init (recommended)

# Create a new skill

uv run mcp-skill-server init ./my_skills/hello -n "hello" -d "A friendly greeting"

Or use the standalone command

uv run mcp-skill-init ./my_skills/hello -n "hello" -d "A friendly greeting"

Promote an existing prompt-only Claude skill to a runnable MCP skill

uv run mcp-skill-init ./existing_claude_skill

Option B: Manual setup

1. Create a folder with your script

my_skills/

└── hello/ ├── SKILL.md └── hello.py

2. Add SKILL.md with frontmatter

---

name: hello description: A friendly greeting skill entry: uv run python hello.py

---

Hello Skill

Greets the user by name.

3. Write your script with argparse

# hello.py

import argparse

parser = argparse.ArgumentParser(description="Greeting skill") parser.add_argument("--name", default="World", help="Name to greet") args = parser.parse_args()

print(f"Hello, {args.name}!")

That's it. The server auto-discovers commands and parameters from your --help output — no config needed.

Validating for Deployment

When a skill is ready to graduate to production:

uv run mcp-skill-server validate ./my_skills/hello

or

uv run mcp-skill-validate ./my_skills/hello

Checks:

• Required frontmatter fields (name, description, entry)
• Entry command uses allowed runtime
• Script file exists
• Commands discoverable via --help

How It Works

MCP Tools

The server exposes four tools to your agent:

Schema Discovery

The server automatically discovers your skill's interface by parsing --help output:

# Subcommands become separate commands

subparsers = parser.add_subparsers(dest='command') analyze = subparsers.add_parser('analyze', help='Run analysis')

Arguments become parameters with inferred types

analyze.add_argument('--year', type=int, required=True) # int, required analyze.add_argument('--file', type=str) # string, optional

Output Files

Files saved to output/ are automatically detected. Alternatively, print OUTPUT_FILE:/path/to/file to stdout.

Plugins

Output Handlers

Process files generated by skills (upload, copy, transform, etc.):

from mcp_skill_server.plugins import OutputHandler, LocalOutputHandler

Default: tracks local file paths

handler = LocalOutputHandler()

Optional GCS handler (requires uv sync --extra gcs)

from mcp_skill_server.plugins import GCSOutputHandler handler = GCSOutputHandler( bucket_name="my-bucket", folder_prefix="skills/outputs/", )

Response Formatters

Customize how execution results are formatted in MCP tool responses:

from mcp_skill_server.plugins import ResponseFormatter

class CustomFormatter(ResponseFormatter): def format_execution_result(self, result, skill, command): return f"Result: {result.stdout}"

Use with create_server()

from mcp_skill_server import create_server server = create_server( "/path/to/skills", response_formatter=CustomFormatter() )

Development

git clone https://github.com/jcc-ne/mcp-skill-server

cd mcp-skill-server uv sync --dev uv run pytest uv run mcp-skill-server serve examples/

Further Reading

• Tool Design for LLMs — Why skills use a list/get/run pattern instead of exposing raw tools, and how it affects LLM accuracy

License

MIT