mcp-builder

MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.

Quality

57%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/mcp-builder/SKILL.md

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 — McpServer from @modelcontextprotocol/sdk
├── package.json      # dep: @modelcontextprotocol/sdk
└── tsconfig.json

TypeScript SDK: @modelcontextprotocol/sdk (McpServer). Python SDK: mcp (pip install "mcp[cli]", FastMCP bundled in mcp.server.fastmcp).

Transport Types

Type	Use
stdio	Local, CLI-based
Streamable HTTP	Remote/web servers (replaced the deprecated HTTP+SSE transport)

The current spec (2025-06-18) defines two standard transports: stdio and Streamable HTTP. WebSocket is not a standard transport. Validate the Origin header on Streamable HTTP servers.

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

Client Config (Claude Desktop, Claude Code, IDEs)

Field	Purpose
command	Executable to run (stdio servers)
args	Command arguments
env	Environment variables

MCP is multi-client — the same server works across Claude Desktop, Claude Code, and IDE hosts. Remote (Streamable HTTP) servers authenticate via OAuth rather than a local command.

9. Current Spec Features

Worth using in modern servers (spec 2025-06-18):

Feature	Purpose
Tool annotations	Hint read-only/destructive behavior to the client
Structured content / `outputSchema`	Typed, predictable tool results
Resource links	Return references to resources from tool results
OAuth	Auth for remote/Streamable HTTP servers

10. Testing

Test Categories

Type	Focus
Unit	Tool logic
Integration	Full server
Contract	Schema validation

11. Best Practices Checklist

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

Repository: vudovn/ag-kit
Path: .agents/skills/mcp-builder/SKILL.md
Commit: 04514f0

Last updated: about 11 hours ago
First committed: 11 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.