---
name: ecc-mcp-server-patterns
description: Patterns and best practices for building MCP (Model Context Protocol) servers — tool definition, resource exposure, transport options, and testing.
---

# MCP Server Patterns

Patterns and best practices for building MCP servers.

## When to Activate
- Building a new MCP server from scratch
- Adding tools or resources to an existing MCP server
- Debugging MCP server connectivity or tool call issues
- Converting an existing API or library into MCP tools

## Core Concepts

MCP servers expose:
- **Tools** — Functions the LLM can call (for actions)
- **Resources** — Data the LLM can read (for context)
- **Prompts** — Template-able interactions

## Tool Design Principles

- Names are verbs: `search_packages`, not `package_search`
- Parameters should be flat (not nested objects)
- Return structured JSON that's easy for LLMs to parse
- Include descriptive parameter descriptions
- Handle errors gracefully with meaningful messages

## Resource Design Principles

- Use `file://` style URIs for static content
- Include descriptive MIME types
- Support parameterized URIs for dynamic resources

## Testing

```bash
# MCP Inspector (web UI)
npx @modelcontextprotocol/inspector

# Direct CLI test
python -c "
import asyncio
from my_server import handle_call_tool
result = asyncio.run(handle_call_tool('tool_name', {'param': 'value'}))
print(result)
"
```

## Pitfalls

- Don't make tools that take too long (LLMs have timeouts)
- Don't expose destructive operations without confirmation
- Don't include API keys or credentials in tool definitions
- Keep tool responses concise — long responses waste tokens
