mcp server dev

AI Community

Skill notes

What MCP Servers Are

An MCP server is a process that exposes one or more tools (and optionally resources and prompts) over the Model Context Protocol. Servers communicate via stdio transport — they read JSON-RPC from stdin and write responses to stdout. MCP servers are how you package and distribute tool capabilities. An LLM client (Claude Code, Claude Desktop, etc.) starts the server process and calls its tools.

When to Create a Server

You have 2+ related tools that share configuration, state, or domain You want to distribute tools for others to use (via uvx or npx) Tools need shared resources (database connections, API clients, auth tokens) You're building a domain-specific toolkit (GitHub, database, monitoring, etc.)

When NOT to Create a Server

Single utility tool — use a standalone tool file (see mcp-tool-dev skill) Claude Code agent, skill, or command — use their respective creation skills REST API — MCP is for LLM tool calling, not general HTTP services

Python vs TypeScript

Factor · Python (FastMCP) · TypeScript (@modelcontextprotocol/sdk) Distribution · uvx (uv tool) · npx Type system · Type hints + docstrings · Zod schemas Packaging · pyproject.toml · package.json with bin Async · Native async/await · Native async/await

Step 1: Design Your Tools

List every tool with its name, description, parameters, and return format. Apply the consolidation principle: prefer fewer capable tools over many narrow ones. For each tool, write the 3-4 sentence description (what, when to use, when NOT to use, behavior notes). This is the most important step — good descriptions prevent misuse.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
macOS · Linux · Windows
Runtime requirements
Node.js · Python
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Design Your Tools

List every tool with its name, description, parameters, and return format. Apply the consolidation principle: prefer fewer capable tools over many narrow ones. For each tool, write the 3-4 sentence description (what, when to use, when NOT to use, behavior notes). This is the most important step — good descriptions prevent misuse.

02
Step 2: Scaffold the Project

Use the templates as starting points: Python: `templates/mcp-server-python-template/` TypeScript: `templates/mcp-server-typescript-template/` Core directory structure: Python:

03
Step 3: Implement Tools

Write each tool handler following the patterns in the language-specific reference: Python: `references/python-server-patterns.md` TypeScript: `references/typescript-server-patterns.md` Key principles for all tools: Validate inputs at the top of every handler

04
Step 4: Configure Packaging

Python (uvx): Set `[project.scripts]` in `pyproject.toml`: TypeScript (npx): Set `bin` in `package.json`:

05
Step 5: Handle Server Lifecycle

Implement graceful shutdown (SIGINT/SIGTERM handling). This is critical for clean process termination when the client disconnects.

06
Step 6: Write Tests

Test at three levels: Unit: Import handler, call with dict, assert output Integration: Start server, call tools via MCP client Schema validation: Verify tool definitions match expected schemas See `references/server-testing-guide.md` for detailed patterns.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.