gitlab-mcp-server mcp-best-practices.instructions.md

MCP Best Practices

Protocol-level guidelines for building high-quality MCP servers that enable LLMs to accomplish real-world tasks effectively.

Tool Design Principles

Naming

• snake_case with service prefix: gitlab_create_issue, gitlab_list_projects
• Action-oriented verbs: get, list, search, create, update, delete
• Specific names: Avoid generic names that conflict with other MCP servers
• Descriptions must match behavior exactly: Narrow, unambiguous descriptions

Annotations

Every tool MUST declare annotations to help clients understand behavior:

Annotations: &mcp.ToolAnnotations{
    ReadOnlyHint:    boolPtr(true),
    DestructiveHint: boolPtr(false),
    IdempotentHint:  boolPtr(true),
    OpenWorldHint:   boolPtr(true),
}

Tool Type	ReadOnly	Destructive	Idempotent	OpenWorld
list / get / search	true	false	true	true
create	false	false	false	true
update	false	false	true	true
delete	false	true	true	true

Atomic Operations

Keep tools focused on a single operation. Avoid multi-step tools that combine unrelated actions.

Response Formats

• JSON: Structured data for programmatic processing (include all fields)
• Markdown: Human-readable display (use headers, lists, formatting)
• Convert timestamps to human-readable format in Markdown
• Show display names with IDs in parentheses when useful
• Omit verbose metadata in Markdown output

Pagination

For list operations:

• Default to 20-50 items per page
• Always respect the per_page / limit parameter
• Return metadata: has_more, total_items, page, total_pages
• Never load all results into memory for large datasets
• Use cursor-based pagination when offset-based becomes expensive

Error Handling

• Actionable messages: Tell the LLM what went wrong AND what to try next
• Report tool errors in results: Use IsError: true in CallToolResult for recoverable errors
• Don't expose internals: Hide stack traces, internal paths, database details
• Wrap with context: fmt.Errorf("gitlab_list_projects: %w", err)
• Clean up resources: Always release connections, files on errors