registerTool

registerTool adds an action the model can call to your server, optionally rendering its result through a view.

Example

search-products searches the store catalog for the signed-in user and renders the matches in the carousel view.

server.ts

import { McpServer } from "skybridge/server";
import { z } from "zod";

const server = new McpServer({ name: "shop", version: "1.0" }).registerTool(
  {
    name: "search-products",
    title: "Search products",
    description: "Search the store catalog by keyword and optional price ceiling.",
    inputSchema: {
      query: z.string().describe("What the shopper is looking for"),
    },
    outputSchema: {
      productIds: z.array(z.string()).describe("The IDs of products matching the query."),
    },
    annotations: { readOnlyHint: true },
    securitySchemes: [{ type: "oauth2", scopes: ["catalog.read"] }],
    view: {
      component: "carousel",
      csp: { connectDomains: ["https://api.myshop.com"] },
    },
  },
  async ({ query, maxPrice }, { authInfo }) => {
    const userId = authInfo.extra?.sub as string;
    const products = await search(query, { maxPrice, userId });
    return {
      content: `Found ${products.length} products for "${query}".`,
      structuredContent: { products },
    };
  },
);

Signature

server.registerTool(config: ToolConfig, handler: ToolHandler): McpServer;

Config

The first argument declares the tool.

type ToolConfig = {
  name: string;
  title?: string; // human-readable label
  description?: string; // model-facing: decides when the model calls the tool
  inputSchema?: ZodRawShape; // Zod shape; validates the call and types the handler input
  outputSchema?: ZodRawShape; // Zod shape; types structuredContent
  annotations?: ToolAnnotations; // standard MCP hints
  view?: ViewConfig; // bind a view to render the result
  auth?: { allowsAnonymous?: boolean; scopes?: string[] }; // per-tool auth
  securitySchemes?: SecurityScheme[]; // low-level alternative to `auth` (mutually exclusive)
  _meta?: ToolMeta; // extra metadata
};

`name`, `title`, `description`

All three are the tool’s prompt surface: the model reads them to decide when to call it, so write each for the model. name is also the identifier the call uses, and title a short display name.

`inputSchema`, `outputSchema`

Zod raw shapes. inputSchema validates the call arguments and types the handler’s input. Add .describe() to a field to tell the model what it’s for. outputSchema tells the model the shape to expect back, it does not type the returned value.

`annotations`

Standard MCP hints describing what the tool does, so the host can label it and order calls. They are hints: the host may surface or ignore them, and never gates a call on them.

type ToolAnnotations = {
  title?: string;
  readOnlyHint?: boolean;
  destructiveHint?: boolean;
  idempotentHint?: boolean;
  openWorldHint?: boolean;
};

Hint	Meaning	Default
`title`	Human-readable label; the host gives it precedence over `name`.	none
`readOnlyHint`	The tool does not modify its environment.	`false`
`destructiveHint`	The tool may perform destructive updates, not only additive ones. Meaningful only when `readOnlyHint` is `false`.	`true`
`idempotentHint`	Repeating the call with the same arguments has no further effect. Meaningful only when `readOnlyHint` is `false`.	`false`
`openWorldHint`	The tool interacts with an open world of external entities, not a closed domain.	`true`

`view`

Bind the tool to a React view to render its result instead of plain text. Each view backs exactly one tool.

type ViewConfig = {
  component: ViewName;
  description?: string;
  hosts?: Array<"apps-sdk" | "mcp-app">;
  prefersBorder?: boolean;
  domain?: string;
  csp?: ViewCsp;
  _meta?: Record<string, unknown>;
};

Key	Purpose
`component`	The view’s file name, type-checked against your views.
`description`	Label the host may show during view discovery.
`hosts`	Restrict where the view renders; defaults to all.
`prefersBorder`	Apps SDK only: request a visible border around the view.
`domain`	Apps SDK only: override the served domain (advanced).
`csp`	Per-view CSP overrides; see below.
`_meta`	Free-form metadata forwarded on the view resource.

`csp`

A view runs in a sandboxed iframe; your server’s domain is allowlisted automatically. Add external origins per directive:

type ViewCsp = {
  resourceDomains?: string[];
  connectDomains?: string[];
  frameDomains?: string[];
  redirectDomains?: string[];
  baseUriDomains?: string[];
};

Directive	Purpose
`resourceDomains`	Static assets: images, fonts, scripts, styles.
`connectDomains`	Fetch / XHR targets.
`frameDomains`	Iframe embed origins (opts into stricter app review).
`redirectDomains`	`openExternal` targets that skip the safe-link modal.
`baseUriDomains`	`<base href>` origins (MCP Apps only).

`auth`

The recommended way to declare a tool’s auth. With the oauth provider option set, Skybridge enforces the declaration for you (anonymous or under-scoped calls are rejected before the handler runs).

Value	Meaning
omitted (default)	Requires sign-in, the secure default when the server has an `oauth` provider.
`{ allowsAnonymous: true }`	Callable signed out; uses the token when one is present.
`{ scopes: [...] }`	Requires sign-in with every listed scope.
`{ allowsAnonymous: true, scopes: [...] }`	Callable signed out; a signed-in caller missing a listed scope gets a step-up challenge (`insufficient_scope`) instead of the anonymous path.

Declaring any { allowsAnonymous: true } tool turns the server mixed: it serves anonymous callers, and every other tool stays sign-in-gated by default. Requiring sign-in ({ scopes }) needs the oauth provider and throws without it; { allowsAnonymous: true } works either way. Omit auth entirely for the secure default (sign-in required whenever the server has auth).

