If you already have a REST API — your own product API, a third-party service you use, or an internal microservice — you are 80% of the way to having an MCP server. The pattern for wrapping a REST API as an MCP server is generic, well-trodden, and worth knowing well, because it is the single most common way new MCP servers come into existence.

This article shows the universal pattern using a real, free, no-auth API (JSONPlaceholder) so you can run every example as-is. Then we walk through the design choices that make the difference between a technically correct wrapper and one an LLM can actually use well.

The mental model #

A REST API exposes endpoints. An MCP server exposes tools. The wrapping job is to map one to the other thoughtfully.

Naive mapping (works, but suboptimal):

This works, but it gives the LLM the exact surface of the REST API — which is shaped for code, not for natural language. A better wrapper consolidates, hides, and adds LLM-friendly shortcuts.

We will build both and compare.

Setup #

mkdir jsonplaceholder-mcp
cd jsonplaceholder-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

Add "type": "module" to package.json.

The thin wrapper (one tool per endpoint) #

Create server.js:

#!/usr/bin/env node
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const API = 'https://jsonplaceholder.typicode.com';

async function api(path, init = {}) {
  const res = await fetch(`${API}${path}`, {
    ...init,
    headers: { 'Content-Type': 'application/json', ...(init.headers || {}) },
  });
  if (!res.ok) throw new Error(`API ${res.status}: ${await res.text()}`);
  return res.status === 204 ? null : res.json();
}

const server = new McpServer({ name: 'jsonplaceholder', version: '1.0.0' });

server.tool('list_posts', 'List all posts (returns 100 entries).', {}, async () => {
  const posts = await api('/posts');
  return { content: [{ type: 'text', text: JSON.stringify(posts, null, 2) }] };
});

server.tool('get_post', 'Fetch a single post by ID.',
  { id: z.number().int().positive() },
  async ({ id }) => {
    const post = await api(`/posts/${id}`);
    return { content: [{ type: 'text', text: JSON.stringify(post, null, 2) }] };
  }
);

server.tool('create_post', 'Create a new post.',
  { title: z.string(), body: z.string(), userId: z.number().int() },
  async (args) => {
    const post = await api('/posts', { method: 'POST', body: JSON.stringify(args) });
    return { content: [{ type: 'text', text: `Created post #${post.id}` }] };
  }
);

await server.connect(new StdioServerTransport());

That is a perfectly valid MCP server. Wire it into Claude Desktop, ask "show me post 5," and it works.

But now look at the output of list_posts — 100 JSON objects with hundreds of fields. The LLM has to wade through ~50,000 tokens of noise to answer "what was the title of the most recent post?"

The thoughtful wrapper (LLM-friendly tools) #

A better wrapper does four things:

1. Trims the response to what the LLM actually needs.
2. Adds parameters that real users want (limit, search, by-user).
3. Returns text the LLM can read directly, not raw JSON the LLM has to re-parse.
4. Composes related endpoints when it makes sense (e.g., one tool that returns a post and its comments).

Here is the same API as a thoughtful wrapper:

server.tool('search_posts',
  'Search posts by keyword (matches title and body). Returns up to 10 results with summary info.',
  {
    query: z.string().describe('Keyword to match'),
    limit: z.number().int().min(1).max(50).default(10),
  },
  async ({ query, limit }) => {
    const all = await api('/posts');
    const q = query.toLowerCase();
    const hits = all
      .filter(p => p.title.toLowerCase().includes(q) || p.body.toLowerCase().includes(q))
      .slice(0, limit);
    if (!hits.length) {
      return { content: [{ type: 'text', text: `No posts found matching "${query}".` }] };
    }
    const lines = hits.map(p => `#${p.id} "${p.title}" (by user ${p.userId})`);
    return { content: [{ type: 'text', text: lines.join('\n') }] };
  }
);

server.tool('get_post_with_comments',
  'Fetch a post and all its comments in one call.',
  { id: z.number().int().positive() },
  async ({ id }) => {
    const [post, comments] = await Promise.all([
      api(`/posts/${id}`),
      api(`/posts/${id}/comments`),
    ]);
    const cText = comments.map(c => `  • ${c.email}: ${c.body}`).join('\n');
    return {
      content: [{
        type: 'text',
        text: `Post #${post.id}: ${post.title}\n\n${post.body}\n\n--- Comments (${comments.length}) ---\n${cText}`,
      }],
    };
  }
);

server.tool('posts_by_user',
  "List all posts by a specific user.",
  { userId: z.number().int().positive() },
  async ({ userId }) => {
    const posts = await api(`/users/${userId}/posts`);
    const lines = posts.map(p => `#${p.id} ${p.title}`);
    return { content: [{ type: 'text', text: lines.join('\n') || 'No posts.' }] };
  }
);

Notice the differences:

