DEV Community

Cover image for How to Connect Claude to Any REST API in 2 Minutes (Step-by-Step Guide)
Docat
Docat

Posted on

How to Connect Claude to Any REST API in 2 Minutes (Step-by-Step Guide)

#ai #tutorial #beginners #api

What if you could ask Claude "What's my Stripe MRR this month?" and get a real number back — not a hallucinated guess, but an actual API response?

Or ask "What's the current Bitcoin price?" and have Claude fetch it from CoinGecko, live, right inside your chat window?

This isn't a hypothetical. It takes about 2 minutes to set up, and you don't need to write a single line of code. I'll walk you through the entire process.

The Problem: Claude Is Smart But Isolated

Claude can write code, analyze documents, explain quantum physics. But ask it anything that requires live data — your server metrics, your payment dashboard, today's crypto prices — and it has to make something up. It literally can't reach the outside world.

This is the biggest gap between "impressive demo" and "actually useful tool." You want Claude to be your assistant, not just your chatbot.

The Solution: MCP (One Sentence Version)

MCP (Model Context Protocol) is an open standard that lets Claude call external tools — including REST APIs — directly from the chat interface. Think of it as giving Claude hands to reach out and touch your APIs.

You don't need to understand the protocol. You just need to point it at an API spec and let it work.

Step-by-Step Setup

Prerequisites

That's it. No Python, no Docker, no cloud accounts.

Step 1: Find Your Config File

Claude Desktop stores its MCP configuration in a JSON file. Open it:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json
Enter fullscreen mode Exit fullscreen mode

Windows:

%APPDATA%\Claude\claude_desktop_config.json
Enter fullscreen mode Exit fullscreen mode

If the file doesn't exist, create it. If it's empty, start with {}.

Step 2: Add One Block of JSON

Let's start with the Petstore API — a free, public API that everyone can access. Paste this into your config file:

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Save the file and restart Claude Desktop.

Step 3: Ask Claude Something

Open a new conversation and type:

"List all available pets in the store"

Claude will discover tools like find_pets_by_status, get_pet_by_id, and add_pet — generated automatically from the API's OpenAPI spec. It calls the API, gets real data back, and shows you the result.

That's the whole setup. One JSON block, one restart, done.

3 Real Examples You Can Try Right Now

Example 1: Petstore (Beginner-Friendly)

The Petstore API is the "Hello World" of REST APIs. Perfect for testing.

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Try asking:

  • "Find all pets with status 'available'"
  • "Get details for pet ID 1"
  • "What endpoints does the Petstore API have?"

Example 2: CoinGecko (Crypto Prices)

CoinGecko has a free API with no auth required. Add this alongside the petstore block:

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    },
    "coingecko": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://www.coingecko.com/api/documentations/v3/swagger.json"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Try asking:

  • "What's the current price of Bitcoin in USD?"
  • "Show me the top 10 cryptocurrencies by market cap"
  • "What's the 24-hour price change for Ethereum?"

Example 3: Any Public API With an OpenAPI Spec

The pattern works with any API that publishes an OpenAPI/Swagger spec. Here are some you can try:

API Spec URL
JSONPlaceholder https://jsonplaceholder.typicode.com/openapi.json
httpbin https://httpbin.org/spec.json
Your own API Any URL or local file path to a .json or .yaml spec

For authenticated APIs (like Stripe or GitHub), add a header:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://api.example.com/openapi.json",
        "--header", "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Replace YOUR_API_KEY with your actual key. This works for any API that uses Bearer tokens, API keys in headers, or basic auth.

Common Mistakes (and How to Fix Them)

"Claude doesn't see any tools"

Cause: You didn't restart Claude Desktop after editing the config file.
Fix: Fully quit and reopen Claude Desktop. On Mac, use Cmd+Q — just closing the window isn't enough.

"npx command not found"

Cause: Node.js isn't installed, or it's not in your PATH.
Fix: Install Node.js 18+ from nodejs.org. On Mac, if you installed via Homebrew, you may need to specify the full path:

{
  "command": "/usr/local/bin/npx",
  "args": ["mcp-openapi", "--spec", "..."]
}
Enter fullscreen mode Exit fullscreen mode

"The API returns errors"

Cause: The spec URL is wrong, or the API requires authentication you haven't provided.
Fix: Open the spec URL in your browser first — you should see a JSON or YAML file. If the API needs auth, add the --header flag as shown in Example 3.

"Claude calls the API but the response is gibberish"

Cause: Some APIs return massive responses that flood Claude's context window.
Fix: mcp-openapi already applies smart truncation by default (slicing arrays to 20 items and capping nesting at 5 levels). If you're still seeing issues, the API might be returning HTML instead of JSON — check the spec URL.

"Can I use this with Claude Code (the CLI), not just Claude Desktop?"

Yes. In Claude Code, MCP servers are configured in your project's .mcp.json file instead:

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Same format, different file location.

How This Actually Works (Optional Deep Dive)

If you're curious about what happens behind the scenes:

  1. npx mcp-openapi downloads and runs the tool — no global install needed
  2. It fetches the OpenAPI spec from the URL you provided
  3. It parses every endpoint and generates an MCP tool for each one
  4. Parameters are flattened into a simple key-value format (instead of nested JSON) — this dramatically reduces LLM hallucination on parameter names
  5. Claude Desktop connects to the MCP server via stdio and discovers all available tools
  6. When you ask a question, Claude picks the right tool, fills in the parameters, and calls the API
  7. The response is truncated intelligently so it fits in Claude's context window without losing important information

If you want to go deeper on why flat schemas matter for LLMs, I wrote a detailed breakdown here: 3 Patterns That Fix LLM API Calling.

Next Steps

Once you've got Claude talking to APIs, you'll want to optimize how you instruct it. Instruction files (like CLAUDE.md) let you set persistent rules so Claude uses your APIs the way you want — every time, without repeating yourself.

I covered the 5 most useful patterns here: 5 Instruction File Patterns I Wish I Knew from Day 1.

What API are you going to connect Claude to first? I've seen people wire up everything from internal dashboards to smart home controllers. Drop your use case in the comments — I reply to every one.

If you want pre-built MCP setups for Stripe and crypto tracking, I sell them at docat.gumroad.com.

Top comments (0)