mcp-server-scaffold

Files (1)

• SKILL.md

SKILL.md (first lines)

# MCP Server Scaffold

> **Agents call tools. Tools call infrastructure. This boundary is the governance seam. Do not collapse it.**

An MCP server is a contract between an agent and the capabilities it is allowed to use. Its value is not in what it exposes — it is in what it deliberately withholds.

## When to use

- Adding a new MCP server to an agent system
- Reviewing an existing MCP server for scope creep or security gaps
- Deciding which capabilities to expose to an agent (and which to explicitly deny)
- Governing an agent that has been given "too much access"

## Procedure

1. **Define the tool seam** — before writing any server code, list:
   - What capabilities does the agent legitimately need?
   - What capabilities does the underlying system have that the agent must NOT access?
   - What is the minimum viable tool surface?

2. **Author the tool manifest** — for each tool:
   ```
   Tool: <name>
   Description: <one sentence — what it does and when to call it>
   Input schema: <typed fields with constraints>
   Output schema: <typed fields>
   Side effects: <what it changes in the world — none / read-only / write / external-call>
   Auth required: <yes/no and mechanism>
   Rate limit: <calls/minute or none>
   ```

3. **Enforce least-privilege at the server** — the MCP server holds the credentials and enforces the scope. The agent receives only the tool interface. Key rules:
   - Read tools and write tools are separate, explicitly named operations.
   - No tool exposes raw SQL, raw shell execution, or raw filesystem access.
   - No tool accepts arbitrary code or query strings from the agent without validation.

4. **Add input validation at the boundary** — every tool validates its inputs before executing. Reject malformed inputs with a structured error, not an exception trace.

5. **Log every tool invocation** — at minimum: tool name, caller identity, input summary (no secrets), output summary, timestamp, and latency. These logs are your audit trail.

6. **Test the refusal surface** — confirm that:
   - A call to a non-existent tool returns a clean error, not a server crash.
   - An out-of-scope request (e.g. an agent trying to read data it is not authorised for) is rejected with a clear error.
   - Invalid inputs are rejected before any side effect occurs.

7. **Document the scope boundary** — in the MCP server's README or SKILL.md, explicitly state what the server does NOT expose and why. Scope boundaries that are not documented drift.

8. **Run the Adversarial Gate** — common MCP failure modes: overly broad tool descriptions that invite misuse, missing input validation that allows prompt injection via tool arguments, write tools with no confirmation step, no rate limiting on expensive operations.

## Outputs

- Tool manifest (one entry per tool)
- MCP server skeleton with input validation and structured error responses
- Refusal surface test cases
- Scope boundary documentation

## Guardrails

- **No raw database access through an MCP tool.** Tools call repositories or services; repositories call databases.
- **Tool descriptions are part of the attack surface.** Vague descriptions invite misuse by the agent. Be precise.
- **No secrets in tool outputs.** If a tool must return an identifier, return the identifier — not the credential.
- **Scope creep is the default failure mode.** When in doubt, add a new tool rather than broadening an existing one.

From jpantsjoha/ai-native-developer-experience, Apache-2.0.

More from jpantsjoha/ai-native-developer-experience