Skip to content

mcpolish documentation

Who this page is for: anyone who just landed on the docs and is looking for the right entry point.

mcpolish is a static checker for MCP server source code. It reads the tool definitions in your .py files and reports problems that would cause an AI agent to pick the wrong tool, fail silently, or be tricked by a malicious tool description.

If you have never used a linter, think of it as a spellchecker for your tool descriptions.

Choose your starting point

You are... Start here
Brand new to mcpolish Quickstart (30 seconds)
Brand new to MCP itself What is MCP
Setting up your first project Your first lint
Trying to understand the output Understanding output
Looking for a specific command or flag CLI reference
Wiring mcpolish into CI GitHub setup or GitLab setup
Hitting a diagnostic and want to understand it Rules index

What problem does this solve?

When you build an MCP server, you give each tool a name and a description in English. An AI agent (Claude, GPT, Gemini) reads those descriptions to decide which tool to call. If your descriptions are vague, generic, or misleading, the agent picks the wrong tool.

In research published in 2026, vague descriptions caused 52 percentage points more wrong-tool selections in head-to-head tests. mcpolish detects 23 specific problems that lead to this failure, before you ship.

See What mcpolish checks for the five problem categories.

30-second tour

pip install mcpolish
mcpolish lint your_server.py

That is it. mcpolish prints any problems it finds, gives each one a stable rule ID, and exits non-zero if there are errors. Wire that into your CI and you have a quality gate.

Documentation map

Getting started

Concepts

Usage

Scenarios

Rules

Other