MCP TypeScript SDK

https://ts.sdk.modelcontextprotocol.io/v2
Admin
MCP TypeScript SDK is a development kit for building Model Context Protocol servers and clients in...
Tokens:542,991
Snippets:4,594
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### start()

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/client/client/streamableHttp.html

Starts processing messages on the transport, including any connection steps that might need to be taken. Should only be called after callbacks are installed.

```APIDOC
## start()

### Description
Starts processing messages on the transport, including any connection steps that might need to be taken.
This method should only be called after callbacks are installed, or else messages may be lost.
NOTE: This method should not be called explicitly when using `Client` or `Server` classes, as they will implicitly call `start()`.

### Method
start

### Signature
`start(): Promise<void>`

### Returns
`Promise<void>`

### Implementation of
`Transport.start`
```

--------------------------------

### Install @modelcontextprotocol/server and @modelcontextprotocol/node

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/node

Install the server SDK and the Node.js adapter package. Required before using the Node transport or handler adapters.

```bash
npm install @modelcontextprotocol/server @modelcontextprotocol/node
```

--------------------------------

### start()

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/server/server/stdio.html

Starts listening for messages on stdin. This method must be called to begin receiving messages from the client.

```APIDOC
## Method: start()

### Description
Starts listening for messages on `stdin`.

### Returns
`Promise<void>`

### Implementation of
`Transport`.`start`
```

--------------------------------

### Install @modelcontextprotocol/server-legacy

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/server-legacy

Install the deprecated server-legacy package for migration purposes.

```bash
npm install @modelcontextprotocol/server-legacy
```

--------------------------------

### Install @modelcontextprotocol/server or @modelcontextprotocol/client

Source: https://ts.sdk.modelcontextprotocol.io/v2/get-started/packages.md

Install the package for the side of the protocol you are building: server to expose tools, resources, and prompts, or client to connect to servers and call them.

```sh
npm install @modelcontextprotocol/server   # expose tools, resources, prompts
npm install @modelcontextprotocol/client   # connect to servers and call them
```

--------------------------------

### Install @modelcontextprotocol/express and dependencies

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/express

Install the required packages for using the Express adapters. The second command installs the Node.js transport for MCP Streamable HTTP.

```bash
npm install @modelcontextprotocol/server @modelcontextprotocol/express express

# For MCP Streamable HTTP over Node.js (IncomingMessage/ServerResponse):
npm install @modelcontextprotocol/node
```

--------------------------------

### List the server's tools

Source: https://ts.sdk.modelcontextprotocol.io/v2/get-started/first-client.md

Call listTools to get all tools the server registered, along with their JSON Schema. The example logs each tool's name and description.

```ts
const { tools } = await client.listTools();
for (const tool of tools) {
    console.log(tool.name, '—', tool.description);
}
```

--------------------------------

### Install @modelcontextprotocol/fastify and dependencies

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/fastify

Install the required packages for using the Fastify adapter with the MCP server SDK. The second command adds the Node.js transport for Streamable HTTP.

```bash
npm install @modelcontextprotocol/server @modelcontextprotocol/fastify fastify

# For MCP Streamable HTTP over Node.js (IncomingMessage/ServerResponse):
npm install @modelcontextprotocol/node
```

--------------------------------

### Start Fastify server

Source: https://ts.sdk.modelcontextprotocol.io/v2/serving/fastify.md

Starts the Fastify server on port 3000. Run with `npx tsx server.ts`.

```ts
await app.listen({ port: 3000 });
```

--------------------------------

### Example output from server accessors

Source: https://ts.sdk.modelcontextprotocol.io/v2/clients/connect

Example output from the accessors when connected to a server named 'travel' with one tool and instructions set.

```text
{ name: 'travel', version: '2.1.0' }
{ tools: { listChanged: true } }
Call list-trips before book-trip. Dates are ISO 8601.
```

--------------------------------

### Example output of product-card tool with mixed content blocks

Source: https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt

Example response from calling the 'product-card' tool with { name: 'Travel mug' }. Shows the three content blocks exactly as returned: an image, an audio, and an embedded resource. The resource block arrives without a resources/read round trip.

