---
name: amariahak/MCP Server Builder
source: https://app.decimal.ai/s/amariahak-mcp-server-builder@1/SKILL.md
source_sha256: bfb5e7c8037e
---

# 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:

```ts
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

### Versioning tools
When you change a tool:
- keep name stable if semantics are compatible
- otherwise add a new tool name and deprecate the old
- document breaking changes in the repo and in tool descriptions

## Atlarix tool notes
- Add the MCP server via **Settings → Tools → MCP**.
- Prefer small, composable tools over a single “do everything” tool.
- If a tool can mutate user data, design it to require explicit confirmation in the UI.

Recommended development loop:
- implement tool → test in mcp-inspector → add to Atlarix → run a real workflow

When designing tools for Atlarix agents:
- keep outputs concise by default (IDs + summaries; add “expand” tools if needed)
- prefer deterministic outputs (stable keys, predictable structures)

## Common mistakes to avoid
- Overly permissive schemas that allow invalid input
- Throwing raw errors (leads to unclear UX)
- Returning massive payloads without pagination
- Creating tools that do multiple unrelated things
- Shipping tools without local test coverage
- Returning unvalidated input downstream
- Building a single mega-tool instead of small composable tools

## Mini-checklist
- Input validated
- Output structured
- Error messages actionable
- Resource payloads bounded
- Tested via mcp-inspector
- Mutating tools are safe-by-design