mcp-use TypeScript SDK

https://docs.mcp-use.com/typescript/
Admin
A guide to creating a complete MCP server with OpenAI Apps SDK widget support using TypeScript,...
Tokens:178,531
Snippets:2,171
Trust Score:7.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run sampling example locally

Source: https://docs.mcp-use.com/typescript/server/sampling

Commands to navigate to the sampling example directory, install dependencies, and start the development server.

```bash
cd libraries/typescript/packages/mcp-use/examples/server/features/sampling
pnpm install
pnpm dev
```

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

### Start command examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Common usage patterns for the start command, including port configuration, directory specification, and tunneling.

```bash
mcp-use start
mcp-use start --port 8080
mcp-use start --mcp-dir src/mcp
mcp-use start --tunnel
mcp-use start -p ./my-server
```

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

### Run Elicitation Examples Locally

Source: https://docs.mcp-use.com/typescript/server/elicitation

Commands to navigate to the elicitation example directory, install dependencies, and start the development server.

```bash
cd libraries/typescript/packages/mcp-use/examples/server/features/elicitation
pnpm install
pnpm dev
```

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

### Configure CLI with Environment Variables

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Examples of setting environment variables for starting the server, building, logging in, and taking screenshots.

```bash
PORT=8080 mcp-use start
MCP_SERVER_URL=https://my-server.example.com mcp-use build
MCP_USE_API_KEY=mcp_... mcp-use login --org my-org
MCP_USE_CHROME_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  mcp-use client local screenshot --tool show-board
```

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

### Start command syntax

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Basic syntax for executing the start command.

```bash
mcp-use start [options]
```

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

### Deployment management command examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Common operations for listing, inspecting, logging, restarting, stopping, starting, and deleting deployments.

```bash
mcp-use deployments list
mcp-use deployments get dep_abc123
mcp-use deployments logs dep_abc123 --build --follow
mcp-use deployments restart dep_abc123 --branch main --follow
mcp-use deployments stop dep_abc123
mcp-use deployments start dep_abc123
mcp-use deployments delete dep_abc123 --yes
```

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

### Initialize and Start a Minimal MCPServer

Source: https://docs.mcp-use.com/typescript/api-reference/server/mcp-server

Demonstrates creating a server instance, defining a tool, and starting the server with listen().

```ts
import { MCPServer, text } from "mcp-use/server";

const server = new MCPServer({
  name: "simple-example-server",
  version: "1.0.0",
  description: "A simple MCP server example",
});

server.tool(
  {
    name: "hello-world",
    description: "A simple tool that returns hello world",
  },
  async () => text("Hello World!")
);

// Start the server (MCP endpoints auto-mounted at /mcp)
await server.listen();
```

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

### Run Completion Example

Source: https://docs.mcp-use.com/typescript/client/completion

Executes the completion example using pnpm from the mcp-use package.

```bash
# From packages/mcp-use:
pnpm run example:completion
```

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

### Install and verify the CLI

Source: https://docs.mcp-use.com/typescript/tooling/client-cli

Commands to access the CLI help menu via npx or global installation.

```bash
npx mcp-use client --help
```

```bash
npm install -g @mcp-use/cli
mcp-use client --help
```

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

### Install mcp-use package

Source: https://docs.mcp-use.com/typescript/agent/index

Install the core mcp-use library using your preferred package manager.

```bash
npm install mcp-use
```

```bash
pnpm add mcp-use
```

```bash
yarn add mcp-use
```

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

### Install mcp-use SDK

Source: https://docs.mcp-use.com/typescript/api-reference/overview

Install the mcp-use package via npm to begin development.

```bash
npm install mcp-use
```

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

### Install the CLI

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Commands for installing the CLI globally or as a project dependency.

```bash
npm install -g @mcp-use/cli
```

```bash
npx @mcp-use/cli dev
```

```bash
npm install --save-dev @mcp-use/cli
```

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

### Install mcp-use package

Source: https://docs.mcp-use.com/typescript/client/environments

Install the necessary dependencies for React integration.

```bash
yarn add mcp-use react
```

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

### Run the development server

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Basic syntax for starting the development server.

```bash
mcp-use dev [options]
```

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

### Start the development server

Source: https://docs.mcp-use.com/typescript/getting-started

Commands to navigate to the server directory and initiate the development environment.

```bash
cd my-server
npm run dev
```

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

### Start the HTTP server

Source: https://docs.mcp-use.com/typescript/api-reference/server/mcp-server

Initializes and starts the server, mounting endpoints and the inspector UI.

```ts
await server.listen(3000);
// Server running at: http://localhost:3000
// MCP endpoint:      http://localhost:3000/mcp
// Inspector UI:      http://localhost:3000/inspector
```

```ts
listen(port?: number): Promise<void>
```

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

### Install Supabase Client

Source: https://docs.mcp-use.com/typescript/server/authentication/providers/supabase

Install the required Supabase JavaScript client package.

```bash
npm install @supabase/supabase-js
```

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

### Install Redis client

Source: https://docs.mcp-use.com/typescript/server/session-management/redis-storage

Install the required Redis client library via npm.

```bash
npm install redis
```

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

### Install the mcp-use CLI

Source: https://docs.mcp-use.com/typescript/server/deployment/mcp-use

Install the global CLI tool required for managing deployments if it is not already included in your project.

