## TL;DR

Developers decide in 30 seconds whether to try an MCP server; the README is the trial.
A working quickstart beats a features list every time.
Applies to any MCP server published for others to use.

## The query

```text
how to write an MCP server README that gets adopted
```

## Use this when

- You are publishing an MCP server for others to use.
- Developers decide in seconds whether to try it.
- The README is the main trial experience.

## Not for

- The server is internal-only (a short internal doc is enough).
- You are writing registry metadata (that is a different, shorter format).
- The server is a prototype not ready for users (mark it experimental instead).

## Steps

1. Open with one line: what the server does and for whom.
   Expected output: A pitch a developer can repeat from memory.
2. Add a 30-second quickstart: install command, config snippet, and one example tool call.
   Expected output: A quickstart a new user can complete without reading further.
3. Document every tool with its inputs, outputs, and one example.
   Expected output: A tool reference that answers questions before they are asked.
4. Close with troubleshooting for the three most common setup failures.
   Expected output: A README that resolves the failures users actually hit.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_p1BbswVINuU7RxPSnQ01lA