The 60-Second Window
A developer evaluating your MCP server will read the first two paragraphs of your README, maybe scroll through the headings, and decide whether to install or close the tab. You have about 60 seconds. Everything that matters needs to be visible without scrolling or clicking.
This means your README structure should front-load the most important information: what the server does, how to install it, and a quick example of it in action. Details, configuration options, and advanced usage can come later. Most readers won't get that far, and the ones who do already know they want your tool.
The Critical First Paragraph
Your first paragraph should answer three questions in plain language: what does this server connect your AI assistant to, what can you do with it, and why would you choose it over alternatives. Skip the project history, the motivation story, and the architecture overview. Those belong further down or in a separate document.
Bad first paragraph: "This project implements the Model Context Protocol specification to provide..." Good first paragraph: "Give your AI assistant read-only access to PostgreSQL databases. Ask questions about your data in plain English and get formatted results back. Supports all PostgreSQL 12+ versions."
Installation Must Be Copy-Paste
The installation section should contain a code block that the developer can copy, paste, and run. One command ideally. If your server requires multiple steps, number them and make each step a single command. Every manual step is a point where developers abandon the installation process.
Include the Claude Desktop (or other client) configuration snippet. This is the part developers struggle with most because it involves editing a JSON file in a specific location. A copy-paste config block eliminates this friction. Include comments in the JSON explaining what each field does.
Show, Don't Tell
Include a "Quick Start" or "Examples" section early in the README. Show a real conversation between a user and an AI assistant using your server. "User: How many orders were placed yesterday? Assistant: [uses your tool, returns result]." This demonstrates the tool's value faster than any feature list.
Screenshots or GIFs of the tool in action are even better, but a text-based example is the minimum. Developers need to see what the experience looks like before committing to installation.
What to Include (and What to Skip)
Include: one-line description, installation, configuration, examples, supported features, known limitations, and how to report issues. Skip (or put at the bottom): contribution guidelines, development setup, architecture decisions, changelog, and license details. These matter for contributors, not for users evaluating whether to install.
If your server has been scored on platforms like Skillful.sh, consider including the security grade as a badge. It provides instant credibility and saves evaluators a lookup.
Related Reading
- Why Developer Experience Matters for AI Tool Adoption
- How AI Tools Get Discovered in an Oversaturated Market
- How to Contribute to the Open-Source AI Tool Ecosystem
Browse MCP servers on Skillful.sh. Search 137,000+ AI tools.