playbooks

home / skills / vudovn / antigravity-kit / mcp-builder

mcp-builder skill

/.agent/skills/mcp-builder

This skill helps you design MCP servers with clear tool names, structured outputs, and robust error handling for scalable AI integrations.

npx playbooks add skill vudovn/antigravity-kit --skill mcp-builder

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.2 KB
---
name: mcp-builder
description: MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.
allowed-tools: Read, Write, Edit, Glob, Grep
---

# MCP Builder

> Principles for building MCP servers.

---

## 1. MCP Overview

### What is MCP?

Model Context Protocol - standard for connecting AI systems with external tools and data sources.

### Core Concepts

| Concept | Purpose |
|---------|---------|
| **Tools** | Functions AI can call |
| **Resources** | Data AI can read |
| **Prompts** | Pre-defined prompt templates |

---

## 2. Server Architecture

### Project Structure

```
my-mcp-server/
├── src/
│   └── index.ts      # Main entry
├── package.json
└── tsconfig.json
```

### Transport Types

| Type | Use |
|------|-----|
| **Stdio** | Local, CLI-based |
| **SSE** | Web-based, streaming |
| **WebSocket** | Real-time, bidirectional |

---

## 3. Tool Design Principles

### Good Tool Design

| Principle | Description |
|-----------|-------------|
| Clear name | Action-oriented (get_weather, create_user) |
| Single purpose | One thing well |
| Validated input | Schema with types and descriptions |
| Structured output | Predictable response format |

### Input Schema Design

| Field | Required? |
|-------|-----------|
| Type | Yes - object |
| Properties | Define each param |
| Required | List mandatory params |
| Description | Human-readable |

---

## 4. Resource Patterns

### Resource Types

| Type | Use |
|------|-----|
| Static | Fixed data (config, docs) |
| Dynamic | Generated on request |
| Template | URI with parameters |

### URI Patterns

| Pattern | Example |
|---------|---------|
| Fixed | `docs://readme` |
| Parameterized | `users://{userId}` |
| Collection | `files://project/*` |

---

## 5. Error Handling

### Error Types

| Situation | Response |
|-----------|----------|
| Invalid params | Validation error message |
| Not found | Clear "not found" |
| Server error | Generic error, log details |

### Best Practices

- Return structured errors
- Don't expose internal details
- Log for debugging
- Provide actionable messages

---

## 6. Multimodal Handling

### Supported Types

| Type | Encoding |
|------|----------|
| Text | Plain text |
| Images | Base64 + MIME type |
| Files | Base64 + MIME type |

---

## 7. Security Principles

### Input Validation

- Validate all tool inputs
- Sanitize user-provided data
- Limit resource access

### API Keys

- Use environment variables
- Don't log secrets
- Validate permissions

---

## 8. Configuration

### Claude Desktop Config

| Field | Purpose |
|-------|---------|
| command | Executable to run |
| args | Command arguments |
| env | Environment variables |

---

## 9. Testing

### Test Categories

| Type | Focus |
|------|-------|
| Unit | Tool logic |
| Integration | Full server |
| Contract | Schema validation |

---

## 10. Best Practices Checklist

- [ ] Clear, action-oriented tool names
- [ ] Complete input schemas with descriptions
- [ ] Structured JSON output
- [ ] Error handling for all cases
- [ ] Input validation
- [ ] Environment-based configuration
- [ ] Logging for debugging

---

> **Remember:** MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.

Overview

This skill explains principles for building MCP (Model Context Protocol) servers, focusing on tool design, resource patterns, error handling, security, and testing. It condenses architecture guidance and practical patterns for TypeScript-based MCP servers. The guidance emphasizes clarity, schema-driven inputs, and predictable outputs to make tools reliably usable by AI systems.

How this skill works

The skill inspects core MCP concepts: tools (callable functions), resources (readable data URIs), and prompts (templates). It lays out server transport options (stdio, SSE, WebSocket), recommended project layout, input/output schema conventions, and resource URI patterns. It also covers error handling, multimodal payload encoding, configuration, security measures, and testing strategies.

When to use it

  • Designing a new MCP server or refactoring an existing one
  • Defining tools and input/output schemas for AI integrations
  • Choosing transport and resource URI patterns for clients
  • Implementing secure input validation and secret handling
  • Establishing testing and contract validation for MCP endpoints

Best practices

  • Name tools with clear, action-oriented verbs and give each tool one focused responsibility
  • Define complete input schemas: types, required fields, and human descriptions
  • Return structured, predictable JSON outputs and document response shape
  • Validate and sanitize all inputs; never log secrets or internal details
  • Use environment variables for sensitive config and limit resource access by permissions
  • Log actionable errors for debugging and return safe, user-facing messages

Example use cases

  • Create a get_weather tool with a validated location schema and structured forecast output
  • Serve project documents via URIs like docs://readme and parameterized URIs like users://{userId}
  • Stream model responses to web clients over SSE or support interactive sessions over WebSocket
  • Expose image and file resources as Base64 with MIME type metadata for multimodal tools
  • Run unit, integration, and contract tests to ensure schemas and transports behave as expected

FAQ

What transport should I choose for local CLI vs web clients?

Use stdio for local CLI tools, SSE for one-way streaming to web clients, and WebSocket for real-time bidirectional interactions.

How should I structure errors returned to the model?

Return structured error objects with type, message, and actionable details; log full diagnostics internally but avoid leaking sensitive internals.

How do I encode images and files for MCP?

Encode binary payloads as Base64 and include the MIME type and optional filename in the resource metadata.