Build and Deploy Claude Skills and MCP Servers | The Complete 2026 Guide

Key Concepts

• MCP (Model Context Protocol): A standardized protocol for AI agents to interact with external tools and data.
• Adapters: Different interfaces (CLI, Local MCP, Remote MCP, Skills) that connect to a shared core logic.
• Shared Core: A centralized, environment-agnostic package containing business logic, schemas, and types.
• Monorepo: A project structure using bun workspaces to manage multiple packages (core, cli, local-mcp, remote-mcp) in one repository.
• Zod: A TypeScript-first schema declaration and validation library used to ensure type safety and provide clear error messages for AI agents.
• Skills: Agent instructions that allow AI to decide whether to use a CLI or an MCP server, often optimizing for token usage.
• Shebang (#!): A directive at the top of a script that tells the system to use node to execute the file.
• OAuth/Clerk: A framework for handling authentication and authorization, allowing secure access to remote MCP servers.

---

1. Architecture Overview

The project follows a "Shared Core, Multiple Adapters" architecture. This ensures that the core logic (e.g., sending a Telegram message) is written once and reused across:

• CLI: For direct human interaction.
• Local MCP: For coding agents running on the local machine (e.g., Claude Code, OpenCode).
• Remote MCP: For web-based AI assistants (e.g., ChatGPT, Claude.ai) via HTTP.
• Skills: A hybrid approach where agents are instructed on how to use the CLI or MCP based on availability and cost.

2. Step-by-Step Development Process

Phase 1: The Shared Core

• Purpose: Decouple business logic from the environment.
• Methodology: Use Zod to define schemas for inputs (chat ID, message) and outputs (API responses).
• Implementation: Create a core package that exports sendTelegramMessage. This function is agnostic of the environment (CLI vs. Server).

Phase 2: CLI Adapter

• Tooling: commander for command parsing.
• Configuration: Implemented a config.json stored in the user's home directory to handle API tokens securely, replacing hardcoded environment variables.
• Execution: Added a shebang (#!/usr/bin/env node) to make the CLI executable globally.

Phase 3: Local MCP Server

• Protocol: Uses stdio (Standard Input/Output) transport.
• Integration: Configured via mcp.json or open-code.json.
• Workflow: The agent discovers the tool via the MCP SDK, validates arguments using the shared Zod schema, and executes the core logic.

Phase 4: Remote MCP Server

• Tooling: Hono for the HTTP server.
• Deployment: Deployed to Railway.
• Authentication: Implemented Clerk for OAuth. This allows the server to verify the user's identity before allowing the agent to execute tools, preventing unauthorized access.

Phase 5: Skills & Distribution

• Skills: Created a skill.md file in a public GitHub repository.
• Distribution: Used npx skills add [repo-url] to install the skill.
• Logic: The skill instructs the agent to prefer the MCP server if connected, falling back to the CLI if the MCP is unavailable.

3. Key Arguments & Perspectives

• Type Safety for Agents: The author argues that strict validation (via Zod) is not just for developers but for AI agents. Providing clear, specific error messages reduces "hallucinations" and helps agents self-correct.
• Token Optimization: Skills are presented as a cost-effective alternative to MCPs, as they can be cheaper depending on the agent's reasoning process.
• Production Readiness: The author emphasizes using OXC (Oxidation Compiler) for linting/formatting and tsdown for bundling to ensure the code is industry-standard and distributable.

4. Notable Quotes

• "The question is no longer should I learn MCPs or should I learn skills. The question becomes how do I build a tool and make it work everywhere?"
• "The more accurately you can give [agents] errors, the better can they provide solutions."

5. Synthesis/Conclusion

Building AI tools in 2026 requires a modular approach. By centralizing logic in a shared core and using standardized protocols like MCP, developers can build once and deploy to any environment. The combination of CLI for manual tasks, MCP for agent-driven automation, and Skills for intelligent fallback creates a robust, production-ready architecture that is both scalable and maintainable.