```bash
npm install -g @mcp-use/cli
```

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

### Run Development Server

Source: https://docs.mcp-use.com/typescript/mcp-apps/widgets

Start the development server to test widgets in the Inspector.

```bash
npm run dev
```

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

### Building and Running Locally

Source: https://docs.mcp-use.com/typescript/server/deployment/mcp-use

Commands to build and start the server locally before deployment.

```bash
mcp-use build
mcp-use start
```

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

### Initialize MCP Project

Source: https://docs.mcp-use.com/typescript/server/deployment/supabase

Create a new MCP project directory with a basic server setup.

```bash
npx create-mcp-use-app@latest your-project-name
```

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

### Register a Simple Tool

Source: https://docs.mcp-use.com/typescript/api-reference/server/tools

Example of initializing a server and registering a basic tool that returns text.

```ts
import { MCPServer, text } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({
  name: "simple-example-server",
  version: "1.0.0",
  description: "A simple MCP server example",
})

server.tool(
  {
    name: "hello-world",
    description: "A simple tool that returns hello world",
  },
  async () => text("Hello World!"),
)
```

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

### Test notifications locally

Source: https://docs.mcp-use.com/typescript/server/notifications

Commands to set up and run the local notification example server.

```bash
cd libraries/typescript/packages/mcp-use/examples/server/features/notifications
pnpm install
pnpm dev
```

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

### Binary helper usage example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Example of returning binary data as a base64 string.

```ts
import { MCPServer, binary } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-binary-data",
    description: "Return binary data as base64",
    schema: z.object({}),
  },
  async () => {
    const base64 = Buffer.from("Hello binary world").toString("base64")
    return binary(base64, "application/octet-stream")
  }
)
```

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

### Audio helper usage example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Example of returning an audio sample using base64 data.

```ts
import { MCPServer, audio } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-audio-sample",
    description: "Return an audio sample",
    schema: z.object({}),
  },
  async () => {
    const base64 = Buffer.from("fake-audio-data").toString("base64")
    return audio(base64, "audio/wav")
  }
)
```

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

### Install Better Auth Dependencies

Source: https://docs.mcp-use.com/typescript/server/authentication/providers/better-auth

Install the necessary Better Auth packages and the database driver for your environment.

```bash
npm install better-auth @better-auth/oauth-provider better-sqlite3
```

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

### Install Supabase CLI

Source: https://docs.mcp-use.com/typescript/server/deployment/supabase

Install the Supabase CLI using various package managers or Homebrew.

```bash
npm install supabase --save-dev
```

```bash
pnpm add -D supabase
```

```bash
yarn add -D supabase
```

```bash
brew install supabase/tap/supabase
```

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

### Install project dependencies

Source: https://docs.mcp-use.com/typescript/server/deployment/supabase

Install necessary dependencies using common package managers.

```bash
npm install
```

```bash
pnpm install
```

```bash
yarn
```

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

### Initialize the MCP App project

Source: https://docs.mcp-use.com/typescript/mcp-apps/quickstart

Use the template to scaffold a new MCP application and install dependencies.

```bash
npx create-mcp-use-app my-widget-server --template mcp-apps
cd my-widget-server
npm install
```

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

### server.listen()

Source: https://docs.mcp-use.com/typescript/api-reference/server/mcp-server

Starts the MCP server to listen for incoming requests.

```APIDOC
## server.listen()

### Description
Starts the server instance. MCP endpoints are automatically mounted at the /mcp path.
```

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

### Creating a Minimal Node.js Client

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-client

Example of initializing a client with a filesystem server and creating a session.

```typescript
import { MCPClient } from "mcp-use";

const client = new MCPClient({
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    },
  },
});

const session = await client.createSession("filesystem");
const tools = await session.listTools();

await client.close();
```

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

### Start Docker service

Source: https://docs.mcp-use.com/typescript/server/deployment/supabase

Commands to start and verify the Docker service across different operating systems.

```bash
# If you have Docker Desktop installed:
open -a Docker

# Verify Docker is running:
docker info
```

```bash
# Start Docker service:
sudo systemctl start docker

# Verify Docker is running:
docker info
```

```bash
# Open Docker Desktop from Start Menu or run:
# "C:\Program Files\Docker\Docker\Docker Desktop.exe"

# Verify Docker is running (in PowerShell):
docker info
```

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

### Start Gemini CLI

Source: https://docs.mcp-use.com/typescript/server/deployment/google

Launch the Gemini CLI after deployment.

```bash
gemini
```

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

### Install LangChain provider packages

Source: https://docs.mcp-use.com/typescript/agent/index

Install the specific LangChain provider package corresponding to your chosen LLM.

```bash
npm install @langchain/openai
```

```bash
npm install @langchain/anthropic
```

```bash
npm install @langchain/google-genai
```

```bash
npm install @langchain/groq
```

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

### mcp-use start

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Run a production server from built files or from the TypeScript source entry.

```APIDOC
## mcp-use start

### Description
Run a production server from built files or from the TypeScript source entry recorded for --mcp-dir projects.

### Syntax
`mcp-use start [options]`

### Options
- **-p, --path** (string) - Optional - Project directory. Default: Current directory
- **--entry** (file) - Optional - MCP server entry file, relative to the project. Overrides manifest detection.
- **--mcp-dir** (dir) - Optional - Directory that contains the MCP entry file and resources.
- **--port** (port) - Optional - Server port. Default: 3000
- **--tunnel** (boolean) - Optional - Create a public tunnel for the local server.
```

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

