Skip to main content
The useMcpAppContext hook is a low-level hook that subscribes to context values from the MCP Apps host. This hook powers many of the other Skybridge hooks when running in MCP Apps clients and can be used directly when you need access to specific context values.
For most use cases, prefer using the specialized hooks like useLayout, useUser, useToolInfo, etc., as they provide a more convenient API that works across both runtimes.

​
Basic usage

import { useMcpAppContext } from "skybridge/web";

function ThemeDisplay() {
  const theme = useMcpAppContext("theme");

  return <p>Current theme: {theme}</p>;
}

​
Parameters

​
key

key: keyof McpAppContext
Required The key of the context value to subscribe to. Available keys include:
KeyTypeDescription
theme"light" | "dark"The current color theme
localestringThe user’s locale (e.g., "en-US")
displayMode"inline" | "fullscreen"The widget’s display mode
maxHeightnumberMaximum height available for the widget
toolInputobject | nullThe input arguments passed to the tool
toolResultobject | nullThe tool execution result
toolCancelledobject | nullTool cancellation details (if cancelled)

​
options

options?: { appInfo?: { name: string; version: string } }
Optional Initialization options for the MCP App bridge. Only used on first instantiation.

​
requestTimeout

requestTimeout?: number
Optional Timeout in milliseconds for the initialization request. Defaults to 10000 (10 seconds).

​
Returns

value: McpAppContext[K] | undefined
The current value of the specified context key, or undefined if not yet available.

​
Examples

​
Reading Theme

import { useMcpAppContext } from "skybridge/web";

function ThemedWidget() {
  const theme = useMcpAppContext("theme");

  return (
    <div style={{
      backgroundColor: theme === "dark" ? "#1a1a1a" : "#ffffff",
      color: theme === "dark" ? "#ffffff" : "#000000"
    }}>
      <p>Current theme: {theme}</p>
    </div>
  );
}

​
Accessing Tool Input

import { useMcpAppContext } from "skybridge/web";

function ToolInputDisplay() {
  const toolInput = useMcpAppContext("toolInput");

  if (!toolInput) {
    return <p>No tool input yet...</p>;
  }

  return (
    <div>
      <h3>Tool Input:</h3>
      <pre>{JSON.stringify(toolInput, null, 2)}</pre>
    </div>
  );
}

​
Checking Tool Result

import { useMcpAppContext } from "skybridge/web";

function ToolResultDisplay() {
  const toolResult = useMcpAppContext("toolResult");
  const toolCancelled = useMcpAppContext("toolCancelled");

  if (toolCancelled) {
    return <p>Tool was cancelled: {toolCancelled.reason}</p>;
  }

  if (!toolResult) {
    return <p>Waiting for tool result...</p>;
  }

  return (
    <div>
      <h3>Tool Result:</h3>
      <pre>{JSON.stringify(toolResult, null, 2)}</pre>
    </div>
  );
}

​
Multiple Context Values

import { useMcpAppContext } from "skybridge/web";

function EnvironmentInfo() {
  const theme = useMcpAppContext("theme");
  const locale = useMcpAppContext("locale");
  const displayMode = useMcpAppContext("displayMode");
  const maxHeight = useMcpAppContext("maxHeight");

  return (
    <div>
      <h3>MCP App Environment</h3>
      <ul>
        <li>Theme: {theme}</li>
        <li>Locale: {locale}</li>
        <li>Display Mode: {displayMode}</li>
        <li>Max Height: {maxHeight}px</li>
      </ul>
    </div>
  );
}

​
Type Reference

​
McpAppContext

type McpAppContext = McpUiHostContext & McpToolState;
Combines the host context from the MCP ext-apps spec with tool execution state.

​
McpToolState

type McpToolState = {
  toolInput: Record<string, unknown> | null;
  toolResult: {
    content: Array<{ type: string; text?: string }>;
    isError?: boolean;
  } | null;
  toolCancelled: {
    reason?: string;
  } | null;
};