Build an MCP Server for an Internal API

1. Pick tools, not endpoints

第一步：按任务设计工具，而不是照搬端点

The model reads every tool name, description and schema on every turn, so a tool list should look like the jobs people ask for, not like your route table. Our example is an internal helpdesk with three routes:

Rules that hold up on real internal APIs:

• Start read-only. Ship search and get tools first; add one write tool once you trust the setup. Leave delete and bulk operations out.
• Hide plumbing. Auth headers, tenant IDs, pagination cursors and API versions belong in the server, never in tool parameters.
• Write descriptions for the model. “Ticket ID, e.g. T-1042” tells it the format; “id” makes it guess.
• Keep it to roughly 3–15 tools. If you need dozens and already have a spec, read form generator vs OpenAPI→MCP tools.

2. Generate the scaffold

第二步：生成项目骨架

Open the generator form, name the server helpdesk-api, and enter the three tools from the table (untick required on status). Pick TypeScript or Python and download the ZIP. You get a project where every tool is registered with its schema and the handler is a placeholder:

src/index.ts as generated (one tool shown)

server.registerTool(
  "search_tickets",
  {
    description: "Search internal support tickets by keyword and optional status",
    inputSchema: z.object({
    query: z.string().describe("Keywords to match in the ticket title"),
    status: z.string().describe("open, pending or closed").optional()
  }),
  },
  async ({ query, status }) => {
    // TODO: replace this placeholder with real logic for search_tickets
    const text = "[search_tickets] " + "query=" + JSON.stringify(query) + ", " + "status=" + JSON.stringify(status);
    return {
      content: [{ type: "text", text }],
    };
  }
);

Everything else in the scaffold (McpServer, StdioServerTransport, package.json, the README host config) stays as it is. The template guide explains each generated file. The next step replaces the TODOs with real HTTP calls.

3a. TypeScript: call the internal API

第三步（TypeScript）：调用内部 API

Add an api() helper below the McpServer constructor and point each handler at it. Node 18+ has fetch built in, so there are no new dependencies. This is the complete, tested file:

src/index.ts

#!/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 server = new McpServer({
  name: "helpdesk-api",
  version: "1.0.0",
});

// --- internal API client: one place for base URL, auth, timeout, errors ---
const API_URL = process.env.HELPDESK_API_URL;
const API_TOKEN = process.env.HELPDESK_API_TOKEN;
if (!API_URL || !API_TOKEN) {
  console.error("Set HELPDESK_API_URL and HELPDESK_API_TOKEN");
  process.exit(1);
}