### listen(port)

Source: https://docs.mcp-use.com/typescript/api-reference/server/mcp-server

Starts the HTTP server and mounts the necessary MCP protocol and UI endpoints.

```APIDOC
## listen(port)

### Description
Starts the HTTP server. Mounts MCP protocol endpoints, the inspector UI, widget routes, and OAuth routes, then begins listening.

### Parameters
- **port** (number) - Optional - Port to listen on. Defaults to 3000 if not provided or specified via environment variables.

### Returns
- **Promise<void>** - Resolves once the server is listening.
```

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

### Start interactive mode

Source: https://docs.mcp-use.com/typescript/tooling/client-cli

Opens a REPL for a saved server to explore tools, resources, and prompts.

```bash
npx mcp-use client dev interactive
```

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

### Registering a Prompt

Source: https://docs.mcp-use.com/typescript/api-reference/server/prompts

Example of initializing a server and registering a prompt with a Zod schema and a text response helper.

```ts
import { MCPServer, text } from "mcp-use/server"
import z from "zod"

const server = new MCPServer({
  name: "simple-example-server",
  version: "1.0.0",
  description: "A simple MCP server example",
})

server.prompt(
  {
    name: "greeting",
    description: "A simple prompt that returns a greeting",
    schema: z.object({
      name: z.string(),
    }),
  },
  async ({ name }) => text(`Hello, ${name}!`)
)

await server.listen()
```

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

### Development server usage examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Common configurations for the dev command, including port, host, and directory settings.

```bash
mcp-use dev
mcp-use dev --port 8080
mcp-use dev --host 127.0.0.1 --no-open
mcp-use dev --mcp-dir src/mcp
mcp-use dev --entry src/server.ts --widgets-dir src/resources
mcp-use dev --no-hmr
mcp-use dev --tunnel
```

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

### Run MCP Server

Source: https://docs.mcp-use.com/typescript/server/nextjs-drop-in

Execute the development command to start the MCP server.

```bash
pnpm mcp:dev
```

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

### Auth0 Provider Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/auth-providers

Example of configuring an MCP server with Auth0 authentication using zero-config environment variables.

```ts
import { MCPServer, oauthAuth0Provider, error, object } from "mcp-use/server"

// Zero-config: reads MCP_USE_OAUTH_AUTH0_DOMAIN and MCP_USE_OAUTH_AUTH0_AUDIENCE
const server = new MCPServer({
  name: "auth0-oauth-example",
  version: "1.0.0",
  description: "MCP server with Auth0 OAuth authentication",
  oauth: oauthAuth0Provider(),
})

server.tool(
  { name: "get-user-info", description: "Get information about the authenticated user" },
  async (_args, ctx) =>
    object({
      userId: ctx.auth.user.userId,
      email: ctx.auth.user.email,
      name: ctx.auth.user.name,
      permissions: ctx.auth.permissions,
      scopes: ctx.auth.scopes,
    }),
)

server.listen()
```

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

### connect()

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-session

Starts the underlying transport without running the MCP initialize handshake.

```APIDOC
## connect()

### Description
Starts the underlying transport without running the MCP initialize handshake.

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

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

### Server environment command examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Common usage patterns for listing, adding, updating, and removing environment variables.

```bash
mcp-use servers env list --server srv_abc123
mcp-use servers env list --server srv_abc123 --show-values
mcp-use servers env add --server srv_abc123 API_KEY=secret --sensitive
mcp-use servers env add --server srv_abc123 FEATURE_FLAG=true --env preview,development
mcp-use servers env update API_KEY --server srv_abc123 --value new-secret --sensitive
mcp-use servers env remove API_KEY --server srv_abc123
```

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

### Example log output

Source: https://docs.mcp-use.com/typescript/server/deployment/google

Sample output showing a successful CallToolRequest in the server logs.

```text
2025-08-05 19:50:31 INFO:     169.254.169.126:39444 - "POST /mcp HTTP/1.1" 200 OK
2025-08-05 19:50:31 [INFO]: Processing request of type CallToolRequest
2025-08-05 19:50:31 >>> 🛠️ Tool: 'get_animals_by_species' called for 'penguin'
```

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

### Build an MCP server from scratch

Source: https://docs.mcp-use.com/typescript/getting-started/installation

Define a custom MCP server with tools and start the built-in inspector.

```typescript
import { MCPServer } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "my-server",
  title: "My Server", // display name
  version: "1.0.0",
  description: "My custom MCP server",
  websiteUrl: "https://mcp-use.com",
  favicon: "favicon.ico",
  icons: [
    {
      src: "icon.svg",
      mimeType: "image/svg+xml",
      sizes: ["512x512"]
    }
  ]
});

// Define a tool
server.tool({
  name: "get_weather",
  description: "Get weather for a city",
  schema: z.object({
    city: z.string().describe("City name"),
  }),
}, async ({ city }) => {
  return { temperature: 72, condition: "sunny", city };
});

