Custom MCP server development

What is the Model Context Protocol (MCP) and why does it matter in 2026?

The Model Context Protocol is an open standard that Anthropic released in November 2024. It solves a specific problem: before MCP, every application that wanted to give Claude access to a tool had to build its own custom plumbing. The plumbing worked, but it was per-app, per-integration, and impossible to share across different Claude clients. MCP replaced that pattern with a single, consistent protocol for connecting AI models to tools, data sources, and external systems. You build the server once. Any MCP-compatible client can use it.

By 2026, MCP is widely adopted across the Claude ecosystem. Claude Desktop, Claude Code, and the Claude.ai web app all support MCP clients. Third-party tools, IDEs, and workflow platforms are adding MCP support because it is the standard, not a proprietary API. Anthropic publishes official MCP servers for Slack, GitHub, Google Drive, and other common sources. But official servers only cover common use cases. When your data lives somewhere custom, a custom MCP server is how you get that same native integration without waiting for Anthropic to ship it.

The practical consequence: operators who have built custom MCP servers are shipping AI use cases faster than those who have not. When Claude already has access to your CRM, your internal analytics API, and your ops database as first-class tools, every new AI workflow starts from that foundation. Teams without MCP spend weeks on plumbing every time they try to build something new. Teams with MCP spend days. That gap compounds fast when your team is actively building AI into their workflow. See the official MCP site and the MCP specification for the full protocol detail.

MCP vs REST APIs vs function calling: when to reach for which

These are not competing technologies. They solve overlapping problems at different layers, and the right choice depends on who is calling the tool, how often you need to reuse it, and how much auth complexity you want to manage. Here is the direct comparison:

Function calling (the Anthropic tool use API) is the right choice when you are building a specific application and the tools only make sense inside that app. You define the function schema inline, pass it with the API call, and Claude calls it during the conversation. The downside is that the plumbing is baked into the application. If you build a second app that needs the same tool, you rebuild the plumbing. If you want Claude Desktop to use the same tool, you are rebuilding it again in a completely different format.

MCP exists to solve that reuse problem. You build the server once, define the tools once, handle auth once. Any client that speaks MCP connects to it. That includes Claude Desktop, Claude Code, third-party tools that have added MCP support, and any internal apps you build on top of the MCP client libraries. REST APIs solve a different problem: making data accessible to any software. If you already have a REST API and you want Claude to use it, an MCP server is often the thin layer you build on top of it. The MCP server translates Claude’s tool calls into REST API calls and returns structured results the model can act on. See the full MCP vs REST vs function calling breakdown for deeper analysis.

When a custom MCP server is worth building vs using an off-the-shelf one

Start with the official servers. Anthropic and the MCP community maintain servers for GitHub, Slack, Google Drive, Postgres, and a growing list of common tools. If your use case fits, use the existing server. The build time is zero, maintenance is handled upstream, and the quality is high. The MCP server list at modelcontextprotocol.io is the right first stop.

A custom server is worth building when one or more of the following is true. Your data lives in a custom internal API with no public MCP server. Your auth model is non-standard: multi-tenant with per-customer credentials, short-lived tokens, or a proprietary SSO system. Your operations are not simple CRUD: you need business logic between the Claude request and the data source, such as access control checks, rate limiting per user, or computed fields that do not exist in the raw API. Or you want multiple Claude clients on your team to share the same tool surface without each person configuring credentials separately.

The cost threshold is low. A custom MCP server for a single data source, with one transport type and a handful of tools, typically takes three to five days to build if the underlying API is well-documented. The ongoing hosting cost for a small server is under $10 per month on a shared VM or free on Cloudflare Workers. The ROI calculation is straightforward: if the server unblocks even one AI use case that would otherwise take three weeks of custom plumbing, the build pays for itself immediately. Every subsequent use case built on top of it has near-zero integration cost.

The architecture of a custom MCP server

An MCP server exposes three types of primitives: tools, resources, and prompts. Tools are the most important for most custom builds. A tool is a callable function with a defined input schema (JSON Schema) that Claude can call during a conversation. When Claude decides to use a tool, the MCP client in the host application calls your server, your server executes the logic, and the result comes back as structured context the model uses in its next response. Tools are how Claude takes actions: querying a database, submitting a form, triggering a workflow. Resources are read-only data sources Claude can browse (think file listings or dataset references). Prompts are reusable prompt templates the server exposes for common tasks.

