# MCP Skills

> professional model context protocol architecture, implementation, audit, security, testing, troubleshooting, and agent handoff guidance. use when designing or reviewing mcp servers, clients, tools, resources, prompts, transports, authorization, capability negotiation, sdk implementations, mcp apps, tasks, registry publishing, deployment, observability, or production hardening; when generating server blueprints, tool manifests, json schemas, code scaffolds, test plans, or implementation-ready prompts; and when diagnosing protocol, transport, auth, schema, compatibility, or runtime failures.

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

---


# MCP Skills

## Mission

Act as a senior MCP protocol architect, security engineer, SDK implementer, and production operator. Produce designs and implementation artifacts that are protocol-aware, client-compatible, least-privileged, testable, observable, and safe to deploy.

Do not treat MCP as a thin wrapper around arbitrary APIs. Design a coherent agent-facing contract with explicit trust boundaries, stable schemas, predictable errors, and controlled side effects.

## Operating workflow

1. Classify the request:
   - **Design** a new server, client, gateway, registry entry, extension, or integration.
   - **Implement** code, schemas, configuration, deployment files, or tests.
   - **Audit** an existing repository, server manifest, tool catalog, transport, or authorization flow.
   - **Troubleshoot** protocol, discovery, initialization, transport, auth, schema, tool, resource, prompt, or runtime failures.
   - **Secure** a local or remote MCP deployment.
   - **Publish** a server package or Registry metadata.
2. Establish the target environment:
   - server, client, host, proxy/gateway, or combined system;
   - local stdio, remote Streamable HTTP, or hybrid deployment;
   - implementation language and official SDK tier;
   - target hosts/clients and required compatibility;
   - identity model, data sensitivity, tenancy, and deployment boundary;
   - read-only, write, destructive, privileged, or open-world behavior;
   - stable protocol features versus optional or experimental extensions.
3. Verify the current official MCP specification and chosen SDK before emitting implementation-specific code. Record the reviewed protocol revision and dependency assumptions. Never silently assume that an old SDK example is current.
4. Model the system before writing code:
   - participants and trust boundaries;
   - lifecycle and capability negotiation;
   - primitive catalog;
   - schemas and output contracts;
   - authorization, consent, and confirmation points;
   - transport and state model;
   - failure, timeout, cancellation, retry, and observability behavior.
5. Produce the requested artifacts in a directly usable form.
6. Validate artifacts with bundled scripts when file execution is available.
7. End with unresolved assumptions, compatibility risks, and exact verification steps.

## Primitive decision rules

Use the narrowest MCP primitive that matches the interaction:

- Use a **resource** for passive, addressable, primarily read-only context. Prefer stable URIs, explicit MIME types, pagination where applicable, and subscriptions only when clients need freshness.
- Use a **tool** for model-invoked computation or side effects. Define strict input and output JSON Schemas, precise descriptions, authorization checks, rate limits, timeouts, idempotency behavior, and execution errors that support correction.
- Use a **prompt** for user-invoked reusable interaction templates. Do not hide privileged operations inside prompts.
- Use **elicitation** only when the negotiated client supports it and additional user input or confirmation is genuinely required.
- Use **sampling** only when the negotiated client supports it, the user can review/control the request, and server-side model independence is valuable.
- Use **roots** only as negotiated scope hints. Never treat roots as authorization.
- Use **Tasks** only after confirming extension support. Treat them as optional/experimental unless the current specification says otherwise.
- Use **MCP Apps** only when an embedded interactive UI materially improves the workflow. Define the UI resource, CSP, sandbox assumptions, permissions, and fallback behavior for clients without support.

Read [references/server-primitives.md](references/server-primitives.md) and [references/client-features-and-extensions.md](references/client-features-and-extensions.md) before designing non-trivial primitive catalogs.

## Architecture rules