// Start server with auto-inspector
server.listen(3000);
// 🎉 Inspector at http://localhost:3000/inspector
```

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

### Call Tool Example and Signature

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-session

Calls a tool on the server with specified arguments.

```ts
const result = await session.callTool("add", { a: 5, b: 3 });
console.log(result.content);
```

```ts
callTool(
  name: string,
  args?: Record<string, any>,
  options?: RequestOptions
): Promise<CallToolResult>
```

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

### Connect and call an MCP tool

Source: https://docs.mcp-use.com/typescript/client/index

Full example showing how to initialize a client, create a session, list available tools, and execute a specific tool call.

```typescript
import { MCPClient } from "mcp-use";

const client = new MCPClient({
  mcpServers: {
    demo: {
      url: "http://localhost:3000/mcp",
    },
  },
});

try {
  const session = await client.createSession("demo");

  const tools = await session.listTools();
  console.log("Tools:", tools.map((tool) => tool.name));

  const result = await session.callTool("echo", {
    message: "Hello from mcp-use",
  });

  const firstBlock = result.content[0];
  if (firstBlock?.type === "text") {
    console.log(firstBlock.text);
  }
} finally {
  await client.close();
}
```

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

### Start and Interact with Gemini CLI

Source: https://docs.mcp-use.com/typescript/server/deployment/google

Commands to launch the CLI, list tools, and interact with the remote server.

```bash
gemini
```

```text
/mcp
```

```text
Where can I find penguins?
```

```text
Yes, always allow all tools from server "zoo-remote"
```

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

### Interactive REPL session

Source: https://docs.mcp-use.com/typescript/tooling/client-cli

Example commands executed within the interactive REPL environment.

```text
mcp> tools list
mcp> tools describe get-weather
mcp> tools call get-weather
Arguments (JSON, or press Enter for none): {"city":"Tokyo"}
mcp> exit
```

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

### Completable Usage Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/prompts

Example of using Completable to wrap a Zod schema.

```ts
import type { Completable } from "mcp-use/server"
import type { z } from "zod"

type LanguageSchema = Completable<z.ZodString>
```

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

### Define a Prompt with server.prompt

Source: https://docs.mcp-use.com/typescript/api-reference/server/prompts

Example of registering a prompt using the MCPServer instance and returning a GetPromptResult.

```ts
import { MCPServer } from "mcp-use/server"
import z from "zod"

const server = new MCPServer({ name: "prompts", version: "1.0.0" })

// Returning a GetPromptResult directly from the callback
server.prompt(
  {
    name: "greeting",
    description: "A simple prompt that returns a greeting",
    schema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    messages: [
      {
        role: "user",
        content: { type: "text", text: `Hello, ${name}!` },
      },
    ],
  })
)
```

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

### Install E2B Dependency

Source: https://docs.mcp-use.com/typescript/client/code-mode

Install the required package for E2B cloud sandbox execution.

```bash
yarn add @e2b/code-interpreter
```

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

### Initialize Supabase project

Source: https://docs.mcp-use.com/typescript/server/deployment/supabase

Create a new directory named supabase with a basic project configuration.

```bash
supabase init
```

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

### WidgetResponseConfig Usage Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Example of using widget configuration within a tool handler.

```ts
import { MCPServer, widget, text } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "list-results",
    description: "List paginated results in a widget",
    schema: z.object({ query: z.string() }),
    widget: { name: "results-list" },
  },
  async ({ query }) => {
    const items = await search(query)
    return widget({
      props: { items },
      metadata: { totalCount: 1000, nextCursor: "abc123" },
      output: text(`Showing ${items.length} of 1000 results`),
    })
  }
)
```

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

### mcp-use dev

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Starts a development server with TypeScript watching, widget builds, automatic restarts, and the Inspector.

```APIDOC
## mcp-use dev

### Description
Starts a development server with TypeScript watching, widget builds, automatic restarts, and the Inspector.

### Syntax
`mcp-use dev [options]`

### Options
- **-p, --path <path>** (string) - Optional - Project directory. Default: Current directory
- **--entry <file>** (string) - Optional - MCP server entry file, relative to the project. Default: Auto-detected
- **--widgets-dir <dir>** (string) - Optional - Widget directory, relative to the project. Default: resources
- **--mcp-dir <dir>** (string) - Optional - Directory that contains the MCP entry file and resources.
- **--port <port>** (number) - Optional - Server port. Default: 3000
- **--host <host>** (string) - Optional - Bind address. Default: 0.0.0.0
- **--no-open** (boolean) - Optional - Do not open the Inspector automatically.
- **--no-hmr** (boolean) - Optional - Disable Hot Module Reloading and use tsx watch instead.
- **--tunnel** (boolean) - Optional - Create a public tunnel for the local server.

### Examples
`mcp-use dev`
`mcp-use dev --port 8080`
`mcp-use dev --host 127.0.0.1 --no-open`
`mcp-use dev --tunnel`
```

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

### Implement a complete agent with structured output

Source: https://docs.mcp-use.com/typescript/agent/structured-output

Full example demonstrating agent initialization, schema definition, and execution with structured output.

```typescript
import { z } from "zod";
import { MCPAgent } from "mcp-use";

const ProjectSummary = z.object({
  packageName: z.string().nullable(),
  scripts: z.array(z.string()),
  hasTests: z.boolean(),
  notes: z.string(),
});

type ProjectSummary = z.infer<typeof ProjectSummary>;

