Draft

Build a TypeScript MCP Server for a Real API, Test It with Inspector, and Call It from Claude Code

  • Not yet verified
  • Versions not pinned
  • 1 min read

Task

What you will complete

Implement the server, pass Inspector, then call it from Claude Code to finish a real API task.

Success criteria

  • The server builds and MCP Inspector accepts the tool the task needs.
  • Claude Code calls that same server build and finishes a task against the real API.
  • The evidence section can show the Inspector result, the tool call, and the pinned versions.

What this is not

Not a mock API, and not a server that is only demonstrated inside Inspector.

Prerequisites

  • Node.js and a TypeScript toolchain for the server.
  • A real HTTP API you are allowed to call, plus credentials for it.
  • Claude Code, and MCP Inspector available on the same machine.

Environment

Not recorded. A verified revision will list the operating system, the tool builds, and the model identifiers that were present for the run.

1. Choose a real API and one task

Pick an API you are allowed to call and a task that needs one real request. A fixture that never leaves the machine does not meet the task. Decide now which parts of the response you are willing to publish, and redact secrets before they reach this page.

2. Implement the TypeScript MCP server

Build a server that exposes the tool the task needs. The sketch below is not that server. It has not been typechecked or run.

export const plannedTool = {
  name: "call-the-real-api",
  purpose: "The one API request the task needs.",
};

3. Pass Inspector

Run MCP Inspector against the server you built. Keep the session result, including any schema error you had to fix. A typecheck is not a substitute for Inspector.

Planned command. Not run for this draft.

# The verified page will pin the exact Inspector package version and paste its result.
npx @modelcontextprotocol/inspector

4. Call the server from Claude Code

Connect Claude Code to the same server build Inspector passed. Ask it to finish the API task. Save the tool call and the API result you are allowed to publish.

5. Put Inspector and the task result in evidence

The verified page will show the Inspector result, the Claude Code tool call, the pinned package versions, and a link to the server repository. This draft has none of those.

Evidence it actually ran

This is the shape of the stamp. It has not been earned, and the example date that follows is a placeholder, not a run: Ran on YYYY-MM-DD (Asia/Shanghai) with the pinned versions.

Command output
None recorded. A verified revision will quote the output from the run, not a sample written in advance.
Tests, CI, or Inspector
Not run for this draft.
Repository or config
No link recorded.

Failure modes

Anticipated only. None of these has been checked against a run of this tutorial.

  • Unchecked

    Inspector reports a schema error the typechecker missed

    A compiling server can still present a tool schema Inspector rejects.

  • Unchecked

    Claude Code connects to a stale build

    The process Claude Code starts can be an older build than the one Inspector just passed.

  • Unchecked

    The API call works in Inspector and fails with Claude Code's credentials

    The two clients can be holding different secrets or a different working directory.

Other tutorials in Integrate.