Skills Guide

MCP Server Builder

VerifiedSafe

Covers principles for building MCP (Model Context Protocol) servers, including tool design, resource patterns, error handling, security, and configuration. Helps developers create well-structured, secure, and testable MCP servers for AI tool integration.

Download and use
Sby Skills Guide Bot
DevelopmentIntermediate
6/2/2026
Claude Code
#mcp#model-context-protocol#server-architecture#tool-design#ai-integration

Recommended for

Backend developerClaude CodeCode reviewFrontend developerFullstack developerRefactoring

Automated summary

This guide covers principles for designing and building MCP (Model Context Protocol) servers to connect AI assistants with external tools and data sources.

Strengths

  • Comprehensive coverage of server architecture, transports, and tool design.
  • Concrete examples of input schemas and error handling.
  • Easy-to-follow best practices checklist.

Limitations

  • Does not delve into advanced server scenarios (authentication, scaling).
  • Lacks full code examples for each transport type.
  • Focuses on server-side, not client-side MCP usage.
When to use it

Best for starting a new MCP server or refactoring an existing one with sound practices.

When not to use it

Avoid if you need step-by-step tutorials for specific integrations (e.g., Slack, databases).

Security analysis

Safe
Quality score90/100

The skill contains only educational documentation on building MCP servers; no dangerous commands or actions are instructed.

No concerns found

How this analysis is made

Examples

Create an MCP server with a weather tool
Create a new MCP server project with a tool that returns current weather for a given city. Use TypeScript, stdio transport, and proper input validation. Include README and package.json.
Add a resource to an existing MCP server
Add a resource that provides user profile data given a user ID. Use URI pattern users://{userId} and return structured JSON.
Debug MCP server tool errors
I have an MCP server that returns an internal error when calling my tool. Help me implement proper error handling: validate inputs, return structured errors, and log details without exposing internals.

name: mcp-builder description: Princípios de construção de servidores MCP (Model Context Protocol). Design de ferramentas, padrões de recursos e melhores práticas. allowed-tools: Read, Write, Edit, Glob, Grep

Construtor de MCP

Princípios para construção de servidores MCP.

1. Visão Geral do MCP

O que é MCP?

Model Context Protocol - um padrão para conectar sistemas de IA com ferramentas externas e fontes de dados.

Conceitos Centrais

| Conceito | Propósito | | :--- | :--- | | Ferramentas (Tools) | Funções que a IA pode chamar | | Recursos (Resources) | Dados que a IA pode ler | | Prompts | Templates de prompt pré-definidos |

2. Arquitetura do Servidor

Estrutura do Projeto

meu-servidor-mcp/
├── src/
│   └── index.ts      # Entrada principal
├── package.json
└── tsconfig.json

Tipos de Transporte

| Tipo | Uso | | :--- | :--- | | Stdio | Local, baseado em CLI | | SSE | Baseado na web, streaming | | WebSocket | Tempo real, bidirecional |

3. Princípios de Design de Ferramentas

Bom Design de Ferramenta

| Princípio | Descrição | | :--- | :--- | | Nome claro | Orientado à ação (get_weather, create_user) | | Propósito único | Faz uma coisa bem feita | | Entrada validada | Schema com tipos e descrições | | Saída estruturada | Formato de resposta previsível |

Design de Schema de Entrada

| Campo | Obrigatório? | | :--- | :--- | | Tipo (Type) | Sim - object | | Propriedades | Define cada parâmetro | | Obrigatório | Lista parâmetros mandatórios | | Descrição | Legível para humanos |

4. Padrões de Recursos

Tipos de Recurso

| Tipo | Uso | | :--- | :--- | | Estático | Dados fixos (config, docs) | | Dinâmico | Gerado sob demanda | | Template | URI com parâmetros |

Padrões de URI

| Padrão | Exemplo | | :--- | :--- | | Fixo | docs://readme | | Parametrizado | users://{userId} | | Coleção | files://projeto/* |

5. Tratamento de Erros

Tipos de Erro

| Situação | Resposta | | :--- | :--- | | Parâmetros inválidos | Mensagem de erro de validação | | Não encontrado | Mensagem clara de "não encontrado" | | Erro do servidor | Erro genérico, logar detalhes |

Melhores Práticas

  • Retorne erros estruturados.
  • Não exponha detalhes internos.
  • Logue para fins de depuração.
  • Forneça mensagens acionáveis.

6. Tratamento Multimodal

Tipos Suportados

| Tipo | Codificação | | :--- | :--- | | Texto | Texto simples (Plain text) | | Imagens | Base64 + tipo MIME | | Arquivos | Base64 + tipo MIME |

7. Princípios de Segurança

Validação de Entrada

  • Valide todas as entradas de ferramentas.
  • Higienize (sanitize) os dados fornecidos pelo usuário.
  • Limite o acesso aos recursos.

Chaves de API

  • Use variáveis de ambiente.
  • Não logue segredos.
  • Valide permissões.

8. Configuração

Configuração do Claude Desktop