async function main() {
  const agent = new MCPAgent({
    llm: "openai/gpt-4o",
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "./"],
      },
    },
  });

  try {
    const summary: ProjectSummary = await agent.run({
      prompt: "Inspect package.json and summarize the project scripts.",
      schema: ProjectSummary,
      maxSteps: 8,
    });

    console.log(summary);
  } finally {
    await agent.close();
  }
}

main().catch(console.error);
```

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

### Initialize Browser MCP Client

Source: https://docs.mcp-use.com/typescript/client/environments

Basic setup for connecting to an MCP server over HTTP in a browser environment.

```typescript
import { MCPClient } from "mcp-use/browser";

// Create client with HTTP server
const client = new MCPClient({
  mcpServers: {
    myServer: {
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
      },
    },
  },
});

// Connect to all servers
await client.createAllSessions();

// Use the session
const session = client.getSession("myServer");
const result = await session.callTool("tool_name", { param: "value" });
console.log(result);

// Cleanup
await client.closeAllSessions();
```

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

### Install AI agent skills

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Commands to install or add mcp-use skills to a project directory.

```bash
mcp-use skills add [options]
mcp-use skills install [options]
```

```bash
mcp-use skills add
mcp-use skills add -p ./my-server
mcp-use skills install
```

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

### Initialize MCP Server with Clerk Provider

Source: https://docs.mcp-use.com/typescript/server/authentication/providers/clerk

Basic setup for an MCP server using the Clerk OAuth provider.

```typescript
import { MCPServer, oauthClerkProvider } from "mcp-use/server";

const server = new MCPServer({
  name: "clerk-server",
  version: "1.0.0",
  oauth: oauthClerkProvider(),
});

await server.listen(3000);
```

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

### TypedCallToolResult Usage Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Example of returning a typed tool result using the object helper.

```ts
import { object } from "mcp-use/server"
import type { TypedCallToolResult } from "mcp-use/server"

interface UserData {
  userId: string
  email: string
  role: "admin" | "user"
}

function getUserResponse(user: UserData): TypedCallToolResult<UserData> {
  return object(user)
}
```

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

### Initialize and Link Supabase Project

Source: https://docs.mcp-use.com/typescript/server/deployment/supabase

Commands to set up a new Supabase project and link it to your local environment.

```bash
supabase init
```

```bash
supabase login
```

```bash
supabase link --project-ref YOUR_PROJECT_REF
```

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

### Image helper usage example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Example of returning an image within an MCP tool definition.

```ts
import { MCPServer, image } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-placeholder-image",
    description: "Return a placeholder image",
    schema: z.object({}),
  },
  async () => {
    const { data, mimeType } = await getPlaceholderImage()
    return image(data, mimeType)
  }
)
```

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

### Connect to a server and call a tool

Source: https://docs.mcp-use.com/typescript/tooling/client-cli

Workflow for registering a server alias and executing a tool call.

```bash
npx mcp-use client connect dev http://localhost:3000/mcp
npx mcp-use client dev tools list
npx mcp-use client dev tools call get-weather city=Tokyo
```

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

### CompletionContext Usage Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/prompts

Example of using CompletionContext to provide contextual suggestions based on other arguments.

```ts
import { MCPServer, completable } from "mcp-use/server"
import { z } from "zod"
import type { CompletionContext } from "mcp-use/server"

const server = new MCPServer({ name: "prompts", version: "1.0.0" })

server.prompt(
  {
    name: "analyze-project",
    schema: z.object({
      projectId: completable(
        z.string(),
        async (value: string, ctx?: CompletionContext) => {
          const userId = ctx?.arguments?.userId
          const projects = await fetchProjects(userId)
          return projects
            .map((p) => p.id)
            .filter((id) => id.startsWith(value))
        }
      ),
    }),
  },
  async ({ projectId }) => ({
    messages: [
      {
        role: "user",
        content: { type: "text", text: `Analyzing ${projectId}...` },
      },
    ],
  })
)
```

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

### Deploy the project

Source: https://docs.mcp-use.com/typescript/server/deployment/mcp-use

Execute the deployment process from the root directory of your project.

```bash
mcp-use deploy
```

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

### Deployment Examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Common usage patterns for the deploy command, including environment variable configuration, runtime selection, and monorepo support.

```bash
mcp-use deploy
mcp-use deploy --no-github
mcp-use deploy --name my-server --open
mcp-use deploy --env DATABASE_URL=postgres://... --env API_KEY=secret
mcp-use deploy --env-file .env.production
mcp-use deploy --runtime python
mcp-use deploy --root-dir apps/mcp-server
mcp-use deploy --root-dir apps/mcp-server --watch-paths "apps/mcp-server/**" "packages/shared/**"
mcp-use deploy --new --name my-server-v2
mcp-use deploy --org manufact-inc --region EU --yes
```

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

### Initialize MCPServer with ServerConfig

Source: https://docs.mcp-use.com/typescript/api-reference/server/server-config

Demonstrates the basic instantiation of an MCPServer using a configuration object.

```typescript
import { MCPServer } from "mcp-use/server";

const server = new MCPServer({
  name: "everything-server",
  title: "Everything Server",
  version: "1.0.0",
  baseUrl: process.env.MCP_URL || "http://localhost:3000",
});
```

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

### initialize

Source: https://docs.mcp-use.com/typescript/api-reference/agent/mcp-agent

Connects to MCP servers and configures the agent executor.

```APIDOC
## initialize()

