MCP server discoverability
How an agent finds, chooses and keeps using an MCP server. What to put in tool descriptions, why registries are not the main route yet, and what to measure.
An MCP server has two discoverability problems and they are different. Getting installed, and getting used correctly once installed.
The second one is where most servers lose, and it is the one nobody measures.
How MCP servers actually get installed today
Mostly by a person following an install instruction, or by a coding agent writing a configuration file after reading documentation. Registries exist and are improving, but most clients still rely on manual configuration rather than fetching a registry automatically.
So the routes that work now:
| Route | How it works |
|---|---|
| Documentation | A copy-and-paste configuration block a person or an agent applies |
| A one-line installer | A command that writes the configuration for them |
| Being bundled | The client or platform ships your server as an option |
| Registries | Listed and searchable, increasingly fetched, not yet the default path |
| Word of mouth | A repository, a post, a colleague |
The practical consequence: the configuration block in your documentation is the install button. Treat it that way.
Get the configuration block right
It should work when pasted, with nothing implied.
{
"mcpServers": {
"acme": {
"command": "npx",
"args": ["-y", "@acme/mcp-server"],
"env": { "ACME_API_KEY": "your-key-here" }
}
}
}Then say, on the same page:
- Where that file lives, for each client you support, by exact path.
- Where the key comes from, with a link.
- How to check it worked, with a command or a tool call that returns something.
- What the failure looks like, and what to do about it.
If a person or an agent has to visit a second page to complete step one, you lose some of them.
The part that decides whether you keep the install
An installed MCP server that the agent uses badly gets removed. This is where tool design matters more than marketing.
Write descriptions that say when to use the tool, not what it is.
Bad: search_records: Searches records.
Better: search_records: Find records by free text. Use this when the user describes what they are looking for in their own words rather than giving an ID. Returns at most 50 matches with their IDs; call get_record for the full content of one.
The second version tells the agent when to reach for it and what to do next. That is the whole job of a description.
Keep the tool count small. A server with forty tools spends the agent's context on a menu. Group operations behind fewer tools with clearer arguments, and let the arguments carry the variation.
Give every argument a type, a default and a constraint. An agent that has to guess a date format will guess wrong at least sometimes.
Make errors instructive. 400 Bad Request teaches nothing. The 'since' argument must be an ISO 8601 date such as 2026-09-03. You sent '3 days ago'. gets the next call right.
Return the next step. If a tool returns IDs, say which tool takes an ID. Agents follow that thread.
List on the registries
It is cheap and the direction of travel is clear. Publish accurate metadata: what the server does, what authentication it needs, what tools it exposes, and where the documentation is.
Just size the expectation correctly. Registry listings are not currently where most installations come from, so do not let a listing substitute for the configuration block in your documentation.
What to measure
Installs are the visible number and the least useful one. The useful ones come from the sessions.
| Measure | Why |
|---|---|
| Tool call success rate, per tool | A tool that fails often is a description problem, not a user problem |
| Which tools are never called | Either unnecessary, or badly described |
| Argument errors, per argument | Each one is a documentation defect |
| Task completion, not call success | A sequence of successful calls that failed the user is still a failure |
| Where sessions end | The last call before abandonment is your bug |
Tool descriptions that read well to a human often perform badly with an agent, and the only way to find out is to watch the sessions. That is what MCP analytics is for, and Armature's self-serve product does exactly this: it captures every session on an MCP server, a Claude Connector or a ChatGPT App and rebuilds it step by step.
Once installed, the question becomes whether it still works after a model update, which is what evals are for.
The two things to do first
- Make the configuration block work when pasted, with the file path for every client on the same page.
- Rewrite your tool descriptions to say when to use each tool and what to call next.
Both are an afternoon. Together they matter more than a registry listing.
Common questions
How do agents find MCP servers?
Mostly not through a registry. Today an MCP server is usually added by a person following an install instruction, or by a coding agent writing the configuration after reading documentation. Official registries exist but most clients do not yet fetch from them automatically.
What makes an MCP server easy for an agent to use?
Tool names and descriptions that say what the tool does and when to use it, a small number of tools rather than a large one, arguments with clear types and defaults, and errors that explain the fix rather than only the failure.
Should I list on an MCP registry?
Yes, it costs little and the situation is changing. Just do not expect it to be the main route to installation while most clients still rely on manual configuration.
How do I know whether my MCP server is actually being used well?
Capture the sessions. Every tool call, the intent behind it, and whether the task succeeded. Tool descriptions that read well often perform badly, and only the sessions show it.
Where this comes from
Armature ran 5,292 judged sessions with Claude Code, Codex and Cursor inside 51 realistic codebases, and published every run. The numbers on this page come from that work.