agentskills-mcp-server

MCP server integration for the Agent Skills SDK - expose a skill registry as an MCP server.

Creates a Model Context Protocol server from a SkillRegistry, exposing skills as MCP tools and resources. Works with any MCP-compatible client (Claude Desktop, VS Code, custom clients, etc.).

Installation

pip install agentskills-mcp-server

With provider extras:

pip install agentskills-mcp-server[fs]    # filesystem provider
pip install agentskills-mcp-server[http]  # HTTP provider

With Agent Framework integration:

pip install agentskills-mcp-server[agentframework]  # MCP context provider for Agent Framework

Requires Python 3.12 or newer. Installs agentskills-core, mcp, and pydantic as dependencies.

Quick Start (CLI)

Create a server.json config file:

{
    "name": "My Skills Server",
    "skills": [
        {
            "id": "incident-response",
            "provider": "fs",
            "options": {"root": "./skills"}
        }
    ]
}

Start the server:

python -m agentskills_mcp_server --config server.json

With Streamable HTTP transport:

python -m agentskills_mcp_server --config server.json --transport streamable-http

The server listens on http://127.0.0.1:8000/mcp.

MCP Client Integration

Any MCP-compatible client (Claude Desktop, VS Code, etc.) can connect to the server.

Stdio (local):

{
    "command": "python",
    "args": ["-m", "agentskills_mcp_server", "--config", "server.json"]
}

Streamable HTTP (remote):

{
    "url": "http://127.0.0.1:8000/mcp"
}

Config Reference

The server.json file supports the following structure:

Each skill entry:

Provider options:

• fs: root (path to skills directory, default ".")
• http: base_url (required), headers (optional), params (optional query string parameters)

Only "fs" and "http" are supported as provider types.

Environment Variable Substitution

String values in the config file may contain ${VAR} placeholders that are resolved from environment variables at load time:

{
    "name": "My Skills Server",
    "skills": [
        {
            "id": "cloud-runbooks",
            "provider": "http",
            "options": {
                "base_url": "https://cdn.example.com/skills",
                "headers": { "Authorization": "Bearer ${API_TOKEN}" },
                "params": { "sig": "${SAS_TOKEN}" }
            }
        }
    ]
}

Unset variables resolve to an empty string and a warning is logged.

Programmatic Usage

For custom providers or advanced setups, use the Python API directly:

from agentskills_core import SkillRegistry
from agentskills_mcp_server import create_mcp_server

registry = SkillRegistry()
await registry.register("incident-response", my_custom_provider)  # any SkillProvider

server = create_mcp_server(registry, name="My Skills Server")
server.run()  # stdio by default

Agent Framework Context Provider

If you're using Microsoft Agent Framework, AgentSkillsMcpContextProvider bridges an MCP session into the Agent Framework lifecycle. It reads the skills catalog and usage-instruction resources from the MCP server and injects them as session instructions on every agent.run() call.

Note: This adapter only injects instructions, not tools. Agent Framework's MCP tool classes (MCPStdioTool, MCPStreamableHttpTool, etc.) handle tool registration natively.

pip install agentskills-mcp-server[agentframework]

from agent_framework import Agent, MCPStdioTool
from agentskills_mcp_server import AgentSkillsMcpContextProvider

mcp_skills = MCPStdioTool(
    name="skills",
    command="python",
    args=["-m", "agentskills_mcp_server", "--config", "server.json"],
)

async with mcp_skills:
    skills_context = AgentSkillsMcpContextProvider(
        session=mcp_skills.session,
    )
    agent = Agent(
        client=client,  # any Agent Framework chat client
        name="SREAssistant",
        instructions="You are an SRE assistant.",
        tools=mcp_skills,
        context_providers=[skills_context],
    )
    response = await agent.run("What severity is a full DB outage?")

See examples/agent-framework/ for full working demos including client setup.

Tools

The server exposes tools that let the LLM agent access skill content:

list_skill_resources returns a JSON object keyed by resource kind. Not every backend can enumerate resources — a plain static HTTP host cannot. Rather than surfacing an exception, the tool returns {"supported": false, "note": "..."} in that case: "this cannot be listed" is something the model can act on by falling back to the names in the skill body, not an error worth retrying.

Resources

The server provides resources for system-prompt context:

The MCP client reads these resources and injects them into the system prompt, giving the agent both what skills exist and how to interact with them.

API

AgentSkillsMcpContextProvider(session, *, skills_instruction_prompt=None, skills_catalog_format="xml", source_id=None)

A ContextProvider that reads the skills catalog and tools-usage-instructions from an MCP session and injects them as session instructions via before_run(). Requires the [agentframework] extra.

create_mcp_server(registry, *, name, instructions=None, max_inline_binary_bytes=65536) -> FastMCP

Returns a configured FastMCP instance ready for server.run().

Supported transport modes: stdio (default), streamable-http.

Binary Resources

Skill resources may be arbitrary files. Valid UTF-8 is returned as-is; anything else is returned as a JSON envelope, so a binary payload is never silently mangled into replacement characters:

{
  "name": "architecture.png",
  "media_type": "image/png",
  "size_bytes": 20481,
  "encoding": "base64",
  "content": "iVBORw0KGgo..."
}

Base64 costs roughly 1.37 characters per byte, so binaries above 64 KiB are described rather than inlined - "encoding": "none" plus a note explaining the omission. Adjust the ceiling with create_mcp_server(..., max_inline_binary_bytes=256 * 1024).

License

MIT