- The Model Context Protocol establishes a standardized interface for AI agents to interact with external tools, resources, and prompts.
- Implementing a weighted quality rubric ensures that tool definitions are semantically rich and structurally sound for LLMs.
- Production-grade MCP servers require strict transport security, including OAuth 2.1 and DNS rebinding protection.
- Effective error handling using the isError flag prevents protocol crashes and allows models to reason about failures.
Ever felt like your LLM is just guessing when it calls your tools? That’s usually because the underlying tool definitions lack the semantic depth needed for the model to make a confident choice. The Model Context Protocol (MCP) has stepped in to fix this by decoupling how context is provided from the actual interaction with the AI, allowing developers to build a single server that any compatible client can leverage without writing custom plugins for every single assistant. You can explore more about the interoperability of coding tools with MCP to understand this ecosystem better.
If you are diving into the TypeScript SDK, you are looking at a powerful toolkit that supports Node.js, Bun, and Deno. Whether you are deploying via standard input/output for local apps or using streamable HTTP for remote services, the goal is the same: creating a predictable and robust interface that lets AI agents execute actions, fetch data, and follow reusable workflows without breaking a sweat.
Building a Quality Linter for MCP Tools
To stop the guesswork, savvy developers are building CLI linters to audit their tool definitions. Instead of just checking if the JSON is valid, these linters use a weighted quality rubric to assign a score from 0 to 100. This process usually involves libraries like Ajv for meta-validation and Zod for schema enforcement. The scoring is typically split across five dimensions: schema validity (30%), the actual quality of the descriptions (25%), how complete the arguments are (25%), naming conventions (10%), and the richness of the constraints (10%).
One of the biggest pitfalls is the description field. If a description is too short or starts with filler phrases like “This tool is used to…”, the LLM loses the semantic signal it needs. A pro tip is to start descriptions with strong action verbs like “Retrieve” or “Create”. If a tool has no properties in its input schema, it isn’t necessarily a failure—some tools just don’t need arguments—but if properties exist without descriptions, the linter should flag a significant deduction.
The Three Pillars of MCP Capabilities
When architecting your server, it is crucial to keep these three lanes separate to maintain stability:
- Tools: These are the “action” functions. The model decides when to call them to change state or grab live data.
- Resources: These are read-only context pieces, like database records or files, addressed via URIs. They are application-controlled, meaning the model doesn’t decide to “run” them; they are simply loaded into the context.
- Prompts: Think of these as reusable templates. They allow users to trigger consistent workflows, like a standard code review, which are often exposed as slash commands in the UI.
Production Hardening and Transport Logic
Choosing your transport is a big deal because it defines your security perimeter. Stdio is great for local desktop agents because it inherits the user’s privileges and has no network surface. However, you must ensure that nothing is written to stdout except valid MCP messages, as stray logs will corrupt the JSON-RPC stream. Use stderr for logging instead.
For remote deployments, Streamable HTTP is the way to go, but it requires a much stricter approach to security. You should treat your MCP server as an OAuth 2.1 resource server. To achieve this, you can follow a guide on mastering authentication for AI agents and MCP servers. This means the server doesn’t issue tokens but validates them using bearer tokens and scopes. Implementing DNS rebinding protection and restricting allowed hosts is non-negotiable for servers exposed to the open web to prevent malicious attacks.
Handling Failures and Input Safety
A common rookie mistake is throwing an unhandled exception when a tool fails. In a production environment, you should use the isError flag. By returning { isError: true }, you tell the model that the tool execution failed (e.g., a city wasn’t found in a weather API) rather than the protocol itself crashing. This allows the LLM to see the error as a result it can reason about and potentially retry.
Finally, always remember that tool boundaries are trust boundaries. Since the arguments come from an LLM that is reading untrusted user text, you are at risk of injection attacks. Using Zod for strict validation is essential. Treat every validated input as data, never as code, and ensure that the OAuth scopes you’ve implemented strictly gate which tools a specific token is authorized to trigger.
By combining a rigorous scoring linter for definitions with the official TypeScript SDK and a strict OAuth 2.1 security model, you can transition from a fragile prototype to a professional MCP server. Prioritizing semantic clarity in descriptions and isolating tool failures via the isError flag ensures that your AI agent remains reliable and secure across both local and remote deployments.
