Agent skill

MCP Server Builder

by shareAI-lab in shareAI-lab/Kode-CLI

Guide to designing and building MCP servers: tool, resource and prompt design for agent usability, with TypeScript or Python implementation workflows.

Apache-2.0Auto-check passedAgent Workflows

Install MCP Server Builder

skills CLI
$ npx skills add shareAI-lab/Kode-CLI --skill mcp-builder -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install shareAI-lab/Kode-CLI mcp-builder --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/shareAI-lab/Kode-CLI.git skills-src && mkdir -p .claude/skills && cp -r skills-src/packages/builtin-skills/skills/mcp-builder .claude/skills/mcp-builder && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
mcp-builder
GitHub stars
5.2k
Token cost
~1.9k tokens
SKILL.md length
762 words
Files
5
Skills in repo
8
Repo updated
First seen
Licence
Apache-2.0

At a glance

Guide to designing and building MCP servers: tool, resource and prompt design for agent usability, with TypeScript or Python implementation workflows.

  • Works in 3 steps: Deep Research and Planning → Implementation → Review and Test
  • Designing the tools of a new MCP server for an external service
  • SKILL.md covers Overview, 🚀 High-Level Workflow and 📚 Documentation Library
  • Reaches raw.githubusercontent.com and modelcontextprotocol.io

What it does

An MCP server is judged by how well it lets an LLM finish real tasks through well-designed tools. The agent first asks once for the target SDK, TypeScript, Python or another official one, and for the language of the walkthrough, English or Chinese. Phase one is research and planning: balance full API coverage against specialized workflow tools, preferring coverage when unsure, use consistent action-oriented tool names with prefixes, keep descriptions concise with filtering and pagination, and write error messages that suggest next steps.

The agent is also told to study the MCP specification, starting from its sitemap and fetching pages as markdown, covering the architecture, transports such as streamable HTTP and stdio, and tool, resource and prompt definitions. TypeScript is the recommended stack. Reference files cover MCP best practices, Node servers and Python servers. The excerpt ends in the first phase, so later phases are not described here.

When your agent uses it

  • Designing the tools of a new MCP server for an external service
  • Choosing between TypeScript and Python for an MCP server
  • Reviewing tool names, error messages and pagination for agent usability

Example prompts

  • “Build an MCP server for our internal ticketing API in TypeScript.”
  • “Review the tool names and error messages in my Python MCP server for agent usability.”
  • “Plan which of our REST endpoints become MCP tools and which become higher-level workflow tools.”

Requirements

  • A TypeScript or Python MCP SDK, chosen when the build starts

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. Deep Research and Planning
  2. Implementation
  3. Review and Test

What it can do on your machine

Read from SKILL.md and the folder at commit c7f6fcc. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • raw.githubusercontent.com
    • modelcontextprotocol.io

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

MCP Server Builder loads about 1.9k tokens when it runs. Until then it costs about 87 tokens; SKILL.md has 762 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~87
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from shareAI-lab/Kode-CLI at commit c7f6fcc, republished under its Apache-2.0 licence (© shareAI-lab). 762 words, ~1,861 tokens.

Download SKILL.mdSave it as .claude/skills/mcp-builder/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.
name
mcp-builder
description
Guide for building high-quality MCP (Model Context Protocol) servers and tools: what MCP is, how to design tools/resources/prompts for agent usability, and how to implement servers in TypeScript or Python. Use when you need MCP best practices, server architecture patterns, or a step-by-step build workflow (with language preference).
license
Complete terms in LICENSE.txt

MCP Server Development Guide

Overview

Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.


Process

🚀 High-Level Workflow

Creating a high-quality MCP server involves three main phases:

Before starting, confirm two preferences (ask once):

  • Target implementation language/SDK (TypeScript SDK, Python SDK, or another official MCP SDK)
  • Preferred language for the build walkthrough (English / 中文)
