## TL;DR
Test the handshake, the tools list, every tool call, and the error paths before you submit, because reviewers and agents will hit exactly those four. The MCP inspector catches most of it in ten minutes. A server that passes the inspector on both stdio and remote transports almost never bounces in review.

```text
how to test an MCP server before submitting
```

## Use this when
- Your MCP server runs locally and you are close to submitting
- A reviewer bounced your listing for behavior you cannot reproduce
- You changed tools or schemas and want a regression pass
- You support both stdio and remote transports and need both verified
- You are writing the test plan section of a launch checklist

## Not for this skill when
- You are still choosing what tools the server should expose
- The problem is registry paperwork or metadata, not server behavior
- You need load testing for hundreds of concurrent agents (different discipline)
- You are debugging the MCP client or host application instead

## Steps
1. Start the server exactly the way a registry reviewer will. If the listing says `npx your-server`, test `npx your-server`, not your IDE run button. Environment differences between your machine and a clean install cause most "works for me" review failures.
   ```text
   fresh shell, no project env vars, run the documented start command
   ```
   Expected output: the server starts and stays up. Success check: it also starts on a second machine or a clean container.

2. Run the MCP inspector against it and walk the handshake. The inspector is the official interactive client; point it at your server and confirm initialize, tools list, and capabilities all come back clean.
   ```bash
   npx @modelcontextprotocol/inspector
   ```
   Expected output: the inspector UI connects and shows your server info. Success check: no protocol errors in the inspector log on connect.

3. List tools and read every description as a skeptical agent would. For each tool, ask: could an agent that has never seen my project guess when to call this? Rewrite any description that assumes context only you have.
   ```text
   [ ] every tool appears in the list
   [ ] every description names what it does and what it needs
   [ ] no two tools have descriptions an agent could confuse
   ```
   Expected output: a tools list you would trust a stranger's agent to use. Success check: a colleague can pick the right tool for three tasks from descriptions alone.

4. Call every tool with valid, invalid, and edge-case inputs. Valid inputs should return useful results. Invalid inputs should return clear errors, not stack traces or hangs. Timeouts, empty results, and auth failures each get one deliberate test.
   ```text
   [ ] happy path per tool: correct result, sensible shape
   [ ] bad input per tool: clear error message, no crash
   [ ] empty result: explicit "no results", not an empty blob
   [ ] slow dependency: times out gracefully under 30s
   ```
   Expected output: a matrix of tool by input class with pass or fail. Success check: zero crashes and zero hangs across the matrix.

5. Repeat steps 2 through 4 on the other transport. If you ship stdio and a remote endpoint, test both; auth, headers, and session handling only exist on the remote side and that is where the surprises live.
   ```text
   [ ] stdio: full matrix passes
   [ ] remote: full matrix passes, auth failures return clear errors
   ```
   Expected output: two passing matrices. Success check: the remote run used a fresh credential with minimum scopes.

6. Do one cold review of the listing metadata against the tested reality. Server name, version, tool count, and the repo link in your submission must match what the inspector just showed. Drift between listing and reality is an instant reviewer bounce.
   ```text
   [ ] name and version match the running server
   [ ] tool count matches the inspector
   [ ] repo link and docs link both resolve
   ```
   Expected output: metadata matches reality exactly. Success check: someone else verifies the match without your help.

## Variant phrasings
### MCP inspector tutorial
Hands-on phrasing. Steps 2 and 3 are the core: connect, handshake, read the tools list like an agent.

### MCP server QA checklist
Checklist phrasing. Steps 3 through 6 compress into a pre-submit checklist you can reuse every release.

### Test MCP server locally before publishing
Local-first phrasing. Emphasize step 1: test the documented start command in a clean environment, not your dev setup.

### MCP server works locally but fails in review
Troubleshooting phrasing. Almost always step 1 (environment drift) or step 4 (an error path that crashes instead of returning a clean error).

## Why it happens
Reviewers test like adversarial users because agents are adversarial users: they call tools with missing arguments, at odd hours, over flaky networks. A server that was only ever poked by its author in a warm IDE has never met those conditions. The inspector plus a deliberate error matrix simulates the reviewer before the reviewer simulates your users.

## Edge cases / pitfalls
- The inspector passing does not mean agents will use the tools well. Confusing descriptions pass protocol tests and fail in practice; step 3 is a judgment call, not a green check.
- Timeouts are the most common remote-transport failure. Test with a slow dependency on purpose; "usually fast" is not a test.
- Version skew between your test client and the registry's client can hide handshake bugs. Note the inspector version in your test log.
- If your server needs secrets, test with minimum-scope credentials. A test that only passes with an admin key is a finding, not a pass.

## Provenance

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