Transport is how the MCP client connects to your server. There are two options that matter in practice. Stdio (standard input/output) is the local transport: the MCP client spawns your server as a child process and communicates via stdin/stdout. This is the right choice for Claude Desktop and Claude Code on a single developer machine. It requires no network exposure, no auth configuration, and starts in seconds. HTTP with SSE (Server-Sent Events) is the remote transport: your server runs as an HTTP service, and clients connect over the network. This is the right choice for team deployments where multiple users share one server. The MCP specification documents both transports in detail.

SDK choice comes down to your team’s primary language. The TypeScript SDK is the most mature and has the largest community of examples. If your existing backend is Node.js, use the TypeScript SDK. The Python SDK is the right choice for Python-first teams and has good support for async patterns. Both SDKs are maintained by Anthropic and track the spec closely. The core pattern is the same in either language: define a server, register tools with their input schemas, implement handler functions, and connect a transport.

Error handling in MCP deserves specific attention. Claude uses the error messages from failed tool calls to decide what to do next. A raw 500 error with no context leaves the model with nothing to work with. A descriptive error message, such as “query returned no results for date range 2024-01-01 to 2024-03-31; try a broader range”, gives Claude enough context to adjust its approach, retry with different parameters, or explain the problem to the user. This is a different error-handling discipline than backend API development. Design your error messages as LLM-readable instructions, not just HTTP status codes.

Real case study: Ahrefs and Google Ads MCP for a content agency

A content agency running SEO and paid search for mid-market clients needed their team to move faster on campaign strategy. Their data lived in two places: Ahrefs for organic keyword data and Google Ads for paid performance. Every brief required a manual pull from both tools, a spreadsheet to merge the data, and an analyst hour before any content decisions could be made. The bottleneck was not analysis skill. It was data access latency.

The build was a single MCP server exposing tools for both sources: keyword metrics from Ahrefs, campaign performance from Google Ads, and a computed gap analysis tool that took a domain as input and returned a ranked list of keywords where organic rank and paid spend were misaligned. Claude Desktop with this server connected could run the full brief workflow in a conversation. An analyst typed a domain, Claude called the tools, and a complete brief came back in under two minutes. The full build took nine days. The first five downstream content workflows were shipped in the following week because the data access problem was already solved. See the SEO content engine case study for the complete story.

What made this work was the gap analysis tool specifically. It was not something that existed in either Ahrefs or Google Ads natively. It was business logic the agency had been running manually in spreadsheets for three years. Encoding that logic in the MCP server turned it into a callable tool. Claude did not need to be told how to run the analysis. It called the tool, got the result, and used it. That is the difference between an MCP server that wraps an API and one that encodes real operational knowledge.

Security and secrets management for MCP servers

The first rule is scope. Each tool in your MCP server should carry only the credentials it needs and no more. A tool that reads customer records does not need write access. A tool that queries an analytics database does not need access to the billing API. Use separate API keys or service accounts per tool where your data source supports it. If a Claude session is compromised or a tool is called unexpectedly, the blast radius is bounded by the credential scope rather than your entire integration surface.

For multi-user remote deployments, implement per-session auth. The MCP spec supports OAuth-style token flows where each user authenticates once and the server issues a scoped session token. This means Claude is acting on behalf of a specific authenticated user, not a shared service account. The audit log (what tool was called, with what parameters, by which user, at what time) becomes meaningful because you know whose session triggered each action. Log at the server level, not just the application level, so you have a record even if the client application fails to log.

What to avoid: passing your production database connection string as an environment variable and exposing a raw SQL query tool. This is the fastest way to give Claude (and anyone who can send it a message) unrestricted access to your data. The right pattern is a tool that accepts structured parameters, runs a pre-defined query or calls a specific API endpoint, and returns only the fields the caller needs. Claude does not need raw SQL access to answer “what were last month’s top 10 customers by revenue?” It needs a tool called get_top_customers that takes a date range and a limit and returns a list. See the Anthropic MCP security guidance for the full recommendations.