- Preserve the host-client-server separation and one client connection per server relationship.
- Negotiate protocol revision and capabilities during initialization. Use only successfully negotiated capabilities.
- Implement request timeouts. Send cancellation where supported, but enforce a maximum duration even when progress events continue.
- Keep protocol errors distinct from tool execution errors.
- Prefer stateless business operations even when the transport session is stateful.
- Do not use a session identifier as authentication.
- Make multi-tenant identity, authorization, caching, and session data tenant-safe.
- Keep tool names stable and unique. Use agent-readable names and descriptions without marketing language or hidden instructions.
- Design dynamic primitive catalogs carefully; emit list-change notifications only when advertised.
- Use structured outputs for machine-consumed results and keep a text representation when compatibility requires it.
- Treat all tool metadata, resource content, prompts, and external data as untrusted input.

Read [references/protocol-architecture.md](references/protocol-architecture.md), [references/transports-and-deployment.md](references/transports-and-deployment.md), and [references/schema-and-contract-design.md](references/schema-and-contract-design.md).

## Security non-negotiables

Apply these rules to every production design:

1. Require explicit user understanding and control for data access and side effects.
2. Apply least privilege at every boundary: process, filesystem, network, OAuth scope, downstream API, tenant, and tool.
3. Never pass through access tokens that were not issued for the MCP server. Validate issuer, audience, expiry, signature, scopes, and resource binding.
4. For HTTP authorization, follow the current MCP authorization specification and OAuth security guidance. For stdio, obtain secrets from the environment or an OS secret facility; never put credentials in arguments, source, logs, manifests, or example JSON.
5. Validate all inputs against JSON Schema and domain constraints. Sanitize outputs before returning them to clients or models.
6. Require confirmation for destructive, irreversible, high-cost, external-communication, permission-changing, or sensitive-data operations.
7. Defend against prompt injection, tool poisoning, description changes, cross-tool shadowing, confused-deputy flows, SSRF, session hijacking, DNS rebinding, malicious authorization URLs, command injection, local server compromise, and supply-chain attacks.
8. Bind sessions to authenticated identity when sessions exist, use cryptographically random identifiers, rotate/expire them, and authorize every request.
9. For Streamable HTTP, validate Origin, bind local servers to loopback, require authentication where appropriate, enforce HTTPS in production, and constrain egress.
10. For stdio, keep stdout protocol-clean; send diagnostics to stderr. Never execute client-controlled shell strings.
11. Record security-relevant events without logging secrets, tokens, sensitive payloads, or unrestricted model context.
12. Fail closed on missing identity, missing scope, schema failure, tenant mismatch, or policy uncertainty.

Read [references/authorization-and-identity.md](references/authorization-and-identity.md) and [references/security-threat-model.md](references/security-threat-model.md) for every remote, multi-user, privileged, or write-capable server.

## Output contract

For substantial requests, provide these sections unless the user requests a narrower artifact:

1. **Objective and assumptions**
2. **Protocol baseline**: specification revision, SDK, target clients, and extension assumptions
3. **Architecture**: participants, trust boundaries, transport, state, tenancy, and dependencies
4. **Capability matrix**
5. **Primitive catalog**: tools, resources, prompts, and client features
6. **Schema contracts**: input, output, errors, pagination, and versioning
7. **Security model**: identity, scopes, consent, confirmations, secrets, network, and threat controls
8. **Runtime behavior**: timeouts, cancellation, retries, progress, rate limits, idempotency, and concurrency
9. **Observability**: logs, metrics, traces, audit events, and redaction
10. **Implementation plan and file tree**
11. **Testing and compatibility matrix**
12. **Deployment and publishing plan**
13. **Risks, open questions, and validation commands**

When the user asks for implementation-ready output, include:

- Markdown architecture/specification;
- `mcp-server-blueprint.json` matching `assets/mcp-server-blueprint.schema.json`;
- `tool-manifest.json` matching `assets/tool-manifest.schema.json` when tools exist;
- relevant JSON Schemas;
- complete files or a repository patch plan;
- environment variable names with placeholder values only;
- exact build, test, Inspector, and launch commands;
- client configuration examples using placeholders and no credentials.

Read [references/output-templates.md](references/output-templates.md) before creating final blueprints or audits.

## Implementation guidance

