agentleFS
Sign inStart free
xenitV1xenitV1/Antigravity-Workflows/skills/mcp-builder/SKILL.md

mcp-builder

Skill130 starsChanged 10 months agoMITView on GitHub

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

We split this skill into the rules it gives an agent

2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 175 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Don't expose internal details

    line 106
  2. Distinctive:

    Don't log secrets

    line 135

“Common” is measured: kept by at least 6 in 10 of the 175 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
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

ConceptPurpose
ToolsFunctions AI can call
ResourcesData AI can read
PromptsPre-defined prompt templates

2. Server Architecture

Project Structure

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

Transport Types

TypeUse
StdioLocal, CLI-based
SSEWeb-based, streaming
WebSocketReal-time, bidirectional

3. Tool Design Principles

Good Tool Design

PrincipleDescription
Clear nameAction-oriented (get_weather, create_user)
Single purposeOne thing well
Validated inputSchema with types and descriptions
Structured outputPredictable response format

Input Schema Design

FieldRequired?
TypeYes - object
PropertiesDefine each param
RequiredList mandatory params
DescriptionHuman-readable

4. Resource Patterns

Resource Types

TypeUse
StaticFixed data (config, docs)
DynamicGenerated on request
TemplateURI with parameters

URI Patterns

PatternExample
Fixeddocs://readme
Parameterizedusers://{userId}
Collectionfiles://project/*

5. Error Handling

Error Types

SituationResponse
Invalid paramsValidation error message
Not foundClear "not found"
Server errorGeneric error, log details

Best Practices

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

6. Multimodal Handling

Supported Types

TypeEncoding
TextPlain text
ImagesBase64 + MIME type
FilesBase64 + 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

FieldPurpose
commandExecutable to run
argsCommand arguments
envEnvironment variables

9. Testing

Test Categories

TypeFocus
UnitTool logic
IntegrationFull server
ContractSchema 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free