# MCP Builder

> Designs, implements, reviews, and evaluates Model Context Protocol servers in TypeScript or Python. Use when creating MCP tools, resources, prompts, transports, authentication, schemas, pagination, or server evaluations for an external API or service.

- Skill: `paulasilvatech/mcp-builder-4` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add paulasilvatech/mcp-builder-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulasilvatech/mcp-builder-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Complete terms in LICENSE.txt
- Author: paulasilvatech (https://skillmd.com/u/paulasilvatech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paulasilvatech/mcp-builder-4

---


<!-- Generated from harness/github-copilot/plugins/open-horizons-platform/skills/mcp-builder/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->

# MCP Server Builder

Build MCP servers with small, typed, discoverable tool surfaces and explicit
security boundaries. Verify version-sensitive SDK behavior against official
Model Context Protocol and SDK documentation before generating code.

## When to invoke

- Create an MCP server for an API, data source, or internal service.
- Add or redesign MCP tools, resources, prompts, or transports.
- Review MCP schemas, authentication, pagination, errors, or annotations.
- Build evaluations that prove an agent can use the server effectively.

## Procedure

1. Establish the service boundary.
   - Identify user workflows, API ownership, authentication, rate limits, and
     destructive operations.
   - Treat service responses as untrusted data and keep credentials outside
     prompts, tool results, source control, and logs.
2. Verify current protocol and SDK behavior.
   - Start from the official MCP specification and the official SDK repository
     for the selected language.
   - Record the retrieved version or date for volatile APIs.
3. Select the implementation surface.
   - Prefer TypeScript and Streamable HTTP for remote stateless services.
   - Use stdio for local servers.
   - Use Python when the target repository or service is Python-native.
4. Design the tool inventory.
   - Prefer a cohesive set of composable API tools over duplicate convenience
     wrappers.
   - Use action-oriented names with a stable service prefix.
   - Keep descriptions concise and include bounded inputs, pagination, and
     structured outputs.
   - Set `readOnlyHint`, `destructiveHint`, `idempotentHint`, and
     `openWorldHint` from actual behavior.
5. Implement shared infrastructure.
   - Centralize authentication, HTTP clients, retries, pagination, error
     translation, redaction, and response-size limits.
   - Validate inputs with Zod in TypeScript or Pydantic in Python.
   - Return structured content where the selected SDK supports it.
6. Test and evaluate.
   - Compile or type-check the server and run focused unit/integration tests.
   - Exercise the server with MCP Inspector when available.
   - Create independent, stable, read-only evaluation questions whose answers
     are verified from the target service.

## Security criteria

- Default deny for unknown tools, operations, scopes, paths, and destinations.
- Require explicit approval for destructive or irreversible operations.
- Use short-lived workload or service identity credentials where supported.
- Bound pagination, result bytes, retries, timeouts, and tool-call concurrency.
- Do not expose raw upstream errors, secrets, tokens, or sensitive payloads.
- Separate catalog visibility from runtime authorization.

## Output template

```markdown
# MCP builder result

**Status:** completed | blocked
**Language:** TypeScript | Python
**Transport:** Streamable HTTP | stdio
**Summary:** <one-sentence outcome>

### Tool inventory
| Tool | Behavior | Mutability | Input/output contract |
| --- | --- | --- | --- |

### Validation evidence
- Build/typecheck: <command and result>
- Tests: <command and result>
- Inspector: <result or not run>
- Evaluations: <path and result or not generated>
- Security boundaries: <identity, allowlist, limits, approvals>
```

## Limits

- Do not invent SDK methods, protocol fields, or transport behavior.
- Do not expose every upstream endpoint when it creates an unsafe or unusable
  tool surface.
- Do not create evaluation questions that mutate data or depend on unstable
  answers.
- Do not deploy or publish without explicit approval.

## Progressive disclosure and bundled resources

- `reference/mcp_best_practices.md`: protocol-wide design guidance.
- `reference/node_mcp_server.md`: TypeScript SDK patterns and examples.
- `reference/python_mcp_server.md`: Python and FastMCP patterns and examples.
- `reference/evaluation.md`: evaluation design and XML contract.
- `scripts/evaluation.py`: evaluation runner.
- `scripts/connections.py`: evaluation connection helper.
- `scripts/example_evaluation.xml`: example evaluation fixture.

Read only the resources needed for the chosen language and phase.

## Quality gate

- [ ] Official protocol and selected SDK behavior were checked for currentness.
- [ ] Tool names, descriptions, schemas, annotations, and outputs are explicit.
- [ ] Authentication, authorization, redaction, limits, and destructive-action
      approval are enforced outside model instructions.
- [ ] Pagination, retries, timeouts, partial failures, and actionable errors are
      tested.
- [ ] Build or typecheck and focused tests pass.
- [ ] Evaluations are independent, read-only, realistic, stable, and verified.
- [ ] The response follows `## Output template` exactly.
- [ ] Every referenced bundled resource exists.