```json
[
  {
    type: 'image',
    data: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=',
    mimeType: 'image/png'
  },
  {
    type: 'audio',
    data: 'UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQAAAAA=',
    mimeType: 'audio/wav'
  },
  {
    type: 'resource',
    resource: {
      uri: 'catalog://products/Travel%20mug',
      mimeType: 'application/json',
      text: '{"name":"Travel mug","price":24}'
    }
  }
]
```

--------------------------------

### Install @modelcontextprotocol/hono

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/hono

Install the required packages for using the Hono adapter with the MCP TypeScript server SDK.

```bash
npm install @modelcontextprotocol/server @modelcontextprotocol/hono hono
```

--------------------------------

### start()

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/server/server/streamableHttp.html

Starts the transport. This is required by the Transport interface but is a no-op for the Streamable HTTP transport as connections are managed per-request.

```APIDOC
## start()

### Description
Starts the transport. This is required by the `Transport` interface but is a no-op for the Streamable HTTP transport as connections are managed per-request.

### Method
start

### Signature
`start(): Promise<void>`

### Returns
`Promise<void>`

### Implementation of
`Transport.start`

```

--------------------------------

### Example protocolVersion output

Source: https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt

Example output printed when logging the client end's protocolVersion after connect() over a linked pair of SessionLoopbackTransport instances. The actual version depends on the connection's protocol era.

```text
2025-11-25
```

--------------------------------

### Example output: URL flow finished log and tool result

Source: https://ts.sdk.modelcontextprotocol.io/v2/servers/elicitation.md

Example console output showing the client logging the `notifications/elicitation/complete` notification before the tool result arrives. The `elicitationId` is fresh on every run.

```text
URL flow finished: c9a7bcfc-acc9-494c-8ce5-44c921232ea6
[ { type: 'text', text: 'Connected google.' } ]
```

--------------------------------

### Log output example

Source: https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt

Example output when calling 'validate-records' with one bad record: both log notifications are delivered before the tool result.

```text
info Validating 2 records
warning { invalid: [ 'b.txt' ] }
[ { type: 'text', text: '1 of 2 records are valid' } ]
```

--------------------------------

### Client handler for elicitation/create

Source: https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt

Sets up an in-memory client with elicitation capabilities and a handler for 'elicitation/create' that stands in for a real host's UI. For url mode it opens the URL and returns accept; for form mode it returns the user's typed fields. This handler is used by every example on this page.

```ts
const client = new Client({ name: 'feedback-host', version: '1.0.0' }, { capabilities: { elicitation: { form: {}, url: {} } } });

client.setRequestHandler('elicitation/create', async request => {
    if (request.params.mode === 'url') {
        // Open request.params.url in the user's browser; answer when they finish.
        return { action: 'accept' };
    }
    // Render request.params.requestedSchema as a form; return what the user typed.
    return { action: 'accept', content: { rating: 5, comment: 'Smooth setup' } };
});
```

--------------------------------

### Output of getPrompt

Source: https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt

Example output from `getPrompt` showing the messages array with the argument substituted into the template.

```text
[
  {
    role: 'user',
    content: { type: 'text', text: 'Review this code:\n\nlet x = 1' }
  }
]
```

--------------------------------

### registerTool

Source: https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt

Example of registering a tool with an ArkType schema using the MCP server SDK.

```APIDOC
## registerTool

### Description
Registers a tool with the MCP server, accepting any Standard Schema (e.g., ArkType) that can produce JSON Schema. The SDK derives the JSON Schema for the model, validates arguments before the handler runs, and infers the handler's argument types.

### Method
registerTool

### Parameters
- **name** (string) - Required - The name of the tool.
- **schema** (object) - Required - An object containing `description` (string) and `inputSchema` (Standard Schema).
- **handler** (function) - Required - Async function that receives the validated arguments and returns the tool result.

### Request Example
```ts
server.registerTool(
    'greet',
    {
        description: 'Greet someone by name',
        inputSchema: type({ name: 'string', 'times?': '1 <= number.integer <= 5' })
    },
    async ({ name, times }) => ({
        content: [{ type: 'text', text: Array.from({ length: times ?? 1 }, () => `Hello, ${name}`).join('\n') }]
    })
);
```

### Response
#### Success Response
- **content** (array) - Array of content objects, each with `type` and `text`.
- **isError** (boolean) - Indicates if the call resulted in an error.

#### Response Example
```
{
  content: [
    {
      type: 'text',
      text: 'Input validation error: Invalid arguments for tool greet: times: times must be at most 5 (was 99)'
    }
  ],
  isError: true
}
```
```

