> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpfy.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Api reference

# API Reference

This page provides a reference for the public APIs exposed by `mcpfy-sdk`.

The examples in this document target `mcpfy-sdk@0.3.1`.

## Server

Import the server APIs from:

```typescript theme={null}
import {
  MCPServer,
  object,
  text,
  markdown,
} from "mcpfy-sdk/server";
```

### `MCPServer`

Creates an MCP server.

```typescript theme={null}
const server = new MCPServer({
  name: "my-server",
  version: "1.0.0",
});
```

### `MCPServerConfig`

The server configuration supports:

```typescript theme={null}
interface MCPServerConfig {
  name: string;
  version: string;
  description?: string;
  basePath?: string;
  icon?: string | ServerIcon;
  auth?: AuthConfig;
  widgetsDir?: string;
}
```

#### `name`

Required server name.

```typescript theme={null}
name: "weather-server"
```

#### `version`

Required server version.

```typescript theme={null}
version: "1.0.0"
```

#### `description`

Optional description for the server.

```typescript theme={null}
description: "Provides weather information"
```

#### `basePath`

Optional HTTP MCP endpoint path.

The default is:

```text theme={null}
/mcp
```

Example:

```typescript theme={null}
basePath: "/weather"
```

#### `icon`

Optional server icon.

mcpfy supports remote URLs, data URIs, local file paths, and `file:` URLs.

#### `auth`

Optional HTTP authentication configuration.

```typescript theme={null}
auth: {
  type: "oauth",
  verifyToken: jwksVerifier({
    issuer,
    jwksUri,
    audience,
  }),
  authorizationServers: [issuer],
}
```

See [Authentication](authentication.md).

#### `widgetsDir`

Optional widget root directory.

The default is:

```text theme={null}
src/widgets
```

### `server.tool()`

Registers a tool with the MCP server.

```typescript theme={null}
server.tool(
  {
    name: "add",
    description: "Add two numbers",
    schema: z.object({
      a: z.number(),
      b: z.number(),
    }),
  },
  async ({ a, b }) => {
    return object({
      result: a + b,
    });
  }
);
```

The tool definition contains:

* `name`
* `description`
* `schema`
* optional widget configuration

The callback receives validated input.

### Tool Return Helpers

#### `text()`

Creates a text result:

```typescript theme={null}
return text("Hello!");
```

#### `markdown()`

Creates a Markdown result:

```typescript theme={null}
return markdown("# Hello\n\nThis is Markdown.");
```

#### `object()`

Creates a structured result:

```typescript theme={null}
return object({
  success: true,
  value: 42,
});
```

Tool callbacks should use these helpers instead of returning an arbitrary object directly.

## `server.listen()`

Starts the MCP server.

### stdio

```typescript theme={null}
await server.listen({
  transport: "stdio",
});
```

### HTTP

```typescript theme={null}
const result = await server.listen({
  transport: "http",
  port: 4000,
});

console.log(result.url);
```

HTTP listen results include information such as:

```typescript theme={null}
{
  transport: "http",
  port: 4000,
  host: "localhost",
  url: "http://localhost:4000/mcp"
}
```

### Port Resolution

The HTTP port is resolved in this order:

1. `listen()` option
2. `--port` command-line argument
3. `PORT` environment variable
4. `3000`

For example:

```typescript theme={null}
await server.listen({
  transport: "http",
  port: 4000,
});
```

takes precedence over:

```bash theme={null}
node server.js --port 5000
```

and:

```text theme={null}
PORT=6000
```

### Host

The HTTP host can be configured with:

```typescript theme={null}
await server.listen({
  transport: "http",
  host: "0.0.0.0",
  port: 4000,
});
```

### Silent Startup

Suppress the HTTP startup message with:

```typescript theme={null}
await server.listen({
  transport: "http",
  silent: true,
});
```

## `server.close()`

Closes the server and its underlying resources.

```typescript theme={null}
await server.close();
```

## `server.nativeServer`

Provides access to the underlying native MCP server.

```typescript theme={null}
const nativeServer = server.nativeServer;
```

This can be used when functionality from the official MCP SDK is required directly.

***

# Client

Import the client from:

```typescript theme={null}
import { MCPClient } from "mcpfy-sdk/client";
```

## `MCPClient`

Creates an MCP client.

### HTTP Server