Phase 1: Deep Research and Planning
1.1 Understand Modern MCP Design

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools can be more convenient for specific tasks, while comprehensive coverage gives agents flexibility to compose operations. Performance varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level workflows. When uncertain, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes (e.g., github_create_issue, github_list_repos) and action-oriented naming.

Context Management: Agents benefit from concise tool descriptions and the ability to filter/paginate results. Design tools that return focused, relevant data. Some clients support code execution which can help agents filter and process data efficiently.

Actionable Error Messages: Error messages should guide agents toward solutions with specific suggestions and next steps.

1.2 Study MCP Protocol Documentation

Navigate the MCP specification:

Start with the sitemap to find relevant pages: https://modelcontextprotocol.io/sitemap.xml

Then fetch specific pages with .md suffix for markdown format (e.g., https://modelcontextprotocol.io/specification/draft.md).

Key pages to review:

  • Specification overview and architecture
  • Transport mechanisms (streamable HTTP, stdio)
  • Tool, resource, and prompt definitions
1.3 Study Framework Documentation

Recommended stack:

  • Language: TypeScript (high-quality SDK support and good compatibility in many execution environments e.g. MCPB. Plus AI models are good at generating TypeScript code, benefiting from its broad usage, static typing and good linting tools)
  • Transport: Streamable HTTP for remote servers, using stateless JSON (simpler to scale and maintain, as opposed to stateful sessions and streaming responses). stdio for local servers.

Load framework documentation:

For TypeScript (recommended):

  • TypeScript SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
  • ⚡ TypeScript Guide - TypeScript patterns and examples

For Python:

  • Python SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • 🐍 Python Guide - Python patterns and examples
1.4 Plan Your Implementation

Understand the API: Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.

Tool Selection: Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.


Phase 2: Implementation
2.1 Set Up Project Structure

See language-specific guides for project setup:

Show full SKILL.md (314 more words)Show less
2.2 Implement Core Infrastructure

Create shared utilities:

  • API client with authentication
  • Error handling helpers
  • Response formatting (JSON/Markdown)
  • Pagination support
2.3 Implement Tools

For each tool:

Input Schema:

  • Use Zod (TypeScript) or Pydantic (Python)
  • Include constraints and clear descriptions
  • Add examples in field descriptions

Output Schema:

  • Define outputSchema where possible for structured data
  • Use structuredContent in tool responses (TypeScript SDK feature)
  • Helps clients understand and process tool outputs

Tool Description:

  • Concise summary of functionality
  • Parameter descriptions
  • Return type schema

Implementation:

  • Async/await for I/O operations
  • Proper error handling with actionable messages
  • Support pagination where applicable
  • Return both text content and structured data when using modern SDKs

Annotations:

  • readOnlyHint: true/false
  • destructiveHint: true/false
  • idempotentHint: true/false
  • openWorldHint: true/false

Phase 3: Review and Test
3.1 Code Quality

Review for:

  • No duplicated code (DRY principle)
  • Consistent error handling
  • Full type coverage
  • Clear tool descriptions
3.2 Build and Test

Verification is client- and environment-specific. Focus on correctness and agent usability:

  • Ensure tools/resources/prompts are discoverable, well-described, and return constrained outputs.
  • Sanity-check the server using whatever MCP client/inspector/runtime you are targeting (stdio or streamable HTTP).
  • Prefer small, repeatable smoke checks over a complex “environment validation” checklist.

Reference Files

📚 Documentation Library

Load these resources as needed during development:

Core MCP Documentation (Load First)
  • MCP Protocol: Start with sitemap at https://modelcontextprotocol.io/sitemap.xml, then fetch specific pages with .md suffix
  • 📋 MCP Best Practices - Universal MCP guidelines including:
    • Server and tool naming conventions
    • Response format guidelines (JSON vs Markdown)
    • Pagination best practices
    • Transport selection (streamable HTTP vs stdio)
    • Security and error handling standards
SDK Documentation (Load During Phase 1/2)
  • Python SDK: Fetch from https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • TypeScript SDK: Fetch from https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Language-Specific Implementation Guides (Load During Phase 2)
  • 🐍 Python Implementation Guide - Complete Python/FastMCP guide with:

    • Server initialization patterns
    • Pydantic model examples
    • Tool registration with @mcp.tool
    • Complete working examples
    • Quality checklist
  • ⚡ TypeScript Implementation Guide - Complete TypeScript guide with:

    • Project structure
    • Zod schema patterns
    • Tool registration with server.registerTool
    • Complete working examples
    • Quality checklist

© shareAI-lab, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files in packages/builtin-skills/skills/mcp-builder of shareAI-lab/Kode-CLI.

  • SKILL.md
  • LICENSE.txt
  • reference/mcp_best_practices.md
  • reference/node_mcp_server.md
  • reference/python_mcp_server.md

Open the folder on GitHubat commit c7f6fcc

Compare with similar skills

MCP Server Builder next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

MCP Server Builder compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
MCP Server Builder this skillshareAI-lab/Kode-CLI5.2k—~1.9kAutomated safety check: PassApache-2.0
MCP Server Builderanthropics/skills180k64 repos~2.3kAutomated safety check: PassApache-2.0
MCP Server BuildershareAI-lab/learn-claude-code78k5 repos~1.2kAutomated safety check: PassMIT
MCP Server Builderalirezarezvani/claude-skills28k—~985Automated safety check: PassMIT
Copilot SDKintellectronica/agent-skills295—~3.2kAutomated safety check: PassCC0-1.0
Copilot SDKmicrosoft/skills3.1k—~7.1kAutomated safety check: PassMIT

Similar skills

  • MCP Server Builder

    anthropics/skills

    Official

    Guides the design and implementation of Model Context Protocol servers in TypeScript or Python, from tool naming and error messages to evaluation.

    180k GitHub starsUsed in 64 repos~2.3k tokens
    Agent WorkflowsAuto-check passed
  • MCP Server Builder

    shareAI-lab/learn-claude-code

    Walks through building MCP servers in Python or TypeScript that expose tools, resources and prompts to Claude, with templates, registration and testing.

    78k GitHub starsUsed in 5 repos~1.2k tokens
    Agent WorkflowsAuto-check passed
  • MCP Server Builder

    alirezarezvani/claude-skills

    Design and ship production-ready MCP (Model Context Protocol) servers from OpenAPI contracts instead of hand-written tool wrappers.

    28k GitHub stars~985 tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed
  • Copilot SDK

    intellectronica/agent-skills

    This skill helps with GitHub Copilot SDK work across Node.js/TypeScript, Python, Go, .NET, and Java.

    295 GitHub stars~3.2k tokensUpdated 5 mo ago
    Agent WorkflowsAuto-check passed
  • Copilot SDK

    microsoft/skills

    Official

    Build applications powered by GitHub Copilot using the Copilot SDK.

    3.1k GitHub stars~7.1k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed
  • Create MCP Servers

    glittercowboy/taches-cc-resources

    Create Model Context Protocol (MCP) servers that expose tools, resources, and prompts to Claude.

    2k GitHub stars~1.5k tokensUpdated 6 mo ago
    Agent WorkflowsAuto-check passed

More from shareAI-lab/Kode-CLI

All 8 skills in this repo
  • Skill Creator

    shareAI-lab/Kode-CLI

    Guides writing a new agent skill or improving an existing one, covering how to keep it concise, how much freedom to give the agent and how to lay out bundled resources.

    5.2k GitHub starsUsed in 1 repo~4.4k tokens
    Auto-check passed
  • Skill Judge

    shareAI-lab/Kode-CLI

    Evaluates the design quality of an agent skill against official specifications and patterns from existing examples, scoring it and suggesting improvements.

    5.2k GitHub starsUsed in 4 repos~7.5k tokens
    Auto-check passed
  • Vibe Coding Partner

    shareAI-lab/Kode-CLI

    Gives an agent a set of working rules for any development task: understand first, surface decisions, verify results, and load deeper reference files per scenario.

    5.2k GitHub stars~5.6k tokensUpdated 1 mo ago
    Auto-check passed
  • Doc Co-Authoring Workflow

    shareAI-lab/Kode-CLI

    Guides a three-stage workflow for turning partial context into a clear PRD, RFC or design doc: capture context, draft section by section, then test with a fresh reader.

    5.2k GitHub stars~977 tokensUpdated 1 mo ago
    Auto-check passed
  • Kode Capabilities Manager

    shareAI-lab/Kode-CLI

    Lets the Kode agent manage its own features, such as LSP, statusline, output styles and plugins, by running its slash commands for you instead of listing install steps.

    5.2k GitHub stars~760 tokensUpdated 1 mo ago
    Auto-check passed
  • Kode LSP Maintenance

    shareAI-lab/Kode-CLI

    Diagnoses why Kode's LSP tool returns nothing and fixes it through plugin .lsp.json files and slash commands, then verifies with a real LSP call.

    5.2k GitHub stars~573 tokensUpdated 1 mo ago
    Auto-check passed

Questions about MCP Server Builder

What does MCP Server Builder do?

Guide to designing and building MCP servers: tool, resource and prompt design for agent usability, with TypeScript or Python implementation workflows. An MCP server is judged by how well it lets an LLM finish real tasks through well-designed tools. The agent first asks once for the target SDK, TypeScript, Python or another official one, and for the language of the walkthrough, English or Chinese.

When should I use MCP Server Builder?

MCP Server Builder fits situations like: designing the tools of a new MCP server for an external service; choosing between TypeScript and Python for an MCP server; reviewing tool names, error messages and pagination for agent usability.

How do I install MCP Server Builder in Claude Code?

Run `npx skills add shareAI-lab/Kode-CLI --skill mcp-builder -a claude-code`. Or copy the skill folder (packages/builtin-skills/skills/mcp-builder in shareAI-lab/Kode-CLI) into .claude/skills/mcp-builder in your project. Claude Code loads it when a task matches its description.

How do I install MCP Server Builder in Codex?

Run `npx skills add shareAI-lab/Kode-CLI --skill mcp-builder -a codex`. Or copy the skill folder (packages/builtin-skills/skills/mcp-builder in shareAI-lab/Kode-CLI) into .agents/skills/mcp-builder in your project. Codex loads it when a task matches its description.

Can I use MCP Server Builder in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add shareAI-lab/Kode-CLI --skill mcp-builder -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/mcp-builder, .gemini/skills/mcp-builder, .github/skills/mcp-builder and .opencode/skills/mcp-builder in your project.

What does MCP Server Builder need to run?

SKILL.md names no scripts, command-line tools or credentials: MCP Server Builder is instructions for the agent only. Our summary lists: A TypeScript or Python MCP SDK, chosen when the build starts.

Does MCP Server Builder access the network?

SKILL.md names 2 domains. In commands or code: raw.githubusercontent.com and modelcontextprotocol.io; the agent is likely to contact these when it follows the instructions. This is read from the text; nothing was executed.

Is MCP Server Builder safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does MCP Server Builder use?

MCP Server Builder is published under the Apache-2.0 licence (from the LICENSE file in the skill folder). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does MCP Server Builder use?

About 1.9k tokens (SKILL.md is roughly 7.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to MCP Server Builder?

Skills that share tags, products or a category with MCP Server Builder: MCP Server Builder (anthropics/skills, 180k stars), MCP Server Builder (shareAI-lab/learn-claude-code, 78k stars), MCP Server Builder (alirezarezvani/claude-skills, 28k stars) and Copilot SDK (intellectronica/agent-skills, 295 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains MCP Server Builder?

shareAI-lab (a GitHub organization) maintains it in shareAI-lab/Kode-CLI, which has 5,232 GitHub stars. The repository holds 8 skills in this directory. The repository was last updated on August 27, 2026.

Source: shareAI-lab/Kode-CLI on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.