| Guide ID | A-6 |
|---|---|
| Audience | Developers, Integrators |
| Prerequisites | A-1: Chipset Architecture, GS-3: How It Works |
| Time | 15 minutes |
| Difficulty | Advanced |
MCP Integration
The Amiga did not exist in isolation. Its Zorro expansion bus connected it to a growing ecosystem of third-party hardware. Its IFF file format enabled data exchange between applications. Its Arexx scripting language allowed programs to communicate and automate each other. The Amiga was powerful alone but transformative when connected.
The Model Context Protocol (MCP) serves a similar role for AI tools. MCP is an open standard that defines how AI applications discover, connect to, and use external tool servers. gsd-skill-creator participates in this ecosystem in two directions: as an MCP consumer (using tools provided by external MCP servers) and as an MCP provider (making skills available to other systems through MCP). This bidirectional integration transforms gsd-skill-creator from a local skill management tool into a node in a distributed intelligence network.
As MCP Consumer
When gsd-skill-creator operates within a Claude Code session, it can access any MCP server configured in the environment. This means skills and workflows can invoke external tools without implementing those tools themselves. Three integration patterns demonstrate the consumer role.
WordPress Publishing via claudeus-wp-mcp
The gsd-skill-creator project itself uses the claudeus-wp-mcp MCP server to publish documentation directly to WordPress. This is not a theoretical integration — the documentation you are reading was staged as HTML files and published to WordPress through MCP tool calls. The claudeus-wp-mcp server provides tools for content management (creating, updating, and retrieving posts and pages), taxonomy management (categories and tags), media management, menu management, and theme customization.
This integration demonstrates a key MCP principle: the AI system does not need to understand the WordPress REST API. It calls MCP tools with structured parameters and receives structured results. The MCP server handles authentication, error handling, and API translation. From the skill's perspective, publishing is just another tool call.
Context7 for Library Documentation
When skills need to reference up-to-date library documentation (API signatures, usage examples, migration guides), they can query Context7 or similar documentation MCP servers. This is particularly valuable for skills that provide framework-specific guidance: rather than embedding framework documentation in the skill content (which becomes stale), the skill can retrieve current documentation on demand during activation.
This pattern keeps skill content focused on how to apply knowledge rather than what the knowledge is. The skill provides the judgment; the MCP server provides the facts.
Custom MCP Servers
Organizations can build custom MCP servers for domain-specific tools: internal API clients, CI/CD triggers, database query interfaces, monitoring dashboards. Skills and agents in gsd-skill-creator can invoke these tools as part of their workflows, enabling AI-assisted automation that reaches beyond the local filesystem into the organization's infrastructure.
The key constraint is that MCP tool calls are always mediated by the AI session. A skill cannot directly call an MCP server — it instructs Claude Code to make the call, and Claude Code uses its configured MCP connections. This keeps the security model consistent: all tool use flows through the same permission and confirmation system.
As MCP Provider
The provider role is the more ambitious direction (v1.9). Instead of just consuming external tools, gsd-skill-creator can make its skills available to other systems through an MCP skill server.
Skill Portability
The portability module (src/portability/) handles cross-platform skill export. Skills created in gsd-skill-creator use a specific frontmatter format with extension fields. The export system produces platform-neutral skill representations that can be consumed by other AI tool systems, shared across organizations, or stored in centralized skill registries. Import converts external skill formats into gsd-skill-creator's native format, mapping foreign metadata to the appropriate extension fields.
MCP Skill Server Architecture
The MCP skill server (src/mcp/) exposes gsd-skill-creator's skill inventory as MCP tools. A remote Claude Code session can query available skills, request skill content at a specific disclosure level, and receive skill recommendations based on context. The server respects the same pipeline invariants as local skill loading: budget constraints, scope resolution, and tier ordering apply regardless of whether the consumer is local or remote.
This enables organizational skill sharing. A team lead can curate a skill repository that team members access through MCP, ensuring consistent practices without requiring every developer to maintain their own skill installations. Updates to shared skills propagate automatically on the next session startup.
Agentic RAG
Agentic RAG (Retrieval-Augmented Generation) extends the chipset architecture with intelligent content retrieval. Rather than loading all skill content into the context window upfront, the retrieval system (src/retrieval/) provides content on demand at the appropriate level of detail.
Tiered Content
Skill content is organized into three retrieval tiers, each optimized for a different context budget:
Summary tier (~2K characters). A compressed representation of the skill's core guidance. Loaded when the context budget is tight or when the skill's relevance is moderate. Provides enough information for Claude to know what the skill covers and when to request the full version. This is what gets loaded during the Budget stage when a full skill would exceed the remaining budget.
Active tier (~10K characters). The standard working content of the skill. Loaded during normal operation when the skill's relevance is high and the budget allows. Contains actionable guidance, code examples, and decision criteria. This is the tier most skills operate at during typical sessions.
Reference tier (full content). The complete skill content including all reference material, historical context, edge cases, and detailed examples. Not loaded into the context window by default. Retrieved on demand when Claude needs deep information — for example, when debugging an edge case that the active tier does not cover. Reference material lives in the skill's reference.md file and is fetched through Denise's progressive disclosure system.
The tiered model is the retrieval equivalent of the Amiga's memory architecture. Chip RAM (fast, limited, always available) corresponds to the summary tier. Fast RAM (larger, slightly slower) corresponds to the active tier. Disk storage (vast, slow, loaded on demand) corresponds to the reference tier. The system automatically manages promotion and demotion between tiers based on relevance, budget pressure, and access patterns.
Integration Configuration
MCP-related configuration lives in the project's .planning/skill-creator.json alongside other skill-creator settings. The MCP section specifies which MCP servers are recognized for skill distribution, what trust level each server has, and how skill content from remote servers interacts with local skills (whether remote skills can shadow local skills, or only supplement them).
Claude Code's own MCP configuration (in .claude/settings.json or the global settings) controls which MCP servers are available to the session. gsd-skill-creator reads these settings to discover available servers but does not modify them. The separation ensures that MCP server configuration remains under the user's explicit control.
Security Considerations
MCP integration introduces trust boundary concerns that do not exist in a purely local system. gsd-skill-creator enforces several security principles at the MCP boundary.
Skill name sanitization. Skill names received from MCP servers are sanitized before being used in file paths. This prevents path traversal attacks where a malicious server provides a skill named ../../.env to read sensitive files. Sanitization strips path separators, null bytes, and other dangerous characters, and validates that the resulting name matches the expected pattern (lowercase letters, numbers, hyphens).
No automatic code execution. Skills received via MCP are treated as guidance content, not executable code. Even if a skill's content includes code blocks, those blocks are presented to the AI as examples, not executed automatically. The scripts/ directory within a skill is not populated from MCP-provided content — only locally-created skills can have executable scripts.
User confirmation always required. No skill from an MCP server loads into the context without the user's awareness. Remote skills are flagged as remotely-sourced in the pipeline, and the first load of any new remote skill requires explicit confirmation. This prevents a compromised MCP server from silently injecting guidance that could influence the AI's behavior.
Append-only observation data. The .planning/patterns/ directory uses append-only JSONL files for observation data. While MCP servers can trigger observations (e.g., a tool call that results in a session event), they cannot modify or delete existing observations. Each entry is validated on read to detect tampering.
Cross-project isolation. User-level skills (~/.claude/skills/) must not expose project-specific patterns to other projects. The MCP distribution system enforces project boundaries: a skill created in project A and shared via MCP does not carry project A's observation data, feedback history, or learning state. Only the skill content and metadata are shared.
What's Next
- A-1: Chipset Architecture — The coprocessor model that MCP extends
- A-5: Extending the Pipeline — Other extension points in the system
- UG-4: Configuration — Configuring MCP servers and skill-creator settings