```typescript theme={null}
const client = new MCPClient({
  mcpServers: {
    remote: { url: "http://localhost:4000/mcp" },
  },
});

const session = await client.createSession("remote");
```

### stdio Server

```typescript theme={null}
const client = new MCPClient({
  mcpServers: {
    local: { command: "node", args: ["dist/server.js"] },
  },
});

const session = await client.createSession("local");
```

The client determines the connection type from the server configuration.

A `transport` property is not required for stdio configuration.

***

# Resources

## `server.resource()`

Registers a resource.

```typescript theme={null}
server.resource(
  {
    name: "server-info",
    uri: "info://server",
    description: "Server information",
    mimeType: "text/plain",
  },
  async () => ({
    contents: [
      {
        uri: "info://server",
        text: "Server information",
      },
    ],
  })
);
```

The callback receives the tool context. The registered URI is available from the definition.

## `server.resourceTemplate()`

Registers a resource template.

The callback signature receives:

```typescript theme={null}
(uri, params, ctx)
```

Example:

```typescript theme={null}
server.resourceTemplate(
  {
    name: "user-profile",
    uriTemplate: "user://{id}",
    description: "User profile",
    mimeType: "text/plain",
  },
  async (uri, params, ctx) => ({
    contents: [
      {
        uri: uri.href,
        text: `User: ${params.id}`,
      },
    ],
  })
);
```

The parameters are:

* `uri` — resolved resource URI
* `params` — values extracted from the template
* `ctx` — request context

***

# Prompts

Prompts are reusable prompt definitions exposed by an MCP server.

## Prompt Definition

Prompt arguments are described using a Zod schema.

```typescript theme={null}
server.prompt(
  {
    name: "greeting",
    description: "Create a greeting",
    schema: z.object({
      name: z.string(),
    }),
  },
  async ({ name }) => {
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Greet ${name}`,
          },
        },
      ],
    };
  }
);
```

The prompt definition uses `schema`; there is no `arguments` property on the prompt definition.

***

# Context

Tool and resource callbacks can receive a context object.

## `ctx.log()`

Logs a message using a specified level.

```typescript theme={null}
ctx.log("info", "Processing request");
```

The first argument is the log level and the second is the message.

***

# Authentication

Import the authentication helpers from the server package:

```typescript theme={null}
import {
  jwksVerifier,
} from "mcpfy-sdk/server";
```

## `jwksVerifier()`

Creates a JWT verifier using a JWKS endpoint.

```typescript theme={null}
const verifyToken = jwksVerifier({
  issuer: "https://auth.example.com",
  jwksUri: "https://auth.example.com/.well-known/jwks.json",
  audience: "my-mcp-server",
});
```

Use it in the server configuration:

```typescript theme={null}
const issuer = "https://auth.example.com";

const server = new MCPServer({
  name: "protected-server",
  version: "1.0.0",
  auth: {
    type: "oauth",
    verifyToken: jwksVerifier({
      issuer,
      jwksUri: `${issuer}/.well-known/jwks.json`,
      audience: "my-mcp-server",
    }),
    authorizationServers: [issuer],
  },
});
```

The authentication discriminant is:

```typescript theme={null}
type: "oauth"
```

not:

```typescript theme={null}
type: "jwt"
```

## `NodeOAuthClientProvider`

For Node.js OAuth clients, create the provider through its static `create()` method:

```typescript theme={null}
const provider = await NodeOAuthClientProvider.create({
  // provider options
});
```

The constructor is private and should not be called directly.

## `ensureAuthorized()`

Ensures that an OAuth provider is authorized for a server.

```typescript theme={null}
await ensureAuthorized(
  provider,
  serverUrl
);
```

Both the provider and the target server URL are required.

Example:

```typescript theme={null}
const serverUrl = "https://example.com/mcp";

await ensureAuthorized(
  provider,
  serverUrl
);
```

***

# Authentication Header Forwarding

mcpfy exposes helpers for forwarding supported authentication headers to upstream services.

## `extractForwardableAuthHeaders`

Extracts supported authentication headers from incoming headers.

```typescript theme={null}
import type { IncomingMessage } from "node:http";
import {
  extractForwardableAuthHeaders,
  forwardAuthHeaders,
} from "mcpfy-sdk/server";