`securitySchemes`

The low-level form behind auth, for cases it can’t express (several alternative oauth2 schemes, or pure noauth that never accepts a token). Mutually exclusive with auth.

type SecurityScheme =
  | { type: "noauth" }
  | { type: "oauth2"; scopes?: string[] };

Across the array, match any. Each entry is an alternative.
Within an oauth2 entry’s scopes, match all. The token must carry every listed scope.
noauth and oauth2 together means “works anonymously, but auth unlocks more.”

With the oauth provider option, Skybridge enforces securitySchemes like auth. With hand-wired middleware (requireBearerAuth or optionalBearerAuth) it stays client-facing metadata: enforce the tool’s requirements in the handler from extra.authInfo.

`_meta`

Metadata on the tool. Skybridge recognizes the keys below; any other key you set is forwarded on the tool’s _meta untouched.

type ToolMeta = {
  ui?: { visibility?: Array<"model" | "app"> };
  "openai/toolInvocation/invoking"?: string;
  "openai/toolInvocation/invoked"?: string;
  "openai/fileParams"?: string[];
  [key: string]: unknown;
};

Key	Purpose
`ui.visibility`	Expose the tool to the model, the app, or both.
`openai/toolInvocation/invoking`, `invoked`	Status text shown while the tool runs and after it completes.
`openai/fileParams`	Top-level input fields that carry file references; see `FileRef`.
`openai/widgetAccessible`	Deprecated, use `ui.visibility`.

The openai/* keys are read only on ChatGPT. openai/widgetAccessibleis deprecated, prefer ui.visibility instead.

Handler

Runs when the tool is called. It receives the validated input (typed from inputSchema) and the request context extra:

type ToolHandler = (input: Input, extra: RequestHandlerExtra) => Promise<{
  content?: string | ContentBlock | ContentBlock[];
  structuredContent?: Record<string, unknown>;
  isError?: boolean;
  _meta?: Record<string, unknown>;
}>;

`extra`

The request context.

Field	Purpose
`authInfo`	Validated token from an auth middleware: `clientId`, `scopes`, `extra`.
`requestInfo`	The HTTP request: headers and URL.
`signal`	An `AbortSignal`, aborted when the call is cancelled.
`_meta`	Client hints (below).

Return

Field	Purpose
`content`	Text for the model, shown in the conversation. A string, a `ContentBlock`, or an array.
`structuredContent`	Typed data the model and the view read (via `useToolInfo`).
`isError`	Marks the call as failed.
`_meta`	View-only response metadata, hidden from the model.

For a view tool, Skybridge adds a viewUUID to _meta, a reserved key used for state persistence.

Client hints

ChatGPT attaches conversation context to extra._meta. They are hints: tolerate their absence and never use them for authorization.

type ClientHintsMeta = {
  "openai/locale"?: string;
  "openai/userAgent"?: string;
  "openai/userLocation"?: {
    city?: string;
    region?: string;
    country?: string;
    timezone?: string;
    longitude?: number;
    latitude?: number;
  };
  "openai/subject"?: string;
  "openai/session"?: string;
  "openai/organization"?: string;
  "openai/widgetSessionId"?: string;
};

Key	Purpose
`openai/locale`	Requested locale, BCP-47, e.g. `en-US`.
`openai/userAgent`	Browser user-agent of the ChatGPT client.
`openai/userLocation`	Coarse location: `city`, `region`, `country`, `timezone`, `latitude`, `longitude` (each optional).
`openai/subject`	Anonymized user id.
`openai/session`	Anonymized conversation id, stable within a session.
`openai/organization`	Anonymized organization id, when the user account is in an organization.
`openai/widgetSessionId`	Stable id for the mounted view instance.

These hints are ChatGPT only.

Content helpers

skybridge/server exports helpers that build ContentBlocks for the handler’s content:

import { audio, embeddedResource, image, resourceLink, text } from "skybridge/server";

return {
  content: [text("Here's your chart:"), image(pngBuffer, "image/png")],
  structuredContent: { /* ... */ },
};

Helper	Block
`text(value, annotations?)`	`TextContent`
`image(data, mimeType, annotations?)`	`ImageContent` (base64)
`audio(data, mimeType, annotations?)`	`AudioContent` (base64)
`embeddedResource(resource, annotations?)`	`EmbeddedResource`
`resourceLink(link, annotations?)`	`ResourceLink`

Returning plain ContentBlock objects works too; the helpers are optional.

McpServer

The server you register tools on

useToolInfo

Read the tool’s result in the view

FileRef

Pass files in and out of a tool

Server

Auth

Identity Providers

Hooks

Utilities

Types

Low-level

Example

Signature

Config

`name`, `title`, `description`

`inputSchema`, `outputSchema`

`annotations`

`view`

`csp`

`auth`

`securitySchemes`

`_meta`

Handler

`extra`

Return

Client hints

Content helpers

McpServer

useToolInfo

FileRef

​Example

​Signature

​Config

​name, title, description

​inputSchema, outputSchema

​annotations

​view

​csp

​auth

​securitySchemes

​_meta

​Handler

​extra

​Return

​Client hints

​Content helpers

McpServer

useToolInfo

FileRef

Example

Signature

Config

`name`, `title`, `description`

`inputSchema`, `outputSchema`

`annotations`

`view`

`csp`

`auth`

`securitySchemes`

`_meta`

Handler

`extra`

Return

Client hints

Content helpers