Document local and remote setup

The README is part of the server. If another person can’t get it running from the docs alone, the server isn’t finished. Let’s write one that works on a machine that isn’t yours.

The structure I use

Give README.md these seven sections:

1. Requirements and tested versions
2. Install and type-check commands
3. Local stdio setup
4. Remote HTTP setup
5. Capability reference
6. Security model
7. Troubleshooting

Requirements come first because they fail first. Node 20 or later, the SDK version you tested, the Inspector version. Copy them from TESTING.md.

Local stdio setup

Show the host configuration a person pastes into their MCP client, with placeholders for their values:

{
  "mcpServers": {
    "project-notes": {
      "command": "npx",
      "args": [
        "tsx",
        "/ABSOLUTE/PATH/project-notes-mcp/src/index.ts"
      ]
    }
  }
}

Explain what this does: the host runs that command and owns the process. The user never starts the server by hand.

Say which environment variables the host should pass, if any. Never paste their values, not even fake-looking ones. People copy READMEs.

Remote HTTP setup

Document the exact /mcp URL, the protocol era the endpoint supports, and whether it requires a token. Then describe how to test it safely with the Inspector, including the current remote-transport flags.

Add one sentence I wish more READMEs had: opening the URL in a browser is not a test. A browser GET tells you almost nothing about an MCP endpoint. Use the Inspector.

Capability reference

List every capability with its arguments, result shape, side effects, and the access it needs. For us that’s search_notes, get_note, notes://catalog, and review_project.

State plainly that both tools are read-only. Then back it up: point to the handler code that only reads, and to the backend permission that can only read. A claim with a pointer is verifiable. A claim alone is marketing.

Troubleshooting

Write this section from the failures you hit while building. For this project I’d cover:

• a wrong absolute path in the host config, which shows up as “server failed to start”
• ES module errors, usually a missing type: module or a missing .js extension
• text written to stdout, which shows up as a JSON parse error on connect
• an unsupported protocol version between client and server
• a rejected origin or host on the HTTP endpoint
• 401 (no valid token) and 403 (valid token, wrong scope)

Each entry gets the symptom, the cause, and the fix. Three lines is enough.

The only test that counts

Clone the repository into a fresh folder, ideally on another machine, and follow only the README. Every place you had to remember something the README didn’t say is a documentation bug. Fix it in the README, not in your head.