MCP Server Builder

MCP Server Builder

When to use this skill

Use this skill when building a Model Context Protocol (MCP) server to expose tools/resources/prompts to Atlarix (or other MCP clients), and you want correct schemas, safe handlers, and reliable local testing.

Core patterns

MCP server anatomy

MCP servers usually expose:

• Tools: callable functions with inputSchema
• Resources: addressable data (URI templates), with MIME types
• Prompts: reusable prompt templates (optional)

Tool definitions (name, description, inputSchema)

Rules:

• Names are stable, lowercase, snake_case or kebab-case
• Descriptions are action-oriented (“Use this to…”)
• inputSchema is strict enough to prevent garbage input

Validate input even if schema exists—treat schema as first line of defense.

Tool handlers: return structured results

Rules:

• Always validate input
• Always return structured JSON (or well-typed content) on success
• Never throw raw errors; wrap into { success: false, error: "..." } where appropriate

Example result shape:

return {
  success: true,
  result: { id: "123", status: "ok" }
};

Resources: URI templates + MIME types

Pattern:

• resource://logs/{id}
• return text/plain, application/json, etc.

Avoid:

• returning huge blobs by default (add pagination or “summary then expand”)

Transport: stdio vs HTTP

Use stdio when:

• local tools
• launched by a desktop client

Use HTTP when:

• remote service
• multi-tenant environment
• you need auth, rate limiting, observability

Testing with mcp-inspector

Run locally and verify:

• tool list appears
• schemas validate
• error cases are readable

Common errors:

• schema mismatch (client sends {} but server expects string)
• handler returns wrong shape
• transport not wired (stdio streams not flushed)

Safety patterns for mutating tools

If a tool can mutate state (filesystem, DB, deployments):

• require explicit parameters that make the operation unambiguous
• add a “dry run” mode where possible
• return a preview/plan object the client can display
• avoid “delete everything” endpoints