async function api(method: string, path: string, body?: unknown): Promise<unknown> {
  const res = await fetch(API_URL + path, {
    method,
    headers: {
      Authorization: `Bearer ${API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(10_000),
  });
  if (!res.ok) {
    throw new Error(`${method} ${path} failed: HTTP ${res.status}`);
  }
  return res.json();
}

// Wrap a call so failures come back as a tool error the model can read.
async function asTool(call: () => Promise<unknown>) {
  try {
    const data = await call();
    const text = JSON.stringify(data, null, 2).slice(0, 20_000);
    return { content: [{ type: "text" as const, text }] };
  } catch (err) {
    return {
      content: [{ type: "text" as const, text: String(err) }],
      isError: true,
    };
  }
}

server.registerTool(
  "search_tickets",
  {
    description: "Search internal support tickets by keyword and optional status",
    inputSchema: z.object({
      query: z.string().describe("Keywords to match in the ticket title"),
      status: z.string().describe("open, pending or closed").optional(),
    }),
  },
  async ({ query, status }) => {
    const params = new URLSearchParams({ q: query });
    if (status) params.set("status", status);
    return asTool(() => api("GET", `/tickets?${params}`));
  }
);

server.registerTool(
  "get_ticket",
  {
    description: "Get one ticket with status, assignee and latest comments",
    inputSchema: z.object({
      ticket_id: z.string().describe("Ticket ID, e.g. T-1042"),
    }),
  },
  async ({ ticket_id }) =>
    asTool(() => api("GET", `/tickets/${encodeURIComponent(ticket_id)}`))
);

server.registerTool(
  "add_ticket_comment",
  {
    description: "Add an internal comment to a ticket",
    inputSchema: z.object({
      ticket_id: z.string().describe("Ticket ID, e.g. T-1042"),
      body: z.string().describe("Comment text"),
    }),
  },
  async ({ ticket_id, body }) =>
    asTool(() =>
      api("POST", `/tickets/${encodeURIComponent(ticket_id)}/comments`, { body })
    )
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("helpdesk-api MCP server running on stdio");
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

• Config comes from the environment. The server exits at startup with a message on stderr if HELPDESK_API_URL or HELPDESK_API_TOKEN is missing, which shows up in the host's MCP log.
• asTool() turns failures into isError: true results like Error: GET /tickets/T-9999 failed: HTTP 404, so the model can tell the user, or retry with a different ID, instead of the call failing silently.
• encodeURIComponent keeps a model-supplied ID from changing the path, and the output is capped at 20,000 characters so one big record cannot flood the context.

3b. Python: call the internal API

第三步（Python）：调用内部 API

Add httpx to requirements.txt (and to dependencies in pyproject.toml if you launch with uv):

requirements.txt

mcp>=2.0.0
httpx>=0.27

Then switch the generated functions to async def and route them through one helper:

server.py

"""MCP server for the internal helpdesk API"""

import json
import os
from urllib.parse import quote

import httpx
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("helpdesk-api", version="1.0.0")

# --- internal API client: one place for base URL, auth, timeout, errors ---
API_URL = os.environ["HELPDESK_API_URL"]
API_TOKEN = os.environ["HELPDESK_API_TOKEN"]


async def api(method: str, path: str, **kwargs) -> str:
    try:
        async with httpx.AsyncClient(
            base_url=API_URL,
            headers={"Authorization": f"Bearer {API_TOKEN}"},
            timeout=10.0,
        ) as client:
            r = await client.request(method, path, **kwargs)
    except httpx.HTTPError as exc:
        raise ToolError(f"{method} {path} failed: {exc}") from exc
    if r.is_error:
        # ToolError -> isError: true with this message; other exceptions are hidden.
        raise ToolError(f"{method} {path} failed: HTTP {r.status_code}")
    return json.dumps(r.json(), indent=2)[:20_000]


@mcp.tool()
async def search_tickets(query: str, status: str = "") -> str:
    """Search internal support tickets by keyword and optional status

    Args:
        query: Keywords to match in the ticket title
        status: open, pending or closed
    """
    params = {"q": query}
    if status:
        params["status"] = status
    return await api("GET", "/tickets", params=params)


@mcp.tool()
async def get_ticket(ticket_id: str) -> str:
    """Get one ticket with status, assignee and latest comments

    Args:
        ticket_id: Ticket ID, e.g. T-1042
    """
    return await api("GET", f"/tickets/{quote(ticket_id, safe='')}")


@mcp.tool()
async def add_ticket_comment(ticket_id: str, body: str) -> str:
    """Add an internal comment to a ticket

    Args:
        ticket_id: Ticket ID, e.g. T-1042
        body: Comment text
    """
    return await api("POST", f"/tickets/{quote(ticket_id, safe='')}/comments", json={"body": body})


if __name__ == "__main__":
    mcp.run()

• Raise ToolError, not a plain exception. In mcp 2.x a ToolError message reaches the model (Error executing tool get_ticket: GET /tickets/T-9999 failed: HTTP 404). Any other exception is treated as a crash, and the model only sees Error executing tool get_ticket.
• Network failures are caught too (httpx.HTTPError), so a VPN that is down reads as “All connection attempts failed” rather than a generic error.
• On mcp 1.x, import FastMCP from mcp.server.fastmcp instead of MCPServer; the decorators are the same.

4. Pass the URL and token through the host config

第四步：通过主机配置传入地址和令牌

Claude Desktop and Cursor both accept an env object per server. Start from the absolute-path config in the generated README and add it:

claude_desktop_config.json or .cursor/mcp.json

{
  "mcpServers": {
    "helpdesk-api": {
      "command": "/absolute/path/to/helpdesk-api/node_modules/.bin/tsx",
      "args": ["/absolute/path/to/helpdesk-api/src/index.ts"],
      "env": {
        "HELPDESK_API_URL": "https://helpdesk.internal.example.com/api",
        "HELPDESK_API_TOKEN": "paste-a-scoped-token-here"
      }
    }
  }
}

For Python, use .venv/bin/python and server.py as command and args, with the same env block. The server runs on your machine, so it reaches the API over whatever network you are on: if the API sits behind a VPN, the VPN has to be up. Config file locations and fixes for servers that do not appear are in connect an MCP server to Claude Desktop and Cursor.

5. Test before you connect a host

第五步：接入主机前先测试

# TypeScript
HELPDESK_API_URL=https://helpdesk.internal.example.com/api \
HELPDESK_API_TOKEN=... \
npx @modelcontextprotocol/inspector npm start

# Python
HELPDESK_API_URL=https://helpdesk.internal.example.com/api \
HELPDESK_API_TOKEN=... \
npx @modelcontextprotocol/inspector .venv/bin/python server.py

In the Inspector, call each tool with a good input, an ID that does not exist, and a wrong token. In our run, both servers returned the matching ticket for search_tickets with {"query": "vpn", "status": "open"}, an isError result with the HTTP status for a 404 and a 401, and a readable error when the API was unreachable. If a tool only works on the happy path, the model will hit the other paths first.

Security checklist for internal APIs

内部 API 安全清单

• Use a dedicated, least-privilege token, read-only if you can. The model can call any tool you register, with any arguments it chooses.
• Keep the config file out of git. The token in env is stored in plain text in that file.
• Treat write tools as actions. Claude Desktop and Cursor can ask you to approve each tool call; keep approval on for tools like add_ticket_comment instead of auto-running them.
• Trim responses. Return only the fields the task needs, and drop personal data the model has no reason to see.
• Never print to stdout. stdout carries the protocol; log with console.error or to stderr.

FAQ

常见问题