• search_posts is something the LLM actually wants. The raw API has no search; we synthesized it client-side. The LLM never has to scan 100 records itself.
• get_post_with_comments collapses two endpoints into one tool. Saves a round-trip and reads naturally as a single "give me the post" intent.
• Output is preformatted text, not raw JSON. The LLM does not have to parse it before answering the user.
• Limits and defaults make response sizes predictable.

Authentication patterns #

JSONPlaceholder needs no auth, but most real APIs do. Three common patterns:

Static API key (simplest) #

const API_KEY = process.env.API_KEY;
if (!API_KEY) throw new Error('Set API_KEY environment variable.');

async function api(path, init = {}) {
  return fetch(`${API}${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${API_KEY}`, ...init.headers },
  });
}

The user puts their key in their claude_desktop_config.json server entry as an env property:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "my-api-mcp"],
      "env": { "API_KEY": "sk_live_..." }
    }
  }
}

Per-user OAuth (more complex) #

For APIs that need per-user authorization (think: "my GitHub issues" not "the GitHub public API"), MCP supports OAuth flows via the Streamable HTTP transport. Full coverage is its own article, but the gist is: the server registers OAuth metadata, the host opens a browser, the user authorizes, and the host stores the resulting token for subsequent calls.

Personal access tokens (PATs) #

For developer-tools APIs (GitHub, GitLab, Linear), the simplest path is to ask the user for a PAT once, treat it like an API key, and document the scopes required. Less elegant than OAuth, but works everywhere.

Pagination #

APIs that paginate large result sets need careful handling. Two patterns:

Pattern A: Expose the cursor to the LLM.

server.tool('list_users',
  'List users with pagination. Pass cursor from previous response to continue.',
  { cursor: z.string().optional(), limit: z.number().int().min(1).max(100).default(20) },
  async ({ cursor, limit }) => {
    const url = `/users?limit=${limit}${cursor ? `&cursor=${cursor}` : ''}`;
    const data = await api(url);
    return {
      content: [{
        type: 'text',
        text: `${data.items.map(u => u.name).join('\n')}\n\nNext cursor: ${data.nextCursor || '(none)'}`,
      }],
    };
  }
);

Pattern B: Auto-paginate up to a sensible cap.

server.tool('list_all_users',
  'List up to the first 500 users.',
  {},
  async () => {
    const all = [];
    let cursor;
    while (all.length < 500) {
      const data = await api(`/users?limit=100${cursor ? `&cursor=${cursor}` : ''}`);
      all.push(...data.items);
      if (!data.nextCursor) break;
      cursor = data.nextCursor;
    }
    return { content: [{ type: 'text', text: all.map(u => u.name).join('\n') }] };
  }
);

Pattern B is more LLM-friendly (no cursor juggling), but you must enforce a cap to prevent runaway calls.

Error normalization #

A real REST API can fail in dozens of ways — 4xx, 5xx, network timeouts, rate limits. Translate them into responses the LLM can act on:

async function safeApi(path, init = {}) {
  try {
    const res = await fetch(`${API}${path}`, init);
    if (res.status === 429) return { error: 'Rate limit hit. Please retry in a minute.' };
    if (res.status === 404) return { error: 'Not found.' };
    if (!res.ok) return { error: `API error ${res.status}: ${await res.text()}` };
    return { data: await res.json() };
  } catch (err) {
    return { error: `Network error: ${err.message}` };
  }
}

server.tool('get_post', 'Fetch a post by ID.',
  { id: z.number().int().positive() },
  async ({ id }) => {
    const r = await safeApi(`/posts/${id}`);
    if (r.error) return { content: [{ type: 'text', text: r.error }], isError: true };
    return { content: [{ type: 'text', text: JSON.stringify(r.data, null, 2) }] };
  }
);

The LLM reads the friendly error and can decide whether to retry, ask the user, or apologize gracefully.

Design checklist #

Before you publish a REST-API-backed MCP server, ask yourself:

Conclusion #

Wrapping a REST API as an MCP server is one of the highest-leverage patterns in the entire MCP ecosystem. Every internal service in your company, every SaaS your team uses, every API you have ever written documentation for — all of them can be exposed to any AI assistant with a few hundred lines of glue.

The trick is to resist the urge to expose the API one-to-one. Build the wrapper for the LLM that will use it, not for the developer who wrote the REST docs. Consolidate related calls, hide low-value endpoints, preformat responses, and add the conveniences the LLM actually wants.

Do that, and you will have an MCP server that feels native — not a transliteration of a REST API into JSON-RPC.

Try it yourself #

With the thoughtful version of the JSONPlaceholder wrapper connected, the LLM can answer real questions instead of dumping raw JSON:

The naive list_posts wrapper would have returned all 100 posts and the LLM would have had to scan them itself — chewing through tokens. The thoughtful search_posts tool did the filtering server-side and returned a clean summary.