---
title: "Server utilities"
description: "Full signatures for the auto-imported Nitro/server helpers."
canonical_url: "https://nuxt-backend.dev/docs/reference/nuxt/server-utilities"
---
# Server utilities

> Full signatures for the auto-imported Nitro/server helpers.

Auto-imported in the `server/` directory and Nitro handlers: the fetch and preload helpers (which mirror the official `convex/nextjs` API surface), `backendAuth`, and the two agent-tool utilities.

## Fetch & preload

```ts
function fetchQuery<Q extends FunctionReference<'query'>>(
  query: Q, ...args: ArgsAndOptions<Q, NuxtConvexOptions>      // (args?, options?)
): Promise<FunctionReturnType<Q>>

function fetchMutation<M extends FunctionReference<'mutation'>>(
  mutation: M, ...args: ArgsAndOptions<M, NuxtConvexOptions>
): Promise<FunctionReturnType<M>>

function fetchAction<A extends FunctionReference<'action'>>(
  action: A, ...args: ArgsAndOptions<A, NuxtConvexOptions>
): Promise<FunctionReturnType<A>>

function preloadQuery<Q extends FunctionReference<'query'>>(
  query: Q, ...args: ArgsAndOptions<Q, NuxtConvexOptions>
): Promise<Preloaded<Q>>

function preloadedQueryResult<Q extends FunctionReference<'query'>>(preloaded: Preloaded<Q>): FunctionReturnType<Q>

interface NuxtConvexOptions {
  token?: string  // JWT for an authenticated call
  url?: string    // defaults to the resolved backend URL
}
```

## `backendAuth(event)`

Per-request authenticated helper for the current H3 event. `backendAuth` is
auto-imported in Nitro handlers; the option and service types are exported from
the package entry:

```ts
import type { BackendAuthOptions, BackendAuthService } from 'nuxt-backend'

function backendAuth(event: H3Event, opts?: BackendAuthOptions): BackendAuthService
type BackendAuthOptions = GetTokenOptions & { convexSiteUrl?: string }

interface BackendAuthService {
  getToken(): Promise<string | undefined>
  isAuthenticated(): Promise<boolean>
  handler(): Promise<Response>
  preloadAuthQuery<Q extends FunctionReference<'query'>>(query: Q, args?: Q['_args']): Promise<Preloaded<Q>>
  fetchAuthQuery<Q extends FunctionReference<'query'>>(query: Q, args?: Q['_args']): Promise<FunctionReturnType<Q>>
  fetchAuthMutation<M extends FunctionReference<'mutation'>>(mutation: M, args?: M['_args']): Promise<FunctionReturnType<M>>
  fetchAuthAction<A extends FunctionReference<'action'>>(action: A, args?: A['_args']): Promise<FunctionReturnType<A>>
}
```

<tip to="https://nuxt-backend.dev/docs/data/server-rendering">

For usage examples and the SSR preloading flow, see the Server & SSR guide.

</tip>

## `useBackendMcp(event?)` and `defineBackendMcpTool(definition)`

The agent-surface utilities, auto-imported in `server/` and also exported from
`nuxt-backend/mcp`. Experimental, like the rest of `nuxt-backend/mcp` (see
`STABILITY.md`).

```ts
import { defineBackendMcpTool, useBackendMcp } from 'nuxt-backend/mcp'

// The authenticated agent behind the current MCP request. Pass the H3 event
// where you have it; without one the request comes from Nitro's async
// context. Throws a 401 H3Error outside the MCP gate.
function useBackendMcp(event?: H3Event): BackendMcp
interface BackendMcp {
  session: BackendMcpSession   // { userId, clientId, scopes, convexToken }
  hasScope(scope: string): boolean
  // The fetchers above, bound to the agent's short-lived user JWT
  fetchQuery<Q extends FunctionReference<'query'>>(query: Q, args?: FunctionArgs<Q>): Promise<FunctionReturnType<Q>>
  fetchMutation<M extends FunctionReference<'mutation'>>(mutation: M, args?: FunctionArgs<M>): Promise<FunctionReturnType<M>>
  fetchAction<A extends FunctionReference<'action'>>(action: A, args?: FunctionArgs<A>): Promise<FunctionReturnType<A>>
}

// The MCP toolkit's `defineMcpTool` plus the agent-session contract: the tool
// is hidden without a session or the required `scope`, and the scope is
// re-checked when the handler runs. Your own `enabled` guard runs after that.
function defineBackendMcpTool<InputSchema extends ZodRawShape | undefined, OutputSchema extends ZodRawShape>(
  definition: McpToolDefinition<InputSchema, OutputSchema> & { scope?: string },
): McpToolDefinition<InputSchema, OutputSchema>
```

<tip to="https://nuxt-backend.dev/docs/agents/mcp/custom-tools">

For the tool definition fields and a complete read/write example, see Custom tools.

</tip>


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.