Model Context Protocol (MCP)

Best Practice: Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open standard, introduced by Anthropic in late 2024, that defines how AI applications connect to external tools, data, and prompts. It works like a universal adapter: an MCP client (the AI app) talks to MCP servers (which expose tools, resources, and prompts) over a single, well-defined protocol. Instead of building a custom integration for every data source, you implement the standard once. MCP matters because it makes AI tool use portable, secure, and reusable across different models and applications.

MCP follows a client-server architecture. The host application embeds an MCP client, and each integration is an MCP server that exposes three kinds of capability: tools (actions the model can invoke), resources (data the model can read), and prompts (reusable templates). Because the protocol is standardized, a single server can be reused across many AI applications, and a single application can connect to many servers without bespoke glue code. Good server design is schema-first, applies least-privilege access, and requires explicit user consent before any sensitive or irreversible action.

Step-by-Step Implementation Guidance

1. Identify the tools and data your AI app needs to reach.
2. Choose to consume existing MCP servers or build your own.
3. Define server capabilities: tools (actions), resources (data), and prompts.
4. Use clear names, descriptions, and JSON schemas so the model can call tools correctly.
5. Apply least-privilege access and require explicit user consent for sensitive actions.
6. Handle errors with structured, model-readable messages.
7. Test tool calls against an MCP client and add evals for tool selection.
8. Version and document server capabilities for consumers.

Security is central to good MCP design. Because servers can expose powerful actions, they should request the narrowest scopes needed, use short-lived scoped tokens, and surface a clear consent step before performing anything sensitive or irreversible. Errors should be returned in a structured, model-readable form so the agent can reason about and recover from failures rather than guessing. Tool descriptions and JSON schemas should be precise, since vague descriptions are a leading cause of wrong or missed tool calls.

Common Mistakes Teams Make When Ignoring This Practice

• Building one-off, brittle integrations per model and app.
• Vague tool descriptions that cause wrong or missed tool calls.
• Granting broad permissions instead of least privilege.
• No consent step before destructive or sensitive actions.
• Returning opaque errors the model cannot reason about.

Tools and Techniques That Support This Practice

• SDKs: official MCP SDKs for TypeScript, Python, and others.
• Clients: Claude Desktop, IDE agents, and other MCP-aware apps.
• Patterns: tool/resource/prompt separation, schema-first design, scoped tokens.

How This Practice Applies to Different Migration Types

• Cloud Migration: Expose infra inventory through an MCP server so an assistant can query it safely.
• Database Migration: Provide a read-only MCP server over schema metadata for mapping work.
• SaaS Migration: Wrap vendor APIs as MCP tools to standardize integration.
• Codebase Migration: Serve repository search and build tools to a coding agent via MCP.

Checklist

• Required tools and data identified
• Capabilities split into tools, resources, prompts
• Clear names, descriptions, and schemas defined
• Least-privilege access enforced
• User consent required for sensitive actions
• Structured error handling implemented
• Tool selection covered by evals