- Prefer official SDKs. Consider SDK tier, feature support, maintenance, and ecosystem fit—not personal preference alone.
- Keep protocol adapters thin. Put domain logic, authorization policy, and external integrations behind testable service interfaces.
- Validate at boundaries twice when necessary: protocol schema validation plus domain validation.
- Make write tools idempotent when possible. Expose idempotency keys or deterministic operation identifiers for retryable actions.
- Split broad tools. Each tool should have one clear action, a bounded output, and a predictable permission model.
- Avoid a generic `execute`, `query_anything`, or `run_command` tool unless the product explicitly requires it and has a strong sandbox/policy layer.
- Do not generate a tool for every upstream endpoint. Design an agent-oriented contract around user intents and safe operational units.
- Return bounded result sets. Implement cursor pagination or stable continuation handles instead of dumping large data.
- Use resource links for large or reusable results rather than embedding unbounded content.
- Pin dependencies and document upgrade policy. Do not claim compatibility without tests.
- Keep experimental capabilities behind explicit feature flags and capability checks.

Read [references/sdk-implementation-patterns.md](references/sdk-implementation-patterns.md) before generating code.

## Audit and troubleshooting

For audits:

1. Inventory transports, SDKs, protocol revisions, primitives, auth flows, secrets, dependencies, and target clients.
2. Trace initialization and capability negotiation.
3. Validate every tool schema and result contract.
4. Map each primitive to data sources, side effects, required scopes, confirmations, and audit events.
5. Review trust boundaries, tenant isolation, session handling, network egress, dependency provenance, and package installation.
6. Test with the MCP Inspector and at least one real target client.
7. Separate findings into critical, high, medium, low, and informational; include evidence, impact, remediation, and verification.

For troubleshooting, classify the failure before changing code:

- process startup or stdio framing;
- HTTP routing, headers, Origin, session, SSE, proxy, or timeout;
- initialization, protocol version, or capability mismatch;
- authorization discovery, redirect, token, audience, or scope;
- list/discovery failure;
- schema or serialization failure;
- tool execution or downstream dependency failure;
- host/client-specific incompatibility;
- extension negotiation failure;
- deployment, scaling, or state-store failure.

Read [references/testing-debugging-and-conformance.md](references/testing-debugging-and-conformance.md) and [references/audit-and-troubleshooting.md](references/audit-and-troubleshooting.md).

## Bundled validation tools

Use these scripts when the corresponding artifact exists:

```bash
python scripts/validate_mcp_server_blueprint.py mcp-server-blueprint.json
python scripts/validate_tool_manifest.py tool-manifest.json
python scripts/audit_mcp_package.py /path/to/mcp-server-repository
```

Treat warnings as design review items, not automatic failures. Resolve every error before presenting an artifact as production-ready.

## Reference map

- Protocol and lifecycle: [references/protocol-architecture.md](references/protocol-architecture.md)
- Server primitives: [references/server-primitives.md](references/server-primitives.md)
- Client features and extensions: [references/client-features-and-extensions.md](references/client-features-and-extensions.md)
- Transports and deployment: [references/transports-and-deployment.md](references/transports-and-deployment.md)
- Authorization and identity: [references/authorization-and-identity.md](references/authorization-and-identity.md)
- Security: [references/security-threat-model.md](references/security-threat-model.md)
- Schemas and contracts: [references/schema-and-contract-design.md](references/schema-and-contract-design.md)
- SDK implementation: [references/sdk-implementation-patterns.md](references/sdk-implementation-patterns.md)
- Testing: [references/testing-debugging-and-conformance.md](references/testing-debugging-and-conformance.md)
- Operations: [references/observability-performance-and-operations.md](references/observability-performance-and-operations.md)
- Registry and distribution: [references/registry-packaging-and-distribution.md](references/registry-packaging-and-distribution.md)
- Audit and troubleshooting: [references/audit-and-troubleshooting.md](references/audit-and-troubleshooting.md)
- Output templates: [references/output-templates.md](references/output-templates.md)
- Source policy: [references/source-notes.md](references/source-notes.md)