### Description
Connects to MCP servers, creates LangChain tools, builds the system message, configures observability callbacks, and creates the underlying LangChain agent executor.

### Returns
- **Promise<void>**
```

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

### Supabase OAuth Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/auth-providers

Example of configuring an MCP server with Supabase OAuth using zero-config environment variables.

```ts
import { MCPServer, oauthSupabaseProvider } from "mcp-use/server"

// Zero-config: reads MCP_USE_OAUTH_SUPABASE_PROJECT_ID
const server = new MCPServer({
  name: "supabase-oauth-example",
  version: "1.0.0",
  description: "MCP server with Supabase OAuth authentication",
  oauth: oauthSupabaseProvider(),
})
```

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

### Keycloak OAuth Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/auth-providers

Example of configuring an MCP server with Keycloak OAuth and accessing user info in a tool.

```ts
import { MCPServer, oauthKeycloakProvider, object } from "mcp-use/server"

const server = new MCPServer({
  name: "keycloak-oauth-example",
  version: "1.0.0",
  description: "MCP server with Keycloak OAuth authentication (DCR)",
  oauth: oauthKeycloakProvider({
    serverUrl: "http://localhost:8080",
    realm: "demo",
  }),
})

server.tool(
  { name: "get-user-info", description: "Return identity info extracted from the Keycloak access token" },
  async (_args, ctx) =>
    object({
      userId: ctx.auth.user.userId,
      username: ctx.auth.user.username,
      email: ctx.auth.user.email,
      roles: ctx.auth.user.roles,
    }),
)
```

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

### Prepare the database

Source: https://docs.mcp-use.com/typescript/server/authentication/providers/better-auth

Run these commands to generate and migrate the database schema required for Better Auth.

```bash
npx auth@latest generate
npx auth@latest migrate
```

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

### Initialize MCPClient in Node.js

Source: https://docs.mcp-use.com/typescript/client/environments

Demonstrates setting up an MCPClient with both remote HTTP and local filesystem servers in a Node.js environment.

```typescript
import { MCPClient } from "mcp-use";

const client = new MCPClient({
  mcpServers: {
    remoteApi: {
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
      },
    },
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
    },
  },
});

const sessions = await client.createAllSessions();

const remoteTools = await sessions.remoteApi.listTools();
const filesystemTools = await sessions.filesystem.listTools();

console.log("Remote tools:", remoteTools.map((tool) => tool.name));
console.log("Filesystem tools:", filesystemTools.map((tool) => tool.name));

await client.closeAllSessions();
```

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

### Clerk Provider Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/auth-providers

Example of configuring an MCP server with Clerk authentication using zero-config environment variables.

```ts
import { MCPServer, oauthClerkProvider, object } from "mcp-use/server"

// Zero-config: reads MCP_USE_OAUTH_CLERK_FRONTEND_API_URL
const server = new MCPServer({
  name: "clerk-oauth-example",
  version: "1.0.0",
  description: "MCP server with Clerk OAuth authentication",
  oauth: oauthClerkProvider(),
})

server.tool(
  { name: "get-user-info", description: "Get information about the authenticated user" },
  async (_args, ctx) =>
    object({
      userId: ctx.auth.user.userId,
      email: ctx.auth.user.email,
      name: ctx.auth.user.name,
    }),
)

server.listen()
```

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

### Better Auth Provider Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/auth-providers

Example of configuring an MCP server with Better Auth, specifying the authURL explicitly.

```ts
import { MCPServer, oauthBetterAuthProvider, object } from "mcp-use/server"

const server = new MCPServer({
  name: "better-auth-oauth-example",
  version: "1.0.0",
  description: "MCP server with Better Auth OAuth authentication",
  oauth: oauthBetterAuthProvider({
    authURL: "http://localhost:3000/api/auth",
  }),
})
```

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

### Initialize Session and List Tools

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-client

Establishes a session with a configured MCP server and retrieves available tools.

```ts
import { MCPClient } from "mcp-use";

const client = new MCPClient({
  mcpServers: {
    demo: { url: "http://localhost:3000/mcp" },
  },
});

try {
  const session = await client.createSession("demo");
  const tools = await session.listTools();
  console.log(tools.map((tool) => tool.name));
} finally {
  await client.close();
}
```

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

### WorkOS OAuth Example

Source: https://docs.mcp-use.com/typescript/api-reference/server/auth-providers

Example of configuring an MCP server with WorkOS AuthKit OAuth using zero-config environment variables.

```ts
import { MCPServer, oauthWorkOSProvider } from "mcp-use/server"

// Zero-config: reads MCP_USE_OAUTH_WORKOS_SUBDOMAIN
const server = new MCPServer({
  name: "workos-oauth-example",
  version: "1.0.0",
  description: "MCP server with WorkOS AuthKit OAuth authentication",
  oauth: oauthWorkOSProvider(),
})
```

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

### Scaffold a new MCP server project

Source: https://docs.mcp-use.com/typescript/getting-started

Initializes a new project using the interactive CLI tool.

```bash
npx create-mcp-use-app
```

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

### get

Source: https://docs.mcp-use.com/typescript/api-reference/server/sessions

Retrieves session metadata by ID.

```APIDOC
## get(sessionId: string): Promise<SessionMetadata | null>