async function fetchUpstream(request: IncomingMessage) {
  const requestHeaders = extractForwardableAuthHeaders(request);
  return fetch("https://api.example.com/data", {
    headers: forwardAuthHeaders({ requestHeaders }),
  });
}
```

## `forwardAuthHeaders`

Prepares supported authentication headers for forwarding:

```typescript theme={null}
import type { ToolContext } from "mcpfy-sdk/server";

async function fetchWithContext(ctx: Pick<ToolContext, "requestHeaders" | "auth">) {
  return fetch("https://api.example.com/data", {
    headers: forwardAuthHeaders(ctx),
  });
}
```

## `FORWARDABLE_AUTH_HEADER_NAMES`

The SDK exports:

```typescript theme={null}
FORWARDABLE_AUTH_HEADER_NAMES
```

This identifies the authentication-related header names that can be forwarded.

Applications should not blindly forward arbitrary inbound headers.

***

# Widgets

Widgets can be associated with tools.

```typescript theme={null}
server.tool(
  {
    name: "weather",
    description: "Get weather information",
    schema: z.object({
      city: z.string(),
    }),
    widget: "weather",
  },
  async ({ city }) => {
    return object({
      city,
      temperature: 24,
    });
  }
);
```

The widget name corresponds to the widget directory:

```text theme={null}
src/widgets/weather/
```

The standard entry point is:

```text theme={null}
src/widgets/weather/main.tsx
```

Build widgets using:

```bash theme={null}
mcpfy build
```

For development:

```bash theme={null}
mcpfy dev
```

See [Widgets](widgets.md).

***

# Widget Content

Widget content can be represented as HTML:

```typescript theme={null}
{
  type: "html",
  html: "<div>Hello</div>",
}
```

or as a URL:

```typescript theme={null}
{
  type: "url",
  url: "https://example.com/widget",
}
```

HTML should not be supplied as a bare string.

## Widget Size

Widget dimensions use a width/height tuple:

```typescript theme={null}
size: ["800px", "600px"]
```

***

# Widget React APIs

The React integration is available through the widget React package.

Common APIs include:

* `useHostProtocol()`
* `useCallTool()`
* `useToolPayload()`
* `CallToolHandle`

For detailed React integration, see [Widget React](widget-react.md).

***

# Widget Bridge

The widget bridge provides communication between widget applications and the MCP host.

The package exposes APIs including:

```typescript theme={null}
postIntent
postNotify
postToolCall
postPrompt
postLink
connectMcpApps
App
PostMessageTransport
getOpenAiGlobal
mcpUiActions
```

These APIs allow widget applications to communicate with the host runtime.

***

# CLI

mcpfy provides CLI commands for widget development and production builds.

## mcpfy dev

Starts the development workflow:

```bash theme={null}
mcpfy dev
```

## `mcpfy build`

Builds widget assets for production:

```bash theme={null}
mcpfy build
```

Production deployments should run the build before starting a server that depends on built widgets.

***

# `create-mcpfy-app`

For a new project, the recommended fast-start command is:

```bash theme={null}
npx create-mcpfy-app@latest
```

This creates a new mcpfy application using the project scaffolding provided by the SDK ecosystem.

***

# Complete Example

The following example combines the core APIs:

```typescript theme={null}
import {
  MCPServer,
  object,
  text,
} from "mcpfy-sdk/server";
import { z } from "zod";

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

server.tool(
  {
    name: "add",
    description: "Add two numbers",
    schema: z.object({
      a: z.number(),
      b: z.number(),
    }),
  },
  async ({ a, b }) => {
    return object({
      result: a + b,
    });
  }
);

server.tool(
  {
    name: "greet",
    description: "Greet a person",
    schema: z.object({
      name: z.string(),
    }),
  },
  async ({ name }) => {
    return text(`Hello, ${name}!`);
  }
);

server.resource(
  {
    name: "server-info",
    uri: "info://server",
    description: "Server information",
    mimeType: "text/plain",
  },
  async () => ({
    contents: [
      {
        uri: "info://server",
        text: "Calculator MCP server",
      },
    ],
  })
);

await server.listen({
  transport: "http",
  port: 4000,
});
```

The server exposes:

* two executable tools
* one MCP resource
* an HTTP MCP endpoint
* structured and text tool responses

For complete guides and usage examples, see the individual documentation pages for servers, clients, tools, resources, prompts, widgets, and authentication.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.