API Client

@frontmcp/react/api turns OpenAPI operations into MCP tools that agents can call. It supports any HTTP client — fetch, axios, ky, or a custom wrapper with token refresh and interceptors.

import { useApiClient, parseOpenApiSpec, createFetchClient } from '@frontmcp/react/api';
import type { HttpClient, HttpRequestConfig, HttpResponse } from '@frontmcp/react';

useApiClient

Registers each API operation as an MCP tool. Tools are registered on mount and cleaned up on unmount.

import { useApiClient } from '@frontmcp/react/api';

useApiClient({
  baseUrl: 'https://api.example.com',
  operations: [
    {
      operationId: 'getUser',
      description: 'Get a user by ID',
      method: 'GET',
      path: '/users/{id}',
      inputSchema: {
        type: 'object',
        properties: { id: { type: 'string' } },
        required: ['id'],
      },
    },
  ],
  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
});

Query parameters and header parameters are sent from the operation’s parameters: an argument declared in: 'query' goes into the query string and one declared in: 'header' becomes a request header. Arrays and objects follow the parameter’s OpenAPI style and explode: a query argument defaults to form (an array repeats the key, an object sends each property as its own parameter) and may set style to spaceDelimited, pipeDelimited or deepObject (filter[owner]=ada); a header argument is comma-separated (x,y, or a=1,b=2 with explode: true). {param} placeholders in path are filled from the arguments and body is the request body. parseOpenApiSpec fills parameters from the spec; a hand-written operation lists them itself:

useApiClient({
  baseUrl: 'https://api.example.com',
  operations: [
    {
      operationId: 'searchUsers',
      description: 'Search users',
      method: 'GET',
      path: '/users',
      inputSchema: {
        type: 'object',
        properties: { q: { type: 'string' }, limit: { type: 'integer' } },
      },
      parameters: [
        { name: 'q', in: 'query' },
        { name: 'limit', in: 'query' },
      ],
    },
  ],
});
// api_searchUsers({ q: 'ada', limit: 5 }) → GET https://api.example.com/users?q=ada&limit=5

The options may be written inline: the tools are registered again only when prefix, server, or what an operation declares (id, description, method, path, input schema, parameters) changes. baseUrl, headers, client and fetch are read when a tool runs.

Options

Option	Type	Default	Description
`baseUrl`	`string`	—	Required. Base URL for all requests
`operations`	`ApiOperation[]`	—	Required. Operations to register as tools
`headers`	`Record<string, string> \| () => Record<string, string>`	—	Static headers or header factory
`prefix`	`string`	`'api'`	Tool name prefix
`client`	`HttpClient`	—	Custom HTTP client (takes precedence over `fetch`)
`fetch`	`typeof globalThis.fetch`	—	Deprecated. Use `client` instead
`server`	`string`	—	Target a named server

Tool Naming

Each operation becomes a tool named {prefix}_{operationId}. For example, with prefix 'api' and operationId 'getUser', the tool name is api_getUser.

HttpClient Interface

The HttpClient interface lets you inject any HTTP library. Implement a single request method:

interface HttpClient {
  request(config: HttpRequestConfig): Promise<HttpResponse>;
}

interface HttpRequestConfig {
  method: string;
  url: string;
  headers: Record<string, string>;
  body?: unknown;
}

interface HttpResponse {
  status: number;
  statusText?: string;
  data: unknown;
}

Axios Example

import axios from 'axios';
import type { HttpClient } from '@frontmcp/react';

const axiosClient: HttpClient = {
  request: async ({ method, url, headers, body }) => {
    const response = await axios({ method, url, headers, data: body });
    return {
      status: response.status,
      statusText: response.statusText,
      data: response.data,
    };
  },
};

useApiClient({
  baseUrl: 'https://api.example.com',
  operations,
  client: axiosClient,
});

Custom Client with Token Refresh

import type { HttpClient } from '@frontmcp/react';

function createAuthClient(getToken: () => string, refreshToken: () => Promise<string>): HttpClient {
  return {
    request: async (config) => {
      config.headers['Authorization'] = `Bearer ${getToken()}`;

      let response = await fetch(config.url, {
        method: config.method,
        headers: config.headers,
        body: config.body ? JSON.stringify(config.body) : undefined,
      });

      // Auto-refresh on 401
      if (response.status === 401) {
        const newToken = await refreshToken();
        config.headers['Authorization'] = `Bearer ${newToken}`;

        response = await fetch(config.url, {
          method: config.method,
          headers: config.headers,
          body: config.body ? JSON.stringify(config.body) : undefined,
        });
      }

      const data = await response.json().catch(() => response.text());
      return { status: response.status, statusText: response.statusText, data };
    },
  };
}

Backward Compatibility

The fetch option still works but is deprecated. When provided without client, it’s internally wrapped into an HttpClient. If both are provided, client takes precedence.

// Deprecated — still works
useApiClient({
  baseUrl: 'https://api.example.com',
  operations,
  fetch: customFetch,
});

// Recommended — use client
useApiClient({
  baseUrl: 'https://api.example.com',
  operations,
  client: createFetchClient(customFetch),
});

createFetchClient

A convenience factory that wraps a plain fetch function into the HttpClient interface:

import { createFetchClient } from '@frontmcp/react/api';

const client = createFetchClient(); // uses globalThis.fetch
const client = createFetchClient(myCustomFetch); // uses custom fetch

Useful when you want the generic HttpClient interface but still use fetch under the hood.

parseOpenApiSpec

Extracts ApiOperation[] from an OpenAPI 3.x JSON spec. Handles parameters, request bodies, and generates operation IDs when missing.

import { parseOpenApiSpec } from '@frontmcp/react/api';

const spec = await fetch('/openapi.json').then((r) => r.json());
const operations = parseOpenApiSpec(spec);

useApiClient({
  baseUrl: 'https://api.example.com',
  operations,
  client: myClient,
});

What Gets Extracted

operationId: From spec or auto-generated from {method}_{path}
description: From summary, description, or {METHOD} {path}
method: HTTP method (uppercase)
path: URL path with {param} placeholders
inputSchema: JSON Schema built from parameters + requestBody
parameters: where each parameter goes (path, query, header, cookie) and the style / explode it declares, so useApiClient sends query and header parameters as the spec lays them out (cookie parameters are not sent)

Headers Factory

The headers option can be a factory function that’s called fresh on every request. This is useful for dynamic auth tokens:

useApiClient({
  baseUrl: 'https://api.example.com',
  operations,
  client: myClient,
  headers: () => ({
    Authorization: `Bearer ${auth.getAccessToken()}`,
    'X-Request-ID': crypto.randomUUID(),
  }),
});

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

useApiClient

Options

Tool Naming

HttpClient Interface

Axios Example

Custom Client with Token Refresh

Backward Compatibility

createFetchClient

parseOpenApiSpec

What Gets Extracted

Headers Factory

​useApiClient

​Options

​Tool Naming

​HttpClient Interface

​Axios Example

​Custom Client with Token Refresh

​Backward Compatibility

​createFetchClient

​parseOpenApiSpec

​What Gets Extracted

​Headers Factory

useApiClient

Options

Tool Naming

HttpClient Interface

Axios Example

Custom Client with Token Refresh

Backward Compatibility

createFetchClient

parseOpenApiSpec

What Gets Extracted

Headers Factory