### Description
Retrieve and JSON-parse session metadata by ID. Returns null when the key is absent or if the read/parse fails.

### Parameters
- **sessionId** (string) - Required - The unique session identifier.
```

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

### get

Source: https://docs.mcp-use.com/typescript/api-reference/server/sessions

Retrieves session metadata by ID.

```APIDOC
## get(sessionId: string)

### Description
Retrieve session metadata by ID. Returns null when the session is not present.

### Parameters
- **sessionId** (string) - Required - The unique session identifier.

### Returns
- **Promise<SessionMetadata | null>**
```

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

### Deploy Command Syntax

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Basic syntax for initiating a deployment using the mcp-use CLI.

```bash
mcp-use deploy [options]
```

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

### size

Source: https://docs.mcp-use.com/typescript/api-reference/server/sessions

Gets the current number of active sessions.

```APIDOC
## get size()

### Description
The current number of active sessions held in memory. Read-only getter.

### Returns
- **number**
```

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

### Get Roots

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-session

Retrieves the roots currently advertised to the server.

```ts
getRoots(): Root[]
```

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

### Get Session Count

Source: https://docs.mcp-use.com/typescript/api-reference/server/sessions

Retrieve the total number of active sessions.

```ts
get size(): number
```

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

### Server Management Examples

Source: https://docs.mcp-use.com/typescript/api-reference/cli-reference

Common operations for managing servers, including listing, fetching details, updating configurations, and deletion.

```bash
mcp-use servers list
mcp-use servers get srv_abc123
mcp-use servers update srv_abc123 --branch main
mcp-use servers update srv_abc123 --build-command "npm run build"
mcp-use servers update srv_abc123 --watch-paths "apps/api/**" "packages/shared/**" --deploy-branches "release/*"
mcp-use servers delete srv_abc123 --yes
```

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

### Request prompt argument completions with MCPClient

Source: https://docs.mcp-use.com/typescript/client/completion

Demonstrates how to initialize an MCPClient, establish sessions, and request suggestions for a specific prompt argument.

```typescript
import { MCPClient } from 'mcp-use'

const client = new MCPClient({
  mcpServers: {
    'my-server': {
      command: 'node',
      args: ['./my-server.js']
    }
  }
})
await client.createAllSessions()

const session = client.getSession('my-server')
const result = await session.complete({
  ref: { type: 'ref/prompt', name: 'code-review' },
  argument: { name: 'language', value: 'py' }
})

console.log('Suggestions:', result.completion.values)
// Output: ['python', 'pytorch', ...]

await client.closeAllSessions()
```

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

### new MCPServer(config: ServerConfig)

Source: https://docs.mcp-use.com/typescript/api-reference/server/server-config

Initializes a new MCP server instance with the provided configuration object. The name and version fields are required.

```APIDOC
## new MCPServer(config: ServerConfig)

### Description
Initializes a new MCP server instance. The configuration object controls server identity, networking, and session persistence.

### Parameters
- **name** (string) - Required - Unique identifier for the MCP server.
- **version** (string) - Required - Semantic version of the server.
- **description** (string) - Optional - Human-readable description of the server.
- **instructions** (string) - Optional - Instructions for AI models using this server.
- **host** (string) - Optional - Hostname for widget URLs and server endpoints (default: "localhost").
- **baseUrl** (string) - Optional - Full base URL that overrides host:port for widget URLs.
- **cors** (Partial<Parameters<typeof cors>[0]>) - Optional - Custom CORS options for the server.
- **allowedOrigins** (string[]) - Optional - Allowed origins for DNS rebinding protection.
- **sessionIdleTimeoutMs** (number) - Optional - Idle timeout for sessions in milliseconds (default: 86400000).
- **stateless** (boolean) - Optional - Enable stateless mode (no session tracking).
```

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

### MCPClient.fromConfigFile(path, options?)

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-client

Creates an MCPClient instance by loading a JSON configuration file from the specified path.

```APIDOC
## MCPClient.fromConfigFile(path, options?)

### Description
Loads a JSON config file and creates an MCPClient.

### Parameters
- **path** (string) - Required - Path to the JSON configuration file.
- **options** (MCPClientOptions | undefined) - Optional - Client behavior options.

### Returns
- **returns** (MCPClient) - The initialized MCPClient instance.
```

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

### get localSize()

Source: https://docs.mcp-use.com/typescript/api-reference/server/sessions

Returns the number of active local streams on this server instance.

```APIDOC
## get localSize()

### Description
Returns the number of active local streams on this server instance.

### Returns
- **number**
```

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

### Get Prompt

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-session

Fetches a specific prompt by name, including any required arguments.

```ts
getPrompt(name: string, args: Record<string, any>): Promise<GetPromptResult>
```

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

### constructor(config?, options?)

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-client

Creates a new instance of the MCPClient. Accepts an optional configuration object or path to a JSON file.

```APIDOC
## constructor(config?, options?)

### Description
Creates a Node.js MCP client. The constructor accepts an inline config object, a path to a JSON config file, or no config.

