I Built MCP Servers for 9 SaaS APIs — Here's What I Learned About the Pattern
I've spent the last few weeks building MCP (Model Context Protocol) servers for various APIs — CoinGecko, Stripe, Jira, PostHog, Plausible, Etherscan, DeFiLlama, Jobber, and Resend. Nine servers, 68 tools, all published to npm and indexed on Glama.
Along the way, I noticed the same architecture keeps working. If you're building an MCP server for your own API — or thinking about hiring someone to do it — here's the pattern.
The Three-Layer Architecture
Every MCP server I build has three layers:
1. Tool Definitions (the contract)
Each API endpoint becomes an MCP tool with a typed input schema. I use Zod for validation — it catches bad inputs before they hit your API.
{
name: "send_email",
description: "Send a single email via Resend",
inputSchema: {
from: z.string().email(),
to: z.union([z.string().email(), z.array(z.string().email())]),
subject: z.string().min(1),
html: z.string().optional(),
text: z.string().optional(),
},
}
The description matters more than you think. LLMs read these descriptions to decide which tool to call. A vague description like "send email" wastes tokens. A specific one like "Send a single transactional email via Resend API. Supports HTML and plain text. Returns message ID and delivery status." gets used correctly.
2. API Client (the plumbing)
This layer handles auth, rate limiting, and error transformation. The key insight: don't leak HTTP errors to the LLM. Transform them into structured, actionable messages.
// Bad: "Error: 429"
// Good: "Rate limited by Resend API. Retry after 30 seconds. You've sent 100 emails in the last hour."
3. Output Formatter (the presentation)
Raw JSON dumps are terrible for LLM consumption. Format responses as markdown tables, bullet points, or structured text. The LLM reads this output to decide what to do next — make it scannable.
## Email Sent Successfully
- **Message ID:** abc123
- **From:** alerts@yourcompany.com
- **To:** user@example.com
- **Subject:** Your weekly report
- **Status:** Queued for delivery
The Patterns That Keep Working
Mock Mode
Every server includes a mock mode that returns realistic fake data. This lets developers test without live API credentials. It's also how I test during development — no API keys needed.
Progressive Disclosure
Don't dump all 18 tools on the LLM at once if it only needs 3. Group tools by use case. The Resend server has tools for emails, contacts, domains, and API keys — a developer sending an email doesn't need to see the domain management tools.
Error Recovery
APIs fail. Networks timeout. Rate limits hit. The server should handle retries internally and surface clear "try again" instructions to the LLM, not raw stack traces.
What I Deliver
When someone commissions an MCP server from me, they get:
- TypeScript MCP server with full tool definitions
- Input validation via Zod schemas
- Error handling with structured messages
- Clean markdown output optimized for LLM consumption
- Mock mode for testing without credentials
-
npm publication under their scope (e.g.,
@yourcompany/mcp-server) - Glama/directory listing for discoverability
- README with install instructions and tool catalog
Typical turnaround: 1-3 days for standard REST APIs.
Why This Matters
MCP is becoming the standard way AI assistants connect to external services. Claude Desktop, Cursor, Windsurf, and other clients all support it. But most SaaS APIs don't have MCP servers yet. That gap means:
- Developers waste time switching between AI assistants and API dashboards
- APIs miss distribution — being in an MCP directory is like being in an app store
- The first mover wins — once an MCP server exists for an API, there's little reason to build a second one
Get in Touch
If your API needs an MCP server, I can build it. My portfolio includes servers for crypto (CoinGecko, Etherscan, DeFiLlama), analytics (PostHog, Plausible), project management (Jira, Jobber), payments (Stripe), and email (Resend).
GitHub: github.com/friendlygeorge
Tell me which API you need connected. I'll scope it and give you a timeline within 24 hours.
This post is part of my build-in-public series on shipping AI tools. Previous posts covered building 10 MCP servers in a week and how to build an MCP server that actually gets used.