mcp-builder

Stars11

Forks3

UpdatedMarch 18, 2026 at 12:40

Guide for building high-quality MCP (Model Context Protocol) servers and tool suites. Use this whenever the user asks to build, design, refactor, review, or evaluate an MCP server, expose an API through MCP, or improve tool naming, schemas, pagination, auth, or error handling.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

Threat-Vector-Security

Threat-Vector-Security/guardian-agent

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

2 files

SKILL.md

readonly

name	mcp-builder
description	Guide for building high-quality MCP (Model Context Protocol) servers and tool suites. Use this whenever the user asks to build, design, refactor, review, or evaluate an MCP server, expose an API through MCP, or improve tool naming, schemas, pagination, auth, or error handling.

MCP Builder

Build MCP servers so they are easy for agents to discover, reason about, and use safely.

Workflow

Understand the target API or system first.
Choose the transport intentionally.
Design the tool surface for agent discoverability, not just endpoint parity.
Implement shared auth, error handling, formatting, and pagination helpers before adding many tools.
Test the server with realistic multi-step prompts, not only unit tests.

Design Principles

Prefer clear verb-first or provider-prefixed tool names.
Make tool descriptions concrete and concise.
Use structured schemas with field constraints and examples.
Return structured data whenever the SDK supports it.
Keep read-only and mutating tools clearly separated.
Write actionable errors that tell the agent what to do next.

Implementation Guidance

Prefer TypeScript unless the repo already has a strong Python MCP pattern.
Start with the most common read-only tools, then add mutating operations.
Add pagination, filtering, and scoping so tools do not dump oversized payloads.
Model auth once in a shared client layer.
Use annotations and metadata that help approval and policy systems classify risk.

Review Checklist

Can an agent find the right tool from the name alone?
Are input and output schemas specific enough to prevent ambiguous calls?
Do error messages explain the likely fix?
Are mutating tools obviously distinct from inspection tools?
Can common user tasks be solved without custom scripting around the server?

Read references/mcp-server-checklist.md when you need a compact implementation checklist.

Gotchas

Do not mirror raw endpoint naming when it makes tool discovery worse for agents.
Do not expose large unfiltered list endpoints without pagination, filters, or scoping.
Do not mix read-only and mutating behavior behind one ambiguous tool.

More from this repository

same repository

skill-creator

Threat-Vector-Security/guardian-agent

Guide for creating new skills, improving existing skills, and evaluating skill quality. Use this whenever the user wants to turn a workflow into a skill, revise a skill, improve triggering behavior, or add evals and benchmarks for a skill.

2026-04-1911

code-review

Threat-Vector-Security/guardian-agent

Use when reviewing a diff, PR, or patch for bugs, regressions, missing tests, architecture risk, security risk, or reviewability concerns before merge.

2026-04-1311

context-engineering

Threat-Vector-Security/guardian-agent

Use when starting a repo-grounded task, switching subsystems, or when output quality drops and the agent needs tighter project context from rules, specs, relevant files, examples, and current errors.

2026-04-1311

source-driven-development

Threat-Vector-Security/guardian-agent

Use when implementing or reviewing framework-specific code that should be verified against current official docs, versioned guidance, or source-cited examples rather than memory.

2026-04-1311

coding-backend-orchestration

Threat-Vector-Security/guardian-agent

Use when the user explicitly asks Guardian to launch or check an external coding assistant such as Codex, Claude Code, Gemini CLI, or Aider.

2026-04-1111

coding-workspace

Threat-Vector-Security/guardian-agent

Use when the request is about a repo, codebase, implementation, bugfix, or backend-owned coding session that should stay anchored to the active workspace.

2026-04-1111

name	mcp-builder
description	Guide for building high-quality MCP (Model Context Protocol) servers and tool suites. Use this whenever the user asks to build, design, refactor, review, or evaluate an MCP server, expose an API through MCP, or improve tool naming, schemas, pagination, auth, or error handling.

MCP Builder

Build MCP servers so they are easy for agents to discover, reason about, and use safely.

Workflow

Understand the target API or system first.
Choose the transport intentionally.
Design the tool surface for agent discoverability, not just endpoint parity.
Implement shared auth, error handling, formatting, and pagination helpers before adding many tools.
Test the server with realistic multi-step prompts, not only unit tests.

Design Principles

Prefer clear verb-first or provider-prefixed tool names.
Make tool descriptions concrete and concise.
Use structured schemas with field constraints and examples.
Return structured data whenever the SDK supports it.
Keep read-only and mutating tools clearly separated.
Write actionable errors that tell the agent what to do next.

Implementation Guidance

Prefer TypeScript unless the repo already has a strong Python MCP pattern.
Start with the most common read-only tools, then add mutating operations.
Add pagination, filtering, and scoping so tools do not dump oversized payloads.
Model auth once in a shared client layer.
Use annotations and metadata that help approval and policy systems classify risk.

Review Checklist

Can an agent find the right tool from the name alone?
Are input and output schemas specific enough to prevent ambiguous calls?
Do error messages explain the likely fix?
Are mutating tools obviously distinct from inspection tools?
Can common user tasks be solved without custom scripting around the server?

Read references/mcp-server-checklist.md when you need a compact implementation checklist.

Gotchas

Do not mirror raw endpoint naming when it makes tool discovery worse for agents.
Do not expose large unfiltered list endpoints without pagination, filters, or scoping.
Do not mix read-only and mutating behavior behind one ambiguous tool.