mcp

MCP Server Best Practices

Follow these conventions when developing MCP servers.

Tool Design

Naming Conventions

Use descriptive, action-oriented names with service prefixes:

// Good - clear service prefix and action
"drive_list_files"
"docs_create"
"calendar_get_event"
"gmail_send_message"

// Bad - unclear or inconsistent
"listFiles"
"getDoc"
"sendEmail"

Input Schemas

Always provide comprehensive JSON schemas for tool inputs:

{
  name: "calendar_create_event",
  description: "Create a new calendar event with title, time, and optional attendees",
  inputSchema: {
    type: "object",
    properties: {
      title: {
        type: "string",
        description: "Event title/summary"
      },
      startTime: {
        type: "string",
        description: "Start time in ISO 8601 format (e.g., 2024-01-15T10:00:00Z)"
      },
      endTime: {
        type: "string",
        description: "End time in ISO 8601 format"
      },
      attendees: {
        type: "array",
        items: { type: "string" },
        description: "Email addresses of attendees (optional)"
      }
    },
    required: ["title", "startTime", "endTime"]
  }
}

Descriptions

Write clear, actionable descriptions that help the LLM understand:

• What the tool does
• When to use it
• What parameters mean
• What the output contains

// Good
description: "Search for files in Google Drive by name, type, or content. Returns file IDs, names, and metadata. Use this to find files before performing operations on them."

// Bad
description: "Search files"

Error Handling

Return Structured Errors

Always return errors in a consistent format:

if (!this.isAuthenticated()) {
  return {
    content: [{
      type: "text",
      text: JSON.stringify({
        error: "NotAuthenticated",
        message: "Please authenticate first using the google_auth tool",
        suggestion: "Run the google_auth tool to start the OAuth flow"
      }, null, 2)
    }],
    isError: true
  };
}