MCP server integration
Serves the official Skills extension on MCP SDK 2.2+ and protocol 2026-07-28. See the migration guide and server setup.
pip install "agentskills-mcp-server[fs]>=0.7,<0.8"
The command above applies once v0.7 is published. Until then, install the checkout.
agentskills_mcp_server.native.create_mcp_server
async
¶
create_mcp_server(skills: SkillRegistry | Sequence[Skill], *, name: str = 'AgentSkills', instructions: str | None = None, skill_paths: Mapping[str, str] | None = None, listed_skill_ids: Collection[str] | None = None, page_size: int = 100, max_skills: int = 128, max_total_bytes: int = 64 * 1024 * 1024, publication_policy: Callable[[SkillSnapshot], Publication] | None = None, origin: str = 'unconfigured', max_stale_age: float = 0, observer: Callable[[DisclosureEvent], None] | None = None, auth: AuthSettings | None = None, token_verifier: TokenVerifier | None = None) -> NativeSkillsServer
Capture immutable sources and serve the official Skills extension.
Requires MCP SDK 2.2+ and protocol 2026-07-28. No tools, catalog
injection, execution, or directory-read capability are registered.
Call await server.refresh() to publish a new snapshot. Callers supply only skills
authorized for the server's audience. Hosts retain approval and trust duties.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
skills
|
SkillRegistry | Sequence[Skill]
|
An existing registry or raw lossless skill handles. |
required |
name
|
str
|
Server display name, not an origin identity or trust assertion. |
'AgentSkills'
|
instructions
|
str | None
|
Explicit server instructions, without automatic catalog injection. |
None
|
skill_paths
|
Mapping[str, str] | None
|
Unescaped paths keyed by handle ID, ending in each declared name. |
None
|
listed_skill_ids
|
Collection[str] | None
|
Optional listing subset, never an access-control boundary. |
None
|
page_size
|
int
|
Complete skill entries per listing page. |
100
|
max_skills
|
int
|
Maximum number of captured handles. |
128
|
max_total_bytes
|
int
|
Maximum aggregate retained file bytes across captures. |
64 * 1024 * 1024
|
publication_policy
|
Callable[[SkillSnapshot], Publication] | None
|
Trusted verifier/content policy called before manifests. Omission explicitly publishes unsigned content, never verified content. |
None
|
origin
|
str
|
Stable non-secret source identity, not a display name. |
'unconfigured'
|
max_stale_age
|
float
|
Opt-in maximum age in seconds for verified outage snapshots. |
0
|
observer
|
Callable[[DisclosureEvent], None] | None
|
Optional privacy-preserving disclosure observer. |
None
|
auth
|
AuthSettings | None
|
Deployment-supplied MCP authorization settings for remote HTTP. |
None
|
token_verifier
|
TokenVerifier | None
|
Deployment-supplied token validator. Never reused upstream. |
None
|
Returns:
| Type | Description |
|---|---|
NativeSkillsServer
|
A modern MCP server ready for stdio or Streamable HTTP transport. |
Raises:
| Type | Description |
|---|---|
ValueError
|
Publication options, manifests, bounds, or overlapping captures conflict. |
FileAccessNotSupportedError
|
A provider cannot supply complete original files. |
SkillUnavailableError
|
A source changes during capture or becomes unavailable. |
Server¶
agentskills_mcp_server.native.NativeSkillsServer ¶
Bases: MCPServer
Native server with explicit refresh and audience-scoped readiness.
Call refresh from an application-owned control path. Keep providers open
for its lifetime. Neither refresh nor health is an MCP execution tool.
health ¶
health() -> dict[str, Any]
Report publication readiness without implying deployment certification.
list_resources
async
¶
list_resources() -> list[Resource]
List only the current coherent resource generation.
read_resource
async
¶
read_resource(uri: Any, context: Any = None) -> list[ReadResourceContents]
Read captured bytes, never refetching or implicitly activating a skill.
refresh
async
¶
refresh() -> dict[str, Any]
Atomically republish fresh source content, applying current policies.
secure_http_app ¶
secure_http_app(*, allowed_hosts: Sequence[str], allowed_origins: Sequence[str]) -> Any
Build remote HTTP with explicit origin/host policy and MCP authorization.
Supply auth and token_verifier at construction. Terminate TLS
through the deployment. Use a distinct server/catalog for each audience.
This helper never forwards incoming tokens to skill providers.
Configuration¶
agentskills_mcp_server.config.ServerConfig ¶
Bases: BaseModel
Top-level configuration for an Agent Skills MCP server.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Display name shown to MCP clients during initialization. |
instructions |
str | None
|
Optional server-level instructions sent to the client during the MCP handshake. |
skills |
list[SkillConfig]
|
One or more skill definitions to register. |
build_publication_policy ¶
build_publication_policy() -> Callable[[SkillSnapshot], Publication] | None
Require an explicit trust policy for every skill when verification is configured.