--------------------------------

### Register tool with Standard Schema (zod/v4, ArkType, fromJsonSchema)

Source: https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt

Shows three equivalent ways to register a tool with a Standard Schema input: zod/v4, ArkType, and raw JSON Schema via fromJsonSchema. The zod/v4 example is the primary path; the ArkType and fromJsonSchema variants are alternatives. The comment 'No-parameter tools: z.object({})' indicates that an empty object schema is used for tools without parameters.

```typescript
import * as z from 'zod/v4';
server.registerTool('greet', { inputSchema: z.object({ name: z.string() }) }, handler);
```

```typescript
import { type } from 'arktype';
server.registerTool('greet', { inputSchema: type({ name: 'string' }) }, handler);
```

```typescript
import { fromJsonSchema } from '@modelcontextprotocol/server';
server.registerTool('greet', { inputSchema: fromJsonSchema({ type: 'object', properties: { name: { type: 'string' } } }) }, handler);
```

--------------------------------

### GET /prompts/{name}

Source: https://ts.sdk.modelcontextprotocol.io/v2/llms-full.txt

Retrieves a prompt by name, filling in its arguments and returning messages ready to send to a model.

```APIDOC
## [GET] /prompts/{name}

### Description
Retrieves a prompt by name, filling in its arguments and returning messages ready to send to a model.

### Method
GET

### Endpoint
/prompts/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the prompt to retrieve.

#### Query Parameters
- **arguments** (object) - Optional - A map of argument names to values to substitute into the prompt template.

### Request Example
{
  "name": "summarize-order",
  "arguments": {
    "id": "A-1041",
    "tone": "terse"
  }
}

### Response
#### Success Response (200)
- **messages** (array) - The list of messages ready to send to a model.

#### Response Example
{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Write a terse status update for order A-1041."
      }
    }
  ]
}
```

--------------------------------

### Set up the project with npm

Source: https://ts.sdk.modelcontextprotocol.io/v2/get-started/first-server.md

Sets up the project directory, initializes a Node.js package, sets the module type to ES modules, installs the MCP server SDK, Zod, and tsx, and creates the source directory. Requires Node.js 20 or later.

```sh
mkdir weather && cd weather
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod tsx
mkdir src

```

--------------------------------

### Start Express server on port 3000

Source: https://ts.sdk.modelcontextprotocol.io/v2/serving/express.md

Start the Express server on port 3000. Add this line to the previous setup and run the process with npx tsx server.ts.

```ts
app.listen(3000);
```

--------------------------------

### new Server(_serverInfo, options?)

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/server/server/server.html

Initializes a new Server instance with the given server information and optional options. The server automatically responds to the initialization flow from the client.

```APIDOC
## Constructor: new Server(_serverInfo, options?)

### Description
Initializes this server with the given name and version information.

### Parameters
- **_serverInfo** (object) - Required - Server information including name, version, and optional description, icons, title, and website URL.
  - **name** (string) - Required - Intended for programmatic or logical use, but used as a display name in past specs or fallback.
  - **version** (string) - Required - Version of the server.
  - **description?** (string) - Optional - An optional human-readable description of what this implementation does.
  - **icons?** (object[]) - Optional - Optional set of sized icons that the client can display in a user interface.
  - **title?** (string) - Optional - Intended for UI and end-user contexts — optimized to be human-readable and easily understood.
  - **websiteUrl?** (string) - Optional - An optional URL of the website for this implementation.
- **options?** (ServerOptions) - Optional - Server options.

### Returns
- **Server** - The newly created Server instance.

### Overrides
- `Protocol.constructor`
```

--------------------------------

### SSEClientTransport.start()

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/client/client/sse.html

Starts processing messages on the transport, including any connection steps that might need to be taken. This method should only be called after callbacks are installed, or else messages may be lost. NOTE: This method should not be called explicitly when using `Client` or `Server` classes, as they will implicitly call `start()`.

```APIDOC
## start()

### Description
Starts processing messages on the transport, including any connection steps that might need to be taken.

This method should only be called after callbacks are installed, or else messages may be lost.

NOTE: This method should not be called explicitly when using `Client` or `Server` classes, as they will implicitly call `start()`.

### Method
start()

### Signature
`start(): Promise<void>`

### Returns
`Promise<void>`

### Implementation of
`Transport.start`
```

