MCP Server Onboarding Checklist

TL;DR

A Model Context Protocol (MCP) server is only useful if agents can pick it up without help. Use this 40-item checklist before you publish: name tools as imperative verbs, ship strict JSON Schema for inputs and outputs, attach a working example to every tool, secure the server with OAuth 2.1, expose a sandbox, document rate limits and idempotency, and declare safety annotations on destructive actions. The Model Context Protocol specification (modelcontextprotocol.io) is the source of truth; this checklist is the operational gate.

How to use this checklist

Walk the seven phases in order before flipping your MCP server to general availability. Score 1 point per checked box. The total is out of 40.

The checklist assumes you have already implemented the MCP base protocol (JSON-RPC 2.0 transport, capability negotiation, tool / resource / prompt primitives) per the Model Context Protocol specification.

Phase 1: Identity and discovery (5 points)

• [ ] Server has a stable, human-readable name and version returned in initialize
• [ ] serverInfo.title describes the integration in one short sentence
• [ ] instructions field provides a one-paragraph orientation for the agent
• [ ] Public README / landing page documents the install command and supported clients
• [ ] Server publishes a stable identifier (URL or package name) used in agent client registries

Phase 2: Tool design (8 points)

• [ ] Tool names are imperative verb phrases (create_invoice, not invoice or invoiceTool)
• [ ] Tool names are unique within the server and snake_case
• [ ] Each tool has a one-sentence description written in plain English
• [ ] No tool exceeds one logical capability — split umbrella tools
• [ ] Tools that mutate state are explicitly named (create_, update_, delete_*)
• [ ] Read tools are named with get_, list_, or search_*
• [ ] Tool count per server stays under ~30 (above this, agents struggle to choose)
• [ ] Deprecated tools are marked with deprecated: true and continue to work for at least one minor version

Phase 3: Schemas and contracts (7 points)

• [ ] Every tool has a complete inputSchema (JSON Schema draft 2020-12)
• [ ] Every tool has an outputSchema describing the structured result
• [ ] Required fields are explicit; optional fields document their default behavior
• [ ] Enums are used for any field with a finite value set
• [ ] Schemas validate cleanly against a standard JSON Schema validator
• [ ] Field descriptions explain why not just what ("customer_id: customer to invoice; must already exist")
• [ ] Backward-incompatible schema changes bump server version (semver minor or major)

Phase 4: Examples and documentation (5 points)

• [ ] At least one realistic example call per tool, with full input and expected output
• [ ] Examples include at least one error case per tool (e.g., "customer not found")
• [ ] Multi-step workflows are documented with a sequence of tool calls
• [ ] A quickstart page shows install → auth → first call in fewer than 10 minutes
• [ ] All examples are kept under version control alongside the server code

Phase 5: Authentication and security (6 points)

• [ ] Server implements OAuth 2.1 per the MCP authorization spec
• [ ] Authorization Server Metadata exposed at /.well-known/oauth-authorization-server (RFC 8414)
• [ ] Dynamic client registration supported per RFC 7591, or a documented alternative
• [ ] Refresh token rotation enabled with reuse detection
• [ ] Scope strings are granular and documented in plain language
• [ ] Revocation endpoint published and tested

Phase 6: Safety, rate limits, and observability (6 points)

• [ ] Destructive tools annotated with destructiveHint: true and requiresConfirmation: true
• [ ] Read-only tools annotated with readOnlyHint: true and idempotent: true
• [ ] Rate limits documented per scope and per tool, with Retry-After headers on 429
• [ ] Errors return JSON-RPC error objects with stable numeric code values
• [ ] Server logs include the requesting client identifier and tool name (no token material)
• [ ] Health check endpoint or ping tool available for monitoring

Phase 7: Sandbox and rollout (3 points)

• [ ] Public sandbox environment with isolated data, available without payment
• [ ] Sandbox returns the same schemas and error codes as production
• [ ] Changelog and deprecation policy published with a stable URL

Worked example: a minimum viable tool entry

{
  "name": "create_invoice",
  "description": "Create a draft invoice for an existing customer.",
  "inputSchema": {
    "type": "object",
    "required": ["customer_id", "line_items"],
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "ID of an existing customer. Use list_customers to find one."
      },
      "line_items": {
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "object",
          "required": ["description", "amount_cents"],
          "properties": {
            "description": {"type": "string"},
            "amount_cents": {"type": "integer", "minimum": 1}
          }
        }
      },
      "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"], "default": "USD"}
    }
  },
  "outputSchema": {
    "type": "object",
    "required": ["invoice_id", "status"],
    "properties": {
      "invoice_id": {"type": "string"},
      "status": {"type": "string", "enum": ["draft", "open", "paid"]},
      "total_cents": {"type": "integer"}
    }
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "requiresConfirmation": false,
    "idempotent": false
  }
}

Common mistakes

1. Vague tool names like do_thing or helper_v2. Agents cannot choose between them.
2. Missing outputSchema. Forces agents to parse free-form text.
3. Overloaded tools that switch behavior on a string parameter. Split into separate tools.
4. No sandbox. Agents must hit production to learn the API.
5. Token issued via API key only. Blocks user-delegated auth and consent.
6. No requiresConfirmation on destructive tools. Increases blast radius of agent mistakes.
7. Breaking schema changes without a version bump. Silently breaks every agent client.

FAQ

Q: Do I need to support every MCP primitive (tools, resources, prompts)?

No. Most servers only implement tools. Resources are useful for read-mostly data exposed as URIs; prompts are useful when you want to ship reusable prompt templates. Implement the subset that matches your use case and declare it in capability negotiation.

Q: How granular should my scopes be?

One scope per logical capability, mirroring the tool grouping. invoices.read, invoices.write, customers.read, etc. Avoid umbrella scopes like admin because they prevent agents from requesting least privilege.

Q: Is OAuth 2.1 mandatory for an MCP server?

The MCP authorization spec is built on OAuth 2.1, and Anthropic's reference clients expect it. Local-only servers (stdio transport) can skip OAuth, but any networked MCP server should implement it.

Q: How many tools should a single server expose?

Around 10-30 is the practical sweet spot. Below 10 is fine. Above ~30 the agent's tool-selection accuracy drops noticeably; consider splitting into multiple themed servers.

Q: What is the difference between destructiveHint and requiresConfirmation?

destructiveHint: true is a static fact about the tool (it can delete or modify state). requiresConfirmation: true instructs the calling client to prompt the user before invoking. Destructive tools should almost always require confirmation; non-destructive tools occasionally do (e.g., paid actions).

Q: How do I version my server without breaking agents?

Use semver. Bump major when you remove tools or break schemas; bump minor when you add tools or non-breaking fields. Maintain at least one minor version of overlap with deprecated tools marked deprecated: true.