How to build an MCP server that wraps an external API

1// TypeScript
2const API_BASE = process.env.API_BASE_URL || "https://api.example.com/v1";
3const API_KEY = process.env.API_KEY;
4
5if (!API_KEY) {
6  console.error("Error: API_KEY environment variable required");
7  process.exit(1);
8}
9
10async function apiRequest<T>(
11  path: string,
12  options: {
13    method?: string;
14    body?: unknown;
15    params?: Record<string, string>;
16  } = {}
17): Promise<T> {
18  const url = new URL(path, API_BASE);
19  if (options.params) {
20    Object.entries(options.params).forEach(([k, v]) =>
21      url.searchParams.set(k, v)
22    );
23  }
24
25  const response = await fetch(url.toString(), {
26    method: options.method || "GET",
27    headers: {
28      "Authorization": `Bearer ${API_KEY}`,
29      "Content-Type": "application/json",
30    },
31    body: options.body ? JSON.stringify(options.body) : undefined,
32  });
33
34  if (!response.ok) {
35    const errorText = await response.text();
36    throw Object.assign(new Error(`HTTP ${response.status}: ${errorText}`), {
37      status: response.status,
38    });
39  }
40
41  return response.json();
42}

1// TypeScript
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { z } from "zod";
4
5const server = new McpServer({ name: "api-wrapper", version: "1.0.0" });
6
7// GET endpoint → MCP tool
8server.registerTool("list-projects", {
9  description: "List all projects with optional status filter. Returns project names, IDs, and statuses.",
10  inputSchema: {
11    status: z.enum(["active", "archived", "all"]).default("active")
12      .describe("Filter by project status"),
13    page: z.number().int().min(1).default(1).describe("Page number"),
14    perPage: z.number().int().min(1).max(100).default(20)
15      .describe("Results per page (1-100)"),
16  },
17}, async ({ status, page, perPage }) => {
18  try {
19    const data = await apiRequest<any>("/projects", {
20      params: {
21        status: status === "all" ? "" : status,
22        page: String(page),
23        per_page: String(perPage),
24      },
25    });
26    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
27  } catch (error) {
28    return {
29      content: [{ type: "text", text: `Error: ${(error as Error).message}` }],
30      isError: true,
31    };
32  }
33});
34
35// POST endpoint → MCP tool
36server.registerTool("create-project", {
37  description: "Create a new project. Returns the created project object.",
38  inputSchema: {
39    name: z.string().min(1).max(100).describe("Project name"),
40    description: z.string().max(500).optional().describe("Project description"),
41  },
42}, async ({ name, description }) => {
43  try {
44    const data = await apiRequest<any>("/projects", {
45      method: "POST",
46      body: { name, description },
47    });
48    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
49  } catch (error) {
50    return {
51      content: [{ type: "text", text: `Error: ${(error as Error).message}` }],
52      isError: true,
53    };
54  }
55});

1// TypeScript
2server.registerTool("search-items", {
3  description: "Search for items with pagination. Returns items and pagination metadata.",
4  inputSchema: {
5    query: z.string().min(1).describe("Search query"),
6    page: z.number().int().min(1).default(1).describe("Page number"),
7    perPage: z.number().int().min(1).max(50).default(20).describe("Results per page"),
8  },
9}, async ({ query, page, perPage }) => {
10  try {
11    const data = await apiRequest<{
12      items: any[];
13      total: number;
14      page: number;
15      per_page: number;
16    }>("/items/search", {
17      params: {
18        q: query,
19        page: String(page),
20        per_page: String(perPage),
21      },
22    });
23
24    const totalPages = Math.ceil(data.total / data.per_page);
25    const result = {
26      items: data.items,
27      pagination: {
28        currentPage: data.page,
29        totalPages,
30        totalItems: data.total,
31        hasNextPage: data.page < totalPages,
32      },
33    };
34
35    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
36  } catch (error) {
37    return {
38      content: [{ type: "text", text: `Error: ${(error as Error).message}` }],
39      isError: true,
40    };
41  }
42});

1// TypeScript
2async function apiRequestWithRetry<T>(
3  path: string,
4  options: { method?: string; body?: unknown; params?: Record<string, string> } = {},
5  retries = 2
6): Promise<T> {
7  for (let attempt = 0; attempt <= retries; attempt++) {
8    try {
9      return await apiRequest<T>(path, options);
10    } catch (error) {
11      const err = error as Error & { status?: number };
12
13      // Rate limited — wait and retry
14      if (err.status === 429 && attempt < retries) {
15        const waitMs = 2000 * (attempt + 1); // exponential backoff
16        console.error(`Rate limited, waiting ${waitMs}ms before retry`);
17        await new Promise(resolve => setTimeout(resolve, waitMs));
18        continue;
19      }
20
21      // Server error — retry
22      if (err.status && err.status >= 500 && attempt < retries) {
23        await new Promise(resolve => setTimeout(resolve, 1000));
24        continue;
25      }
26
27      throw error; // Non-retryable error
28    }
29  }
30  throw new Error("Max retries exceeded");
31}

1// TypeScript
2server.registerResource("api-docs", "docs://api", {
3  description: "API endpoint documentation for available tools",
4  mimeType: "text/markdown",
5}, async (uri) => ({
6  contents: [{
7    uri: uri.href,
8    text: [
9      "# Available API Operations",
10      "",
11      "## Projects",
12      "- **list-projects**: List all projects, filter by status",
13      "- **create-project**: Create a new project with name and description",
14      "- **get-project**: Get project details by ID",
15      "",
16      "## Items",
17      "- **search-items**: Full-text search with pagination",
18      "- **create-item**: Create item in a project",
19      "- **update-item**: Update item fields",
20      "",
21      "## Notes",
22      "- All list endpoints support pagination (page, perPage)",
23      "- Rate limit: 100 requests/minute",
24    ].join("\n"),
25  }],
26}));