Hosting and deployment

For individual use on Claude Desktop or Claude Code, stdio transport running locally is the right deployment. No server needed. Your MCP server is a Node.js or Python script that the Claude client spawns as a child process when it starts. Configuration is a JSON block in the Claude Desktop or Claude Code config file pointing at the script path and any environment variables it needs. This is the right starting point for evaluating an MCP server before investing in infrastructure. The Claude Code MCP documentation covers local stdio setup step by step.

For team deployments, HTTP-with-SSE transport on a dedicated host is the right pattern. A 1-2 vCPU VM on Fly.io, a Hetzner CX11, or a DigitalOcean Droplet handles most small team workloads for under $10 per month. Cloudflare Workers is the right choice when you want zero-ops hosting and are comfortable with the Workers execution model (no persistent state, no long-running processes). Containerize the server (a 200-line Dockerfile for a Node.js MCP server is straightforward), add a health check endpoint that your load balancer can ping, and configure your team’s Claude clients to point at the HTTPS endpoint with their session tokens. Deployment takes under an hour once the server is built and tested locally.

The 3-week engagement shape

Week one is scoping. We identify the data source, map the operations that need to become tools, and design the auth model. The auth design is the step most people underestimate. Getting credentials management right before writing code saves a week of debugging later. We also determine transport type: stdio for single-user local, HTTP-with-SSE for team deployment. By the end of week one, there is a written tool spec: tool names, input schemas, expected outputs, error cases, and the hosting plan.

Week two is the build. The server is built against the tool spec, tested with real Claude sessions in Claude Desktop and Claude Code, and iterated until it behaves as expected across realistic prompts. Testing with Claude is different from unit testing: you are checking that the tool descriptions are clear enough for Claude to call them correctly without being told to, and that the error messages give Claude enough context to recover from failures. Week three is hosting, documentation, and handoff. The server goes live on the target deployment, each team member gets a config file that connects their Claude client to the server, and you receive written documentation covering the tool surface, the auth model, and how to add new tools later. Fixed fee. You own the code and the server.

Pricing and ROI

Custom MCP server builds are fixed fee, scoped during the AI Operations X-Ray. Hosting a lightweight MCP server runs under $40/mo on a small VM or Cloudflare Workers -- that is infrastructure the team pays directly, not a recurring Moore IQ fee. The ROI case is straightforward: every AI use case your team builds that connects to the same data source ships in days instead of weeks, because the integration work is already done. A content agency that invests in an Ahrefs and Google Ads MCP server gets not just one faster workflow, but every future workflow that touches those two sources for free. Run the free AI Operations X-Ray to see which data sources in your stack would benefit most from a custom MCP integration.

What you own at the end

At handoff, you receive the MCP server codebase (TypeScript or Python, your choice), the deployment configuration, the hosting setup (on your infrastructure or your cloud account), and a Claude Desktop and Claude Code config file for each team member. The documentation covers the full tool surface: what each tool does, what parameters it accepts, what it returns, and how to add a new tool to the server when your needs change.

If you fire Moore IQ the day after handoff, the server keeps running. The code is yours with no license restrictions. Your team can modify it, extend it, or hand it to another developer. There is no vendor lock-in to Moore IQ or to any proprietary infrastructure. The server speaks the open MCP protocol and will continue working as long as the protocol is supported, which, given Anthropic’s investment in it and the broader ecosystem adoption, is not a near-term concern.

Want to know which of your data sources is worth connecting first? Run the free AI Operations X-Ray and get a ranked list of your highest-value automation opportunities in 90 seconds.

Related posts

• Your first custom MCP server: when is it actually worth building?
• MCP vs REST vs function calling: a practical decision guide for 2026
• How a content agency built an Ahrefs and Google Ads MCP server in 9 days

Case studies

• SEO content engine

Related services

• Claude Code for teams
• n8n consulting

Official resources

• modelcontextprotocol.io (official MCP site)
• MCP specification
• Anthropic MCP documentation
• TypeScript SDK (modelcontextprotocol/typescript-sdk)
• Python SDK (modelcontextprotocol/python-sdk)
• Claude Code MCP usage documentation