How to Build a Claude MCP Server for Your API in 30 Minutes
TL;DR: Turn any OpenAPI-spec'd API into a Claude-accessible tool using the MCP Generator. This tutorial walks through creating a Model Context Protocol server that lets Claude Desktop interact with your API directly — no manual tool definitions needed.
What We're Building
By the end of this guide, you'll have:
- A working MCP server that exposes your API to Claude Desktop
- Automatic tool generation from your OpenAPI/Swagger spec
- Claude able to call your API endpoints conversationally
This is huge for solo builders. Instead of building yet another web UI, you can let Claude be your interface.
I discovered this after the recent Claude 3.5 Sonnet outage made me rethink my architecture. Having Claude available through Vertex AI as a backup is smart, but making your APIs Claude-accessible from day one? That's the real move.
Prerequisites
Before we start, make sure you have:
# Node.js 18+ installed
node --version # Should be 18.0.0 or higher
# Claude Desktop installed
# Download from: https://claude.ai/download
# An API with an OpenAPI spec (Swagger)
# Can be local or hosted - we'll use a sample weather API
You'll also need basic familiarity with:
- REST APIs and JSON
- Command line basics
- Where Claude Desktop stores its config (we'll cover this)
Step 1: Get Your OpenAPI Spec Ready
First, you need an OpenAPI specification for your API. If you don't have one, here's a minimal example you can use to follow along:
{
"openapi": "3.0.0",
"info": {
"title": "Weather API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.weather.example.com"
}
],
"paths": {
"/weather": {
"get": {
"summary": "Get current weather",
"parameters": [
{
"name": "city",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Weather data",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"temperature": {"type": "number"},
"conditions": {"type": "string"}
}
}
}
}
}
}
}
}
}
}
Save this as weather-api.json in a new project directory.
Step 2: Generate Your MCP Server
Navigate to the MCP Generator at https://mcp.liblab.com/
Here's what to do:
-
Upload your OpenAPI spec - Drag and drop
weather-api.jsonor paste the URL if it's hosted -
Configure the server name - Use something descriptive like
weather-mcp - Click Generate - The tool creates a complete MCP server implementation
Download the generated ZIP file and extract it to your project directory.
# Your directory should now look like this:
weather-mcp/
├── package.json
├── src/
│ └── index.ts
├── tsconfig.json
└── README.md
Step 3: Install Dependencies and Build
The generated server comes with everything configured. Just install and build:
cd weather-mcp
npm install
npm run build
This compiles the TypeScript to JavaScript and prepares your MCP server for use.
Step 4: Configure Claude Desktop
This is where it gets real. Claude Desktop needs to know about your MCP server.
Find your Claude config file:
-
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json -
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Edit it to add your MCP server:
{
"mcpServers": {
"weather": {
"command": "node",
"args": [
"/absolute/path/to/weather-mcp/dist/index.js"
]
}
}
}
Critical: Use the absolute path. Relative paths will fail silently and you'll waste 20 minutes debugging. Ask me how I know.
Step 5: Restart Claude Desktop
Completely quit Claude Desktop (not just close the window) and reopen it.
You should see your MCP server listed in the bottom-left corner. If you don't see it, check the logs:
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log
# Windows
# Check Event Viewer or the Claude logs folder
Step 6: Test It Out
Open a new conversation in Claude and try:
Can you check the weather in Seattle using the weather API?
Claude should recognize the available tool and call your API. You'll see the tool execution in the conversation.
If Claude doesn't see your tools, the MCP server might not be starting. Check that your OpenAPI spec has clear descriptions — Claude uses these to understand when to use each tool.
Common Gotchas
"Claude doesn't see my tools"
- Verify the absolute path in your config
- Check that
npm run buildcompleted without errors - Restart Claude Desktop completely (quit from menu bar/system tray)
"MCP server crashes on startup"
- Check Node version:
node --version(needs 18+) - Look for missing environment variables your API needs
- Verify the OpenAPI spec is valid JSON
"API calls fail with authentication errors"
The MCP Generator creates servers that pass through auth, but you need to configure it. Add environment variables to your Claude config:
{
"mcpServers": {
"weather": {
"command": "node",
"args": ["/absolute/path/to/weather-mcp/dist/index.js"],
"env": {
"API_KEY": "your-api-key-here"
}
}
}
}
"It worked yesterday, now it doesn't"
Check https://status.anthropic.com/. The recent Sonnet outage taught me to always have a backup plan. Consider deploying Claude via Vertex AI for production apps — it's not affected by Anthropic's infrastructure issues.
Full Code
Here's a complete working example with a mock API server you can run locally:
mock-api.js (run this in a separate terminal):
const express = require('express');
const app = express();
app.get('/weather', (req, res) => {
const city = req.query.city;
res.json({
temperature: Math.random() * 30 + 50,
conditions: ['Sunny', 'Cloudy', 'Rainy'][Math.floor(Math.random() * 3)],
city: city
});
});
app.listen(3000, () => console.log('Mock API running on port 3000'));
OpenAPI spec (weather-api-local.json):
{
"openapi": "3.0.0",
"info": {
"title": "Local Weather API",
"version": "1.0.0",
"description": "Get weather information for any city"
},
"servers": [
{
"url": "http://localhost:3000"
}
],
"paths": {
"/weather": {
"get": {
"summary": "Get current weather for a city",
"description": "Returns temperature and conditions for the specified city",
"operationId": "getWeather",
"parameters": [
{
"name": "city",
"in": "query",
"description": "Name of the city to get weather for",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"temperature": {
"type": "number",
"description": "Temperature in Fahrenheit"
},
"conditions": {
"type": "string",
"description": "Weather conditions"
},
"city": {
"type": "string",
"description": "City name"
}
}
}
}
}
}
}
}
}
}
}
Run the mock API:
npm install express
node mock-api.js
Generate your MCP server using the local OpenAPI spec, then test with Claude.
Next Steps
Now that you have MCP working, here are some power moves:
1. Add your production APIs
- PC Health app? Expose system diagnostics to Claude
- Legal AI? Let Claude search case law through your API
- KidTalk? Make child safety checks available conversationally
2. Chain multiple MCP servers
Claude can use multiple MCP servers simultaneously. Add your database API, your email API, your analytics API — let Claude orchestrate them.
3. Build reliability in
The recent Claude outage was a wake-up call. If you're building production apps:
- Deploy Claude via Vertex AI as a backup
- Cache API responses when possible
- Add fallback modes that work without Claude
4. Use visual tools for faster iteration
I've been testing Piny (https://getpiny.com) for Next.js development. Having a visual editor in VSCode speeds up UI work while Claude handles the API logic. They complement each other well.
5. Think in agents
Listen to the Changelog podcast episode on "Building the machine that builds the machine" — it covers real patterns for agentic engineering that apply directly to MCP development.
The future isn't just "AI that writes code." It's AI that directly manipulates your infrastructure through well-defined interfaces. MCP is how we get there.
Did this work for you? Drop a comment if you run into issues.
Top comments (0)