### Parameters
- **config** (string | MCPClientConfigShape | undefined) - Optional - Inline client configuration, path to a JSON config file, or omitted for an empty client.
- **options** (MCPClientOptions | undefined) - Optional - Client behavior options such as code mode, sampling, elicitation, and notification callbacks.
```

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

### List, describe, and call tools

Source: https://docs.mcp-use.com/typescript/tooling/client-cli

Commands to discover available tools and execute them with specific arguments.

```bash
npx mcp-use client dev tools list
npx mcp-use client dev tools describe get-weather
npx mcp-use client dev tools call get-weather city=Tokyo
```

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

### Return error response example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Demonstrates returning an error when an item is not found in a tool.

```ts
import { MCPServer, error, text } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "delete-item",
    description: "Delete an item permanently",
    schema: z.object({ itemId: z.string() }),
  },
  async ({ itemId }) => {
    if (!items.has(itemId)) {
      return error(`Item not found: ${itemId}`)
    }
    items.delete(itemId)
    return text(`Deleted: ${itemId}`)
  }
)
```

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

### Object helper example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Usage of the object helper to return structured JSON data.

```ts
import { MCPServer, object } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "search-items",
    description: "Search items",
    schema: z.object({ query: z.string() }),
  },
  async ({ query }) => {
    const result = await search(query)
    return object({ count: result.length, items: result })
  }
)
```

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

### Build Application

Source: https://docs.mcp-use.com/typescript/server/deployment/supabase

Build commands for different package managers.

```bash
npm run build
```

```bash
pnpm build
```

```bash
yarn build
```

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

### MCPClient.fromDict(cfg, options?)

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-client

Creates an MCPClient instance from an inline configuration object.

```APIDOC
## MCPClient.fromDict(cfg, options?)

### Description
Creates an MCPClient from an inline configuration object.

### Parameters
- **cfg** (Record<string, any>) - Required - Client configuration with an optional mcpServers map.
- **options** (MCPClientOptions | undefined) - Optional - Client behavior options.

### Returns
- **returns** (MCPClient) - The initialized MCPClient instance.
```

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

### JavaScript helper example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Usage of the javascript helper within an MCP tool definition.

```ts
import { MCPServer, javascript } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-script",
    description: "Return a JavaScript snippet",
    schema: z.object({}),
  },
  async () => javascript('console.log("Hello from MCP tool");')
)
```

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

### Initialize Session Example and Signature

Source: https://docs.mcp-use.com/typescript/api-reference/client/mcp-session

Runs the MCP initialize handshake. If autoConnect is true, it connects automatically if not already connected.

```ts
const session = await client.createSession("api", false);
await session.connect();
await session.initialize();
```

```ts
initialize(): Promise<void>
```

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

### CSS response example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Usage of the css helper within an MCP tool definition.

```ts
import { MCPServer, css } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-theme-css",
    description: "Return CSS theme styles",
    schema: z.object({}),
  },
  async () => css("body { margin: 0; font-family: system-ui; }")
)
```

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

### MCPClient Initialization and Usage

Source: https://docs.mcp-use.com/typescript/client/environments

How to initialize the MCPClient in a browser environment, connect to servers, and invoke tools.

```APIDOC
## MCPClient Initialization

### Description
Initializes the MCP client for browser environments and establishes sessions with configured servers.

### Usage
```typescript
import { MCPClient } from "mcp-use/browser";

const client = new MCPClient({
  mcpServers: {
    myServer: {
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
      },
    },
  },
});

await client.createAllSessions();
const session = client.getSession("myServer");
const result = await session.callTool("tool_name", { param: "value" });
await client.closeAllSessions();
```
```

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

### XML response example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Usage of the xml helper within an MCP tool definition.

```ts
import { MCPServer, xml } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-xml-data",
    description: "Return XML data",
    schema: z.object({}),
  },
  async () => xml('<?xml version="1.0"?><root><item id="1">Test</item></root>')
)
```

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

### HTML response example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Usage of the html helper within an MCP tool definition.

```ts
import { MCPServer, html } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-html-snippet",
    description: "Return an HTML snippet",
    schema: z.object({}),
  },
  async () => html("<h1>Hello</h1><p>This is an HTML response from an MCP tool.</p>")
)
```

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

### List and read resources

Source: https://docs.mcp-use.com/typescript/tooling/client-cli

Commands to list available resources and read content from a specific URI.

```bash
npx mcp-use client dev resources list
npx mcp-use client dev resources read "file:///tmp/data.json"
```

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

### Markdown response example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Usage of the markdown helper within an MCP tool definition.

```ts
import { MCPServer, markdown } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "get-report",
    description: "Generate a markdown report",
    schema: z.object({ title: z.string() }),
  },
  async ({ title }) => markdown(`# ${title}\n\n## Summary\n\n- Item 1\n- Item 2`)
)
```

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

### Prepare Gemini CLI Configuration Directory

Source: https://docs.mcp-use.com/typescript/server/deployment/google

Create the necessary directory for storing Gemini CLI settings.

```bash
mkdir -p ~/.gemini
```

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

### Text response example

Source: https://docs.mcp-use.com/typescript/api-reference/server/response-helpers

Usage of the text helper within an MCP tool definition.

```ts
import { MCPServer, text } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({ name: "my-server", version: "1.0.0" })

server.tool(
  {
    name: "greet-user",
    description: "Greet a user by name",
    schema: z.object({ name: z.string() }),
  },
  async ({ name }) => text(`Hey ${name}!`)
)
```
Tokens:
Raw