mcp-server-design

Stars0

Forks0

UpdatedJuly 11, 2026 at 03:53

Design and implement an MCP server's tools, resources, and prompts with safe transport and input validation. Use when building or extending a Model Context Protocol server for agent integration.

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

synthet

synthet/project-twelve

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	mcp-server-design
description	Design and implement an MCP server's tools, resources, and prompts with safe transport and input validation. Use when building or extending a Model Context Protocol server for agent integration.

MCP server design

Use this skill when

Creating or extending an MCP server that exposes this project to AI agents
Adding tools, resources, or prompts
Configuring .cursor/mcp.example.json / .mcp.json

Procedure

Read the MCP specification and your SDK's docs.
Pick a clear, stable server name and a tool-naming scheme (<scope>_<verb>, e.g. db_query).
Transport: stdio by default; pass secrets via environment variables, never CLI args.
Tools — validate every input with a schema (e.g. Zod / pydantic). Prefer a small, compact surface (a search + dispatch pair) over dozens of raw tools when the domain is large.
Separate read from write. Read-only tools are safe-by-default; write/side-effecting tools must require explicit confirmation (e.g. a confirmed: true flag and an allowlist of actions).
Resources — expose read-only context (status, schema, recent events) — no secrets.
Prompts — ship reusable prompt templates for common workflows where helpful.
On a downstream/dependency failure: return structured diagnostics, do not throw opaque errors.
Test tool handlers with mocked dependencies (no live side effects in unit tests).

Safety checks

No raw shell / file / network / arbitrary-code tools without an explicit approval policy.
All tool inputs validated against a schema.
Side-effecting tools gated behind confirmation + allowlist; destructive actions need a written authorization path. See .agent/SAFETY.md.

Done criteria

Tool list matches the published schemas; descriptions are accurate and current.
Secrets only via env; never logged or returned in tool output.
Build produces the server entrypoint referenced by your MCP config.
An inventory/reference doc is regenerated when the tool set changes.

References: MCP docs, Cursor / Claude Code MCP configuration guides.

More from this repository

same repository

unity-tests

synthet/project-twelve

Run ProjectTwelve Unity batch validation and EditMode/PlayMode test suites via Unity 6000.5.1f1. Use when the user or ticket asks to run Unity tests, EditMode fixtures, batchmode validation, or verify test results from TestResults/*.xml.

2026-07-220

agent-memory

synthet/project-twelve

Log agent sessions, consolidate project memory (dream), promote reviewed memory, and load context for new chats. Use when ending a session, improving cross-session recall, or when the user mentions agent memory, dream, log-session, or memory.md.

2026-07-190

backlog-queue

synthet/project-twelve

Wiki tickets under docs/wiki/tickets/ are the canonical task queue, each linked to a GitHub issue. Use when picking work, claiming an issue, or preparing PR references.

2026-07-190

pick-next-task

synthet/project-twelve

Recommend the next open wiki ticket to work on, ranked by phase then priority, without claiming or mutating anything. Use when the user asks "what's next", to pick the next task, or to start work without a specific ticket in hand.

2026-07-190

repo-sync

synthet/project-twelve

Sync project-twelve with the Assets/_Licensed submodule via fetch_remotes.py, git hooks, and /fetch-remotes. Use at session start, before picking backlog work, or when the user asks to sync repos or get latest.

2026-07-190

commit-and-push

synthet/project-twelve

Use when the user asks to commit and push, publish, ship, or prepare a release commit. Guides staging only intended changes, writing a Conventional Commit, committing, and pushing to origin after verifying status and diff.

2026-07-190

MCP server design

Use this skill when

Creating or extending an MCP server that exposes this project to AI agents

Adding tools, resources, or prompts

Configuring .cursor/mcp.example.json / .mcp.json

Procedure

Read the MCP specification and your SDK's docs.

Pick a clear, stable server name and a tool-naming scheme (<scope>_<verb>, e.g. db_query).

Transport: stdio by default; pass secrets via environment variables, never CLI args.

Tools — validate every input with a schema (e.g. Zod / pydantic). Prefer a small, compact surface (a search + dispatch pair) over dozens of raw tools when the domain is large.

Separate read from write. Read-only tools are safe-by-default; write/side-effecting tools must require explicit confirmation (e.g. a confirmed: true flag and an allowlist of actions).

Resources — expose read-only context (status, schema, recent events) — no secrets.

Prompts — ship reusable prompt templates for common workflows where helpful.

On a downstream/dependency failure: return structured diagnostics, do not throw opaque errors.

Test tool handlers with mocked dependencies (no live side effects in unit tests).

Safety checks

No raw shell / file / network / arbitrary-code tools without an explicit approval policy.

All tool inputs validated against a schema.

Side-effecting tools gated behind confirmation + allowlist; destructive actions need a written authorization path. See .agent/SAFETY.md.

Done criteria

Tool list matches the published schemas; descriptions are accurate and current.

Secrets only via env; never logged or returned in tool output.

Build produces the server entrypoint referenced by your MCP config.

An inventory/reference doc is regenerated when the tool set changes.

References: MCP docs, Cursor / Claude Code MCP configuration guides.