Skip to content
TanStackAI
MCP

MCP Client Input

An MCP server can pause a tool call and ask for input. It asks for one of these:

  • A form that the user fills in.
  • A sampling request that needs a model reply.

You want to show that request in your UI and send the answer back to the server. chat() does this with an interrupt: the run pauses, the UI answers, and the next run calls the tool again with the answer.

Quick setup

You need MCP Server Tools working first, with the client in mcp.clients.

  1. In your chat route, pass parentRunId and resume from the request to chat():
ts
// app/api/chat/route.ts
import {
  chat,
  chatParamsFromRequest,
  toServerSentEventsResponse,
} from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { createMCPClient } from '@tanstack/ai-mcp'

export async function POST(request: Request) {
  const params = await chatParamsFromRequest(request)
  const mcp = await createMCPClient({
    transport: {
      type: 'http',
      url: 'https://my-mcp-server.example.com/mcp',
    },
  })

  const stream = chat({
    adapter: openaiText('gpt-6.1-sol'),
    messages: params.messages,
    threadId: params.threadId,
    runId: params.runId,
    ...(params.parentRunId ? { parentRunId: params.parentRunId } : {}),
    ...(params.resume ? { resume: params.resume } : {}),
    mcp: { clients: [mcp] },
  })
  return toServerSentEventsResponse(stream)
}
  1. In the UI, read interrupts from useChat. For each MCP input interrupt, show the request and call resolveInterrupt with the answer, or call cancel():
tsx
import { useState } from 'react'
import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value)
}

function readMcpInput(
  metadata: Readonly<Record<string, unknown>> | undefined,
) {
  const payload = metadata?.['tanstack:interruptPayload']
  if (!isRecord(payload)) return undefined
  const kind = payload.kind
  if (kind !== 'form' && kind !== 'sampling') return undefined
  if (!isRecord(payload.request)) return undefined
  return { kind, request: payload.request }
}

export function McpInputPrompt() {
  const [answer, setAnswer] = useState('')
  const { interrupts } = useChat({
    threadId: 'thread-1',
    connection: fetchServerSentEvents('/api/chat'),
  })

  return (
    <>
      {interrupts.map((interrupt) => {
        if (!interrupt.id.startsWith('mcp_input_')) return null
        if (interrupt.kind !== 'generic') return null
        const input = readMcpInput(interrupt.metadata)
        if (!input) return null
        return (
          <form
            key={interrupt.id}
            onSubmit={(event) => {
              event.preventDefault()
              interrupt.resolveInterrupt({ value: answer })
            }}
          >
            <label>
              {String(input.request.message ?? interrupt.message)}
              <input
                value={answer}
                onChange={(event) => setAnswer(event.target.value)}
              />
            </label>
            <button type="submit">Send</button>
            <button type="button" onClick={() => interrupt.cancel()}>
              Cancel
            </button>
          </form>
        )
      })}
    </>
  )
}

Try it. When a tool asks for input, the form shows the question from the server. Type an answer and click Send. The tool call continues with your answer.

How it works

  1. The MCP server asks for input during a tool call.
  2. chat() ends the run with an interrupt. outcome.type is interrupt, and the interrupt id starts with mcp_input_.
  3. useChat shows the interrupt. The user answers.
  4. useChat sends the answer in a new run.
  5. chat() runs the tool again, and the MCP client sends the answer to the server.

The pause and the resume work on spec 2026. On spec 2025, the server asks the client for input in the middle of the tool call. chat() cannot pause that call, so the tool call fails.

What to send

The answer depends on the kind of the request.

  • form: send an object that matches request.requestedSchema. A server from createMCPServer asks for { value: string }. The MCP client sends the object as the accepted content.
  • sampling: send the model reply as a string. You can also send a full MCP CreateMessageResult.
  • cancel(): for a form, the server gets { action: 'cancel' }. A createMCPServer tool then ends with a tool error. For a sampling request, the tool call ends with an error.

To decline a form, send the full MCP answer: { action: 'decline' }.

Advanced

Read the pause on the server

The stream ends with one RUN_FINISHED chunk. You can read the interrupt there:

ts
import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { createMCPClient } from '@tanstack/ai-mcp'

const messages = [{ role: 'user' as const, content: 'Ask the server' }]

const mcp = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://my-mcp-server.example.com/mcp',
  },
})

const stream = chat({
  adapter: openaiText('gpt-6.1-sol'),
  messages,
  threadId: 'thread-1',
  mcp: { clients: [mcp] },
})

for await (const chunk of stream) {
  if (chunk.type !== 'RUN_FINISHED') continue
  if (chunk.outcome?.type !== 'interrupt') continue

  for (const interrupt of chunk.outcome.interrupts) {
    if (!interrupt.id.startsWith('mcp_input_')) continue
    const payload = interrupt.metadata?.['tanstack:interruptPayload']
    console.log(interrupt.id, payload)
  }
}

During the pause:

  • The input call has no tool result.
  • The run does not emit RUN_ERROR.
  • When other tools finish in the same turn, the stream has their results.

Interrupt fields

FieldValue
idmcp_input_ and the tool call id. Find the pause by this id.
reasonDisplay text. The default is mcp_input. See the rules below.
messageInput required to run and the tool name.
metadata.toolNameThe tool name.
metadata['tanstack:interruptPayload']kind and request. kind is form or sampling. request is the MCP input body.

Rules for reason:

  • A tool can set another string, for example auth_required.
  • An empty reason stays mcp_input.
  • The reserved reason tanstack:client_tool_execution also stays mcp_input.

Answers on the resumed tool

  • A resumed tool gets the answer on ctx.inputResponse. The MCP tools read it for you. Your own server tool can read it too.
  • The client answers one input request for each tool call. If the server asks for input again after it gets the answer, the tool call ends with a tool error.

Which errors pause the run

If a tool throws a plain Error, the result is a tool error. The run does not pause.

chat() pauses only for a thrown value with this shape:

  • name: MCPInputRequiredError
  • kind: form or sampling
  • request: the MCP input body
  • reason (optional): the reason of the interrupt. The default is 'mcp_input'.

A tool can throw this shape with its own reason, for example auth_required. The interrupt id stays mcp_input_<toolCallId>, and the resume uses the same id. reason is only display text, so find the pause by its id.

Outside chat()

Outside chat(), the client throws MCPInputRequiredError. In this sample, ask is the tool name on your server.

  1. Call tools() on the MCP client.
  2. Call execute on the tool.
  3. Test the error with isMCPInputRequiredError, then read kind and request.
  4. Close the client after the call.
ts
import { createMCPClient, isMCPInputRequiredError } from '@tanstack/ai-mcp'

export async function callAsk() {
  const mcp = await createMCPClient({
    transport: {
      type: 'http',
      url: 'https://my-mcp-server.example.com/mcp',
    },
  })

  try {
    const tools = await mcp.tools()
    const ask = tools.find((tool) => tool.name === 'ask')
    if (!ask?.execute) return
    await ask.execute({})
  } catch (error) {
    if (!isMCPInputRequiredError(error)) throw error
    console.log(error.kind, error.request)
  } finally {
    await mcp.close()
  }
}
Edit on GitHub
MCP Type Generation
MCP Server Tools: Advanced