MCP Tool Surface Design Checklist (printable)

Goal: ship one MCP server that exposes a small, safe set of tools with clean schemas, tight auth, and audit-ready logs. This is written for teams integrating LLM clients (chat, IDE, internal automations) with real systems (GitHub, Jira, Slack, databases).

1) Pick one workflow, not “an agent.”
- Example targets: draft a PR, draft a support reply, create a Jira ticket, summarize an incident.
- Avoid direct production writes on day one.

2) Inventory system-of-record boundaries.
- What system owns truth (GitHub vs Jira vs Salesforce)?
- Decide where the tool is allowed to write.

3) Define tool verbs narrowly.
- Prefer: create_draft_pr, search_issues, post_slack_message.
- Avoid: run_shell_command, execute_sql, call_internal_api(anything).

4) Make read and write tools separate.
- Separate scopes, separate logs, separate review rules.

5) Specify schemas like you mean it.
- Required fields, enums, max lengths, and explicit error responses.
- If a field is optional, decide the default behavior.

6) Add idempotency.
- Require a request_id for any tool with side effects.
- Ensure retries don’t duplicate actions.

7) Authenticate with least privilege.
- Use service accounts where possible.
- Keep credentials out of prompts; store in a secret manager.

8) Authorize per tool.
- Don’t rely on “the app is trusted.”
- Enforce allowlists (repos, projects, channels, tenants).

9) Log for audit.
- Log: tool name, caller identity, inputs (redacted), timestamp, outcome, object IDs created/modified.
- Decide retention and access controls for logs.

10) Add safety rails.
- Rate limits per user/client.
- Human approval for write operations early on.
- Environment segregation (dev/staging/prod).

11) Test failure modes.
- Invalid inputs, missing permissions, timeouts, upstream rate limits.
- Ensure tools return structured errors, not stack traces.

12) Version your tools.
- Treat tools like APIs: semantic versioning, deprecation windows, compatibility tests.
- Document the contract so multiple clients can rely on it.

If you can’t clearly answer: “Who called what tool, with which permissions, and what changed?” you’re not ready to scale beyond demos.