Build a small MCP server in TypeScript

The Model Context Protocol lets servers expose tools that language models can invoke. Each tool has a unique name, a description and an inputSchema in JSON Schema; clients discover tools with a tools/list request and run one with tools/call ¹. Tool names should be 1 to 128 characters of letters, digits, underscore, hyphen or dot ¹.

Two kinds of failure exist. A protocol error, such as an unknown tool, is a JSON-RPC error. A tool execution error, such as an API failure, is a normal result with isError: true so the model can read it and adjust ¹. Your tool should use the second kind when the lookup fails.

The official TypeScript SDK is the package @modelcontextprotocol/sdk, and it needs zod installed beside it as a peer dependency ². We ran the server below against SDK version 1.32.1 and zod 4.

1npm install @modelcontextprotocol/sdk zod

The SDK builds a server with McpServer and connects it to a transport such as stdio ². The tool below registers one tool with registerTool and a zod inputSchema, connects over standard input and output with StdioServerTransport, and calls our REST endpoint with fetch. Because stdout carries the protocol, the server logs with console.error; one stray console.log would corrupt the stream.

1import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
3import * as z from 'zod/v4';
4​
5const server = new McpServer({ name: 'phone-check', version: '1.0.0' });
6​
7server.registerTool(
8  'validate_phone',
9  {
10    description: 'Check a phone number against its numbering plan and return E.164, country and number type.',
11    inputSchema: { phone: z.string() },
12  },
13  async ({ phone }) => {
14    const res = await fetch('https://YOUR_API_HOST/v1/phone', {
15      method: 'POST',
16      headers: {
17        Authorization: 'Bearer ' + process.env.LOOKVALID_API_KEY,
18        'Content-Type': 'application/json',
19      },
20      body: JSON.stringify({ phone }),
21    });
22    const body = await res.json();
23    if (!res.ok) {
24      return { content: [{ type: 'text', text: 'LookValid error: ' + body.error.code }], isError: true };
25    }
26    return { content: [{ type: 'text', text: JSON.stringify(body.found ? body.data : { found: false, reason: body.reason }) }] };
27  },
28);
29​
30async function main() {
31  const transport = new StdioServerTransport();
32  await server.connect(transport);
33  console.error('phone-check MCP server running on stdio');
34}
35main();

The handler returns a content array with a text item, which is the result shape in the specification ¹. On failure it sets isError: true, the tool execution error described above ¹.

The REST call can be tested on its own before you wrap it.

1curl -X POST https://YOUR_API_HOST/v1/phone \
2  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"phone":"+14155552671"}'

1. Save the file as server.ts and set LOOKVALID_API_KEY in the environment of the process that launches it.
2. Add the command that starts it to your MCP client's server list, in whatever configuration format that client uses.
3. Ask the client to validate a number and watch the tool call.

The specification advises keeping a human in the loop with the ability to deny tool calls, so leave your client's confirmation prompts on ¹. You do not have to write any of this to use LookValid from an AI client: our hosted server exposes every live lookup as a tool, described in the MCP docs. To call the REST endpoint from your own code, start with the quickstart or the phone product page.