| Campo | Propósito | | :--- | :--- | | command | Executável a ser rodado | | args | Argumentos do comando | | env | Variáveis de ambiente |

9. Testes

Categorias de Teste

| Tipo | Foco | | :--- | :--- | | Unitário | Lógica da ferramenta | | Integração | Servidor completo | | Contrato | Validação de schema |

10. Checklist de Melhores Práticas

  • [ ] Nomes de ferramentas claros e orientados à ação.
  • [ ] Schemas de entrada completos com descrições.
  • [ ] Saída JSON estruturada.
  • [ ] Tratamento de erros para todos os casos.
  • [ ] Validação de entradas.
  • [ ] Configuração baseada em ambiente.
  • [ ] Logging para depuração.

Lembre-se: As ferramentas MCP devem ser simples, focadas e bem documentadas. A IA depende das descrições para usá-las corretamente.

From the file to a first result

The download contains exactly the content displayed on this page. This copy may differ from the latest version in the source repository.

View the source and supporting files

This download contains SKILL.md only. Any scripts, references, templates and dependencies are not included. Get the required files from the source, preserving their directory structure, before continuing.

1. Download the file

Download SKILL.md

From the root of a test project, save the file as .skill-downloads/mcp-server-builder-mm5t8ben/SKILL.md, or use the command below. This folder is for inspecting the skill before installation.

Command for macOS/Linux or WSL: requires a POSIX shell and curl. On Windows without WSL, use the download button and create the folder manually.

mkdir -p '.skill-downloads/mcp-server-builder-mm5t8ben' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/mcp-server-builder-mm5t8ben/download' --output '.skill-downloads/mcp-server-builder-mm5t8ben/SKILL.md.part' && mv '.skill-downloads/mcp-server-builder-mm5t8ben/SKILL.md.part' '.skill-downloads/mcp-server-builder-mm5t8ben/SKILL.md'

2. Check prerequisites

Read SKILL.md before using it. If it references scripts or external services, inspect them and prepare the required access in your test environment.

Tools declared by the author (check availability in your agent): Read, Write, Edit, Glob, Grep

No recognized prerequisites section in this file. This does not mean it is self-contained: libraries, tools and access requirements may be mentioned elsewhere in the content or source repository.

The platforms on this page are catalog indications. The paths below follow tool documentation; they do not prove this skill has been run in those tools. No minimum tool version is confirmed for this listing.

3. Load the skill

After inspection, copy the complete folder into your project using one of the commands below, then open a new tool session. The command stops if a folder with the same name already exists: compare the files before replacing it.

Claude Code
test -f '.skill-downloads/mcp-server-builder-mm5t8ben/SKILL.md' && test -s '.skill-downloads/mcp-server-builder-mm5t8ben/SKILL.md' && mkdir -p '.claude/skills' && test ! -e '.claude/skills/mcp-builder' && cp -R '.skill-downloads/mcp-server-builder-mm5t8ben' '.claude/skills/mcp-builder'

OpenSkills

OpenSkills must already be installed. The local install/read procedure is checked with OpenSkills 1.5.0, which requires Node.js ≥ 20.6.0. Catalog slugs are not resolved automatically.

Official OpenSkills installation
openskills install './.skill-downloads/mcp-server-builder-mm5t8ben'

openskills read 'mcp-server-builder-mm5t8ben'

Reading should display the installed file content and its base directory. It does not run the skill or install its dependencies.

For an agent that reads AGENTS.md, then sync the index. This command changes AGENTS.md: review the diff before using it.

openskills sync

Manual method or another tool: attach SKILL.md to a conversation, or open it in an agent that can read files. Include any required supporting resources. No universal folder is recognized by every tool.

4. Try a first task

Use a short, synthetic input: an API endpoint, a small document or an interface brief. In a new conversation, attach the file or give the agent its path, then adapt this request:

Read .skill-downloads/mcp-server-builder-mm5t8ben/SKILL.md and apply its instructions to this example: [describe a test input]. Identify any missing files, dependencies or access. Produce the result requested by the skill without inventing data or running unreviewed scripts.

Expected result: output matching the skill instructions, or a precise list of missing prerequisites. A read confirmation alone does not validate a first use. If an external resource is unavailable, that path remains untested.

Related skills

React Hook Form Best Practices

Development

Master React Hook Form: avoid anti-patterns, manage subscriptions, and handle reset, dirty state, and controlled inputs correctly.

Claude CodeCursorWindsurf+2intermediateSafe 108,623
Skills Guide Bot

Emotion to Mantine Migration

Development

Migrate Emotion styled-components to Mantine components with style props and CSS modules. Use when converting .styled.tsx files or removing @emotion imports.

Claude CodeCursorWindsurf+1intermediateSafe 48,981
Skills Guide Bot

Scope Creep Detector

Development

Analyzes git diffs against a stated intent to detect scope creep, unrelated files, broad PRs, and oversized changes, then suggests keep, split, or justify actions.

Claude CodeCursorCodexintermediateSafe 135,015
Skills Guide Bot