> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Build an MCP server for direct coding agent access
> Learn what the Model Context Protocol is, what makes a high-scoring MCP server, and how to submit your server to Devtool Arena for public benchmarking.
An MCP server changes the relationship between a coding agent and your API from abstract to verified. Without MCP, the best an agent can do is recommend your API based on what it knows from training data, web search, or your llms.txt file — and hope the code it generates works. With MCP, the agent connects to your API directly, calls your endpoints, and confirms that tasks complete successfully. That shift from "I think this works" to "I verified this works" meaningfully changes recommendation behavior.
## What MCP is
The Model Context Protocol (MCP) is an open standard for connecting AI systems to external data sources and capabilities. It was developed by Anthropic and is supported across Claude Code, and increasingly across other coding agents in the ecosystem. When you build an MCP server for your API, coding agents can:
1. **Discover** that your API is available as a direct integration
2. **Call** your endpoints through a standardized protocol, not by generating raw HTTP code
3. **Verify** that responses are correct before completing a recommendation
The [MCP server registry](https://github.com/modelcontextprotocol/servers) has over 85,000 stars on GitHub and is the primary directory for discoverable MCP integrations. Publishing your server there is the most important step for ecosystem discoverability.
## How MCP changes agent recommendations
The difference in agent behavior is significant. Consider a developer asking Claude Code to "create a new project in Linear":
**Without MCP:**
The agent generates code that calls the Linear API, returns it to the developer, and the developer must run it manually. If the code has a bug, the developer debugs it. The agent never confirms the task succeeded.
**With MCP:**
Claude Code recognizes that Linear has an MCP server, connects to it directly, executes the action, and confirms the project was created — all within the conversation. The developer sees a result, not a code snippet to run later.
That experience difference directly impacts recommendation rates. In Lightsage's testing of 70+ APIs, MCP presence correlated strongly with higher usability scores and lower task abandonment rates. The agents that could verify success through MCP were far more likely to commit to a recommendation.
### The recommendation flow with MCP
```
Developer prompt
│
▼
Agent searches for available integrations
│
▼
Finds your MCP server in registry
│
▼
Connects and calls your endpoint
│
▼
Verifies response is correct
│
▼
Recommends and implements your API with confidence
```
### The recommendation flow without MCP
```
Developer prompt
│
▼
Agent checks training data, web search, llms.txt
│
▼
Generates code (may contain errors)
│
▼
Returns code to developer to run manually
│
▼
If it fails, agent troubleshoots without live feedback
│
▼
May switch to a competitor with MCP presence
```
## How Lightsage evaluates your MCP server
The Devtool Arena leaderboard includes a dedicated MCP track. Lightsage evaluates MCP servers across three scores:
End-to-end task success rate. Given a real developer task, does the agent complete it using your MCP server? Measured across multiple task types and agent harnesses.
How easily can agents find your MCP server? Factors include presence in the MCP registry, documentation quality, and whether your server appears in agent context when relevant prompts are run.
Percentage of individual tool calls that complete without error. Broken down by tool and by error type, so you can see exactly which parts of your MCP server are underperforming.
In Lightsage's benchmarks, MCP task completion times ranged from 1 minute 28 seconds (Exa, 6 tool calls) to 39 minutes 5 seconds (Coinbase, 79 tool calls). The gap between a well-built MCP server and a poorly built one is not marginal — it determines whether agents prefer your integration or abandon it.
## Best practices for a high-scoring MCP server
Most MCP servers in the registry are minimally functional. The ones that dominate their categories share a set of consistent design patterns.
### Clear tool descriptions
Every tool in your MCP server requires a description that the agent uses to decide when to call it. Vague descriptions lead to wrong tool selection; wrong tool selection leads to failed tasks and low eval scores.
**Weak description:**
```json theme={null}
{
"name": "create_charge",
"description": "Creates a charge"
}
```
**Strong description:**
```json theme={null}
{
"name": "create_charge",
"description": "Creates a one-time payment charge. Use this when the developer needs to accept a credit card payment for a fixed amount. Requires amount in the smallest currency unit (cents for USD), currency code, and a payment_method_id obtained from your frontend SDK. Returns a charge object with status 'succeeded', 'pending', or 'failed'."
}
```
The strong description tells the agent when to use the tool, what inputs it expects, and what output to anticipate. That context is what enables accurate tool selection.
### Consistent auth patterns
Your MCP server should accept authentication in the standard way for your ecosystem. For most APIs, that means a Bearer token passed via an environment variable during server initialization — not per-request, not through a custom header scheme that agents won't know to use.
Document the exact environment variable name and format in your MCP server README. If you use `ACME_API_KEY`, say so explicitly. If the key format is `sk_live_xxx`, include that.
### Descriptive error messages
Error handling inside your MCP server is as important as error handling in your REST API. When a tool call fails, return an error object that tells the agent what went wrong and what to do next.
```json theme={null}
// Poor error response
{
"error": "Request failed"
}
// Effective error response
{
"error": {
"code": "invalid_api_key",
"message": "The API key provided is not valid. Expected format: sk_live_xxx or sk_test_xxx. Check your ACME_API_KEY environment variable.",
"docs": "https://docs.acmepayments.com/auth"
}
}
```
The effective error response gives the agent enough information to self-correct without switching to a competitor.
### Comprehensive endpoint coverage
Your MCP server should cover your API's primary use cases end-to-end. A server that only exposes two or three endpoints forces the agent to fall back to raw API calls for everything else, which eliminates the reliability advantage MCP provides.
Prioritize the endpoints that appear most frequently in developer tasks:
* Core create/read/update/delete operations for your primary resource
* Authentication and setup flows
* The endpoints referenced in your quick start documentation
* Webhook registration if your API is event-driven
## How to register your MCP server
Implement your MCP server following the [MCP specification](https://modelcontextprotocol.io). Test each tool against Claude Code locally before publishing. Run the same prompts you use in Lightsage prompt tracking to validate end-to-end task completion.
Submit a pull request to the [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) repository. Follow their contribution guidelines for adding your server to the official registry. This is the primary discovery path for the Claude Code ecosystem.
Write your MCP server README with agents as the primary audience. Include the exact environment variables required, the format of each one, installation instructions (typically `npx` or `uvx`), and a list of available tools with their descriptions.
Update your `yourdomain.com/llms.txt` to reference your MCP server. Agents that read your llms.txt will then know an MCP integration is available before they search the registry.
```text theme={null}
## MCP Server
Install our MCP server to connect Claude Code directly to [Your API]:
npx @yourco/api-mcp
Registry: https://github.com/modelcontextprotocol/servers/your-server
```
To get your MCP server benchmarked and listed on the Devtool Arena MCP leaderboard, submit your server details at [lightsage.com/welcome](https://app.lightsage.com/welcome). Lightsage runs your server through a standardized eval harness using Claude Code and reports eval score, discovery score, and task success rate.
## MCP category leaders by use case
Based on Lightsage's benchmarks across 70+ APIs, these MCP servers have the highest eval scores in their categories:
| Category | MCP leaders |
| ------------------- | -------------------------- |
| Vector databases | Chroma, Qdrant |
| Search and scraping | Tavily, Jina AI, Firecrawl |
| Email | AgentMail |
| Authentication | Descope, Clerk |
| Payments | Stripe, PayPal |
| Voice AI | ElevenLabs, Deepgram |
| Sandboxes | Daytona |
| Meeting bots | MeetGeek, Recall.ai |
The pattern across all category leaders: their MCP servers have clear tool descriptions, consistent auth, descriptive errors, and broad endpoint coverage of their primary workflows.
## Common MCP server pitfalls
A server with two or three tools forces agents to fall back to raw HTTP calls for everything else. Cover your primary workflows completely. If an agent must exit MCP mid-task, the reliability advantage disappears.
The tool description is the primary signal an agent uses to select the right tool. If the description could apply to multiple tools or doesn't specify inputs and outputs, the agent will make wrong selections and fail tasks.
Returning an empty success response when something goes wrong is worse than returning a clear error. Agents interpret empty success as task completion and move on — leaving the developer with a broken state and no indication of what happened.
Claude Code and Codex have different tool selection behaviors. A server that works perfectly with Claude Code may fail with Codex if the tool descriptions use Claude-specific conventions. Test against both before publishing.
Publishing an MCP server on your own docs without submitting to the official registry means agents that search the registry for your category will not find you. Registry presence is the primary discovery mechanism.
## Measuring MCP impact in Lightsage
After publishing your MCP server, track the following metrics in your Lightsage dashboard:
* **Tool call success rate** — should increase as agents use MCP calls instead of raw API calls
* **Error recovery rate** — should increase with better error messages from your MCP server
* **Completion rate** — should increase as agents can verify task success directly
* **MCP eval score** — your Devtool Arena MCP leaderboard position, tracked over time
Allow four to six weeks after publishing before drawing conclusions. MCP adoption grows as agents update their context about available integrations and as more developers install your server in their Claude Code environments.
## Related guides
* [Add llms.txt to improve coding agent discoverability](/docs/guides/llms-txt) — the prerequisite Layer 3 step before MCP
* [Optimize your API for AI coding agent discovery](/docs/guides/optimize-for-agents) — full 4-layer optimization framework
* [How to track coding agent recommendations for your API](/docs/guides/track-coding-agents) — measure MCP impact on your metrics