MCP Server
Why
The Model Context Protocol (MCP) enables agent interoperability by providing a standardized contract between AI agents and external capabilities. Without a shared protocol, each agent runtime would require custom adapters for every tool, resource, and prompt source. MCP eliminates this fragmentation by defining a single discovery and invocation surface that any compliant agent can consume. This means quirk Skills can be exposed once and consumed by Claude Code, Kilo, or any future MCP-compatible runtime without rewriting skill logic.
Contract
- Input: skill registry paths (
.agents/skills/ and .claude/skills/), transport selection (stdio or sse), optional endpoint for sse.
- Output:
McpServerArtifact with typed schema for tools, resources, prompts, transport, endpoint, and skillsExposed.
- Scope: expose quirk Skills via Model Context Protocol; do not modify skill source files or consume external data sources.
- Rule: every exposed tool maps to a skill capability with explicit input and output schemas.
- Rule: resources must point to static skill documentation; do not expose mutable state.
- Rule: prompts must be versioned and tied to specific workflow combinations.
- Rule: transport selection must match the deployment context —
stdio for local, sse for remote.
- Rule: exclude skills with
trustTier > 3 from automatic exposure; require explicit allow-list.
- Rule: do not expose secrets, credentials, or environment variable values in any generated artifact.
Provenance
| Quality-Bar Question |
Evidence |
| Intent |
Define an MCP server that exposes quirk Skills as tools, resources, and prompts to external LLM agents via the Model Context Protocol. |
| Input |
skill registry paths, transport selection, endpoint configuration. |
| Output |
McpServerArtifact with typed schema for tools, resources, prompts, transport, endpoint, and skillsExposed. |
| Side effects |
writes server configuration files to disk. |
| Boundaries |
exposes skills via MCP; does not modify skill source files or consume external data sources. |
| Completion criteria |
all discovered skills are mapped to MCP tools, resources, and prompts; transport is configured and validated; artifact is saved; completion criteria are checked. |
Artifact
Emit McpServerArtifact as both:
- JSON:
.agents/skills/foundation/mcp-server/artifacts/{request-id}.json
- Markdown view: same filename with
.md extension
Observability: the artifact must include a traceId field for correlating MCP server invocations with downstream skill executions. Each tool entry must record the skillName it maps to, enabling downstream metrics to attribute latency and errors to specific skills.
The traceId in each artifact entry lets operators trace a single MCP session through multiple tool calls and downstream skill executions. This makes it possible to measure per-skill latency and error rates in production observability tools.
The artifact must include the typed schema for McpServerArtifact:
tools: array of MCP tool definitions generated from skill frontmatter capabilities. Each tool must include name, description, inputSchema, and outputSchema.
resources: array of MCP resource definitions pointing to skill documentation. Each resource must include uri, name, description, and mimeType.
prompts: array of MCP prompt templates for common workflows. Each prompt must include name, description, arguments, and messages.
transport: enum [stdio, sse]
endpoint: string (required for sse transport)
skillsExposed: array of skill names exposed through the server
Process
Step 1: Load skill registry from .agents/skills/ and .claude/skills/
Scan both canonical and compatibility view directories for SKILL.md files. Build a registry of available skills with their names, categories, capabilities, and frontmatter metadata. Validate each skill's frontmatter before inclusion. Skip skills missing required fields and log warnings for incomplete entries.
Step 2: Generate MCP tool definitions from skill frontmatter
For each skill in the registry, generate an MCP tool definition using the format in references/tool-schema.md. Map skill capabilities to tool names. Include inputSchema and outputSchema based on the skill's inputs and outputs. Enforce the rule that tools with side effects require explicit allow-list.
Step 3: Generate MCP resource definitions for skill documentation
For each skill, generate an MCP resource definition that exposes the SKILL.md content. Resources should be read-only and point to the canonical skill path. Include the skill name, description, and MIME type text/markdown. Do not expose mutable state through resources.
Step 4: Generate MCP prompt templates for common workflows
Generate prompt templates for common workflow combinations:
- skill discovery: list and filter available skills by category or tag
- skill execution: invoke a skill by name with arguments
- workflow chaining: combine multiple skills in sequence
Each prompt template must include a version, description, and argument schema. Version all prompts to support future updates without breaking existing consumers.
Step 5: Expose via stdio or SSE transport
Configure the MCP server transport based on deployment context:
stdio: for local agent integration, reads from stdin and writes to stdout
sse: for remote agent integration, requires endpoint configuration and HTTP server
Write the server configuration to disk and validate the transport connection. Default to stdio when transport is unspecified. For sse, ensure the endpoint is reachable and returns valid MCP handshake responses.
Completion Criteria
- all discovered skills are mapped to MCP tools, resources, and prompts
- transport is configured and validated
- artifact is saved
- completion criteria are checked
@include .agents/skills/platform/contract-base.xml
Reference
references/mcp-spec.md — MCP protocol overview, transport mechanisms, message types, and security boundaries.
references/tool-design.md — tool definition best practices for naming, schemas, versioning, and side-effect declaration.
scripts/validate-schema.mjs — minimal JSON Schema validator used during artifact emission.
Validation
Before emitting the artifact, run scripts/validate-schema.mjs against the generated JSON to ensure the artifact conforms to the declared schema. If validation fails, fix the artifact generation logic rather than suppressing errors.
This skill follows the Model Context Protocol specification and integrates with the quirk Skills bundle without modifying source files.
1---2name: mcp-server3category: foundation4maturity: beta5version: 26description: Define an MCP server that exposes quirk Skills as tools, resources, and prompts to external LLM agents via the Model Context Protocol.7license: MIT8capabilities:9 - generate-skill-resources10 - generate-workflow-prompts11 - configure-transport12 - trace mcp server decisions across inputs, constraints, and failure paths13 - validate foundation outcomes with evidence, assumptions, and explicit next steps14inputs:15 - "skill-registry-paths: .agents/skills/ and .claude/skills/"16 - "transport: stdio or sse"17 - "endpoint: for sse transport"18outputs:19 - type: object20 name: McpServerArtifact21 properties:22 tools:23 type: array24 items:25 type: object26 resources:27 type: array28 items:29 type: object30 prompts:31 type: array32 items:33 type: object34 transport:35 type: string36 enum: [stdio, sse]37 endpoint:38 type: string39 skillsExposed:40 type: array41 items:42 type: string43 required: [tools, resources, prompts, transport, skillsExposed]44sideEffects:45 - write-files46dependencies: []47stopCondition: MCP server configured with tools, resources, and prompts generated; transport exposed; artifact saved; completion criteria checked.48risk: low49trustTier: 150maxIterations: 551modelTier: router52promptVersion: "2.0"53artifactType: plan54evaluators: [behavioral, traceability]55fixturesPath: .agents/skills/platform/fixtures/regression/mcp-server.json56diataxis: how-to57tags:58 - mcp59 - protocol60 - tools61 - resources62 - prompts63 - agent-discovery64compatibility:65 - all skills66approvalRequired: true67approvalFor: ["write-files"]68metadata:69 source: https://skillmd.com/skills/quantumquirkxyz/mcp-server70---7172# MCP Server7374## Why7576The Model Context Protocol (MCP) enables agent interoperability by providing a standardized contract between AI agents and external capabilities. Without a shared protocol, each agent runtime would require custom adapters for every tool, resource, and prompt source. MCP eliminates this fragmentation by defining a single discovery and invocation surface that any compliant agent can consume. This means quirk Skills can be exposed once and consumed by Claude Code, Kilo, or any future MCP-compatible runtime without rewriting skill logic.7778## Contract7980- Input: skill registry paths (`.agents/skills/` and `.claude/skills/`), transport selection (`stdio` or `sse`), optional endpoint for `sse`.81- Output: `McpServerArtifact` with typed schema for `tools`, `resources`, `prompts`, `transport`, `endpoint`, and `skillsExposed`.82- Scope: expose quirk Skills via Model Context Protocol; do not modify skill source files or consume external data sources.83- Rule: every exposed tool maps to a skill capability with explicit input and output schemas.84- Rule: resources must point to static skill documentation; do not expose mutable state.85- Rule: prompts must be versioned and tied to specific workflow combinations.86- Rule: transport selection must match the deployment context — `stdio` for local, `sse` for remote.87- Rule: exclude skills with `trustTier > 3` from automatic exposure; require explicit allow-list.88- Rule: do not expose secrets, credentials, or environment variable values in any generated artifact.8990## Provenance9192| Quality-Bar Question | Evidence |93|---|---|94| **Intent** | Define an MCP server that exposes quirk Skills as tools, resources, and prompts to external LLM agents via the Model Context Protocol. |95| **Input** | skill registry paths, transport selection, endpoint configuration. |96| **Output** | `McpServerArtifact` with typed schema for `tools`, `resources`, `prompts`, `transport`, `endpoint`, and `skillsExposed`. |97| **Side effects** | writes server configuration files to disk. |98| **Boundaries** | exposes skills via MCP; does not modify skill source files or consume external data sources. |99| **Completion criteria** | all discovered skills are mapped to MCP tools, resources, and prompts; transport is configured and validated; artifact is saved; completion criteria are checked. |100101## Artifact102103Emit `McpServerArtifact` as both:104- JSON: `.agents/skills/foundation/mcp-server/artifacts/{request-id}.json`105- Markdown view: same filename with `.md` extension106107Observability: the artifact must include a `traceId` field for correlating MCP server invocations with downstream skill executions. Each tool entry must record the `skillName` it maps to, enabling downstream metrics to attribute latency and errors to specific skills.108109110The `traceId` in each artifact entry lets operators trace a single MCP session through multiple tool calls and downstream skill executions. This makes it possible to measure per-skill latency and error rates in production observability tools.111The artifact must include the typed schema for `McpServerArtifact`:112113- `tools`: array of MCP tool definitions generated from skill frontmatter capabilities. Each tool must include `name`, `description`, `inputSchema`, and `outputSchema`.114- `resources`: array of MCP resource definitions pointing to skill documentation. Each resource must include `uri`, `name`, `description`, and `mimeType`.115- `prompts`: array of MCP prompt templates for common workflows. Each prompt must include `name`, `description`, `arguments`, and `messages`.116- `transport`: enum `[stdio, sse]`117- `endpoint`: string (required for `sse` transport)118- `skillsExposed`: array of skill names exposed through the server119120## Process121122### Step 1: Load skill registry from `.agents/skills/` and `.claude/skills/`123124Scan both canonical and compatibility view directories for `SKILL.md` files. Build a registry of available skills with their names, categories, capabilities, and frontmatter metadata. Validate each skill's frontmatter before inclusion. Skip skills missing required fields and log warnings for incomplete entries.125126### Step 2: Generate MCP tool definitions from skill frontmatter127128For each skill in the registry, generate an MCP tool definition using the format in `references/tool-schema.md`. Map skill capabilities to tool names. Include `inputSchema` and `outputSchema` based on the skill's inputs and outputs. Enforce the rule that tools with side effects require explicit allow-list.129130### Step 3: Generate MCP resource definitions for skill documentation131132For each skill, generate an MCP resource definition that exposes the `SKILL.md` content. Resources should be read-only and point to the canonical skill path. Include the skill name, description, and MIME type `text/markdown`. Do not expose mutable state through resources.133134### Step 4: Generate MCP prompt templates for common workflows135136Generate prompt templates for common workflow combinations:137- skill discovery: list and filter available skills by category or tag138- skill execution: invoke a skill by name with arguments139- workflow chaining: combine multiple skills in sequence140141Each prompt template must include a version, description, and argument schema. Version all prompts to support future updates without breaking existing consumers.142143### Step 5: Expose via stdio or SSE transport144145Configure the MCP server transport based on deployment context:146- `stdio`: for local agent integration, reads from stdin and writes to stdout147- `sse`: for remote agent integration, requires endpoint configuration and HTTP server148149Write the server configuration to disk and validate the transport connection. Default to `stdio` when transport is unspecified. For `sse`, ensure the endpoint is reachable and returns valid MCP handshake responses.150151## Completion Criteria152153- all discovered skills are mapped to MCP tools, resources, and prompts154- transport is configured and validated155- artifact is saved156- completion criteria are checked157158@include .agents/skills/platform/contract-base.xml159160## Reference161162- `references/mcp-spec.md` — MCP protocol overview, transport mechanisms, message types, and security boundaries.163- `references/tool-design.md` — tool definition best practices for naming, schemas, versioning, and side-effect declaration.164- `scripts/validate-schema.mjs` — minimal JSON Schema validator used during artifact emission.165166## Validation167168Before emitting the artifact, run `scripts/validate-schema.mjs` against the generated JSON to ensure the artifact conforms to the declared schema. If validation fails, fix the artifact generation logic rather than suppressing errors.169This skill follows the Model Context Protocol specification and integrates with the quirk Skills bundle without modifying source files.170