mcp-tool-patterns

MCP Tool Patterns

Adding a Tool

1. Formatter in utils/formatters.py — pure function, no I/O, returns markdown string
2. Tool in tools/markets.py or tools/users.py — @mcp.tool() async handler that calls API and returns text(formatter(data))

from polymarket_mcp.config import READ_ONLY_ANNOTATIONS, gamma_url
from polymarket_mcp.server import mcp
from polymarket_mcp.utils.helpers import get, text
from polymarket_mcp.utils.formatters import format_search_markets

@mcp.tool(annotations=READ_ONLY_ANNOTATIONS)
async def search_markets(query: str, limit: int = 5, active_only: bool = True):
    """Search Polymarket markets by title or description.
    Returns matching markets with: current price, liquidity, volume,
    end date, and active status."""
    params = {"q": query, "limit_per_type": limit, "events_status": "active" if active_only else None}
    data = await get(f"{gamma_url}/public-search", params=params)
    return text(format_search_markets(data))

New tool modules must be imported from tools/__init__.py so registration runs at startup.

Tool Docstrings

• Become the agent-facing tool description — describe what is returned, not just parameters
• Use multi-line docstrings for complex tools

Response Format

• Formatters produce markdown (# / ## headers, key-value lines)
• Always return via text() — wraps markdown in JSON-encoded MCP TextContent
• Errors: err("message") for API failures; plain strings for input validation

Multi-API Tools

Use asyncio.gather(..., return_exceptions=True) and check each result:

portfolio_data, rank_data = await asyncio.gather(portfolio_task, rank_task, return_exceptions=True)
if isinstance(portfolio_data, Exception):
    return err(str(portfolio_data))

API Selection

• Market discovery/details → gamma_url (from config.py)
• User positions/portfolio/leaderboard → data_url (from config.py)