--------------------------------

### Create a new McpServer instance

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/server/server/mcp.html

Example from the McpServer class documentation showing how to instantiate a server with name and version.

```typescript
const server = new McpServer({
    name: 'my-server',
    version: '1.0.0'
});
```

--------------------------------

### connect(transport)

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/server/server/mcp.html

Attaches to the given transport, starts it, and starts listening for messages.

```APIDOC
## connect(transport)

### Description
Attaches to the given transport, starts it, and starts listening for messages. The `server` object assumes ownership of the `Transport`, replacing any callbacks that have already been set, and expects that it is the only user of the `Transport` instance going forward.

### Method
connect(transport)

### Parameters
- **transport** (Transport) - Required - The transport to connect to.

### Returns
`Promise<void>`

### Example
```ts
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
const transport = new StdioServerTransport();
await server.connect(transport);
```
```

--------------------------------

### Install Fastify MCP packages

Source: https://ts.sdk.modelcontextprotocol.io/v2/serving/fastify.md

Install the required packages for serving MCP over Fastify.

```sh
npm install @modelcontextprotocol/server @modelcontextprotocol/fastify @modelcontextprotocol/node fastify
```

--------------------------------

### new Client(_clientInfo, options?)

Source: https://ts.sdk.modelcontextprotocol.io/v2/api/%40modelcontextprotocol/client/client/client.html

Constructor for the Client class. Initializes a new MCP client with the given client information and optional options.

```APIDOC
## new Client(_clientInfo, options?)

### Description
Initializes a new MCP client with the given client information and optional options. The client automatically begins the initialization flow with the server when `connect` is called.

### Constructor
`new Client(_clientInfo, options?): Client`

### Parameters
- **_clientInfo** (object) - Required - Client information including name, version, and optional description, icons, title, and website URL.
  - **name** (string) - Required - Intended for programmatic or logical use, but used as a display name in past specs or fallback.
  - **version** (string) - Required - Version of the client.
  - **description?** (string) - Optional - An optional human-readable description of what this implementation does.
  - **icons?** (object[]) - Optional - Optional set of sized icons that the client can display in a user interface. Must support at least `image/png` and `image/jpeg` (or `image/jpg`). Should also support `image/svg+xml` and `image/webp`.
  - **title?** (string) - Optional - Intended for UI and end-user contexts; optimized to be human-readable. If not provided, `name` should be used for display.
  - **websiteUrl?** (string) - Optional - An optional URL of the website for this implementation.
- **options?** (ClientOptions) - Optional - Client options.

### Returns
`Client`

### Example
```ts
const client = new Client({
  name: 'my-client',
  version: '1.0.0',
  description: 'A sample client',
  icons: [{ src: 'icon.png', sizes: '32x32', type: 'image/png' }],
  title: 'My Client',
  websiteUrl: 'https://example.com'
});
```
```

--------------------------------

### Create a server with one tool

Source: https://ts.sdk.modelcontextprotocol.io/v2/servers/notifications.md

Sets up a server with one tool named 'list-jobs' that returns a text list of jobs. This is the base server used by the notification examples on this page.

```ts
import { McpServer } from '@modelcontextprotocol/server';

const jobs = ['nightly-backup'];

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

server.registerTool('list-jobs', { description: 'List the configured jobs' }, async () => ({
    content: [{ type: 'text', text: jobs.join('\n') }]
}));
```

--------------------------------

### Install MCP Express dependencies

Source: https://ts.sdk.modelcontextprotocol.io/v2/serving/express.md

Install the required packages for serving an MCP server with Express.

```sh
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express
```

--------------------------------

### Connect a client and call a tool

Source: https://ts.sdk.modelcontextprotocol.io/v2/testing.md

Creates a Client with version negotiation set to 'auto', connects over the transport, and calls the 'apply-discount' tool. The handler responds in-process with the structured content shown.

```ts
const client = new Client({ name: 'test-harness', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' } });
await client.connect(transport);

const result = await client.callTool({ name: 'apply-discount', arguments: { price: 80, percent: 25 } });
console.log(result.structuredContent);
```

```text
{ total: 60 }
```
Tokens:
Raw