DEV Community: Maksim Kachurin

MCP Elicitation: Human-in-the-Loop for MCP Servers

Maksim Kachurin — Thu, 14 Aug 2025 17:24:56 +0000

TL;DR

MCP Elicitation provides a standardized way for servers to request additional input from users through the client during a session.
In this article, I break down what problems it solves, and walk through building an MCP server and client with elicitation support — including a real chat UI that shows confirmation prompts to the user.

What is MCP

The Model Context Protocol (MCP) is an open standard developed by Anthropic that enables LLMs to receive data from any backend or application in a single, standardized format.

Before MCP, developers of agent-based AI systems had to rely on custom tools and logic to access the APIs of third-party applications. It was a tedious, manual process that didn’t scale well — every integration had to be built and maintained by the agent developers themselves.

MCP shifts that responsibility: now application developers can expose their APIs in a unified format that most models and agent frameworks can understand out of the box.

MCP evolution: update of June 18, 2025

The protocol keeps evolving and gaining new features. At the time of writing, the latest update was released on June 18, 2025, and here’s what it introduced:

Structured tool output
Tools can now return structured data instead of plain strings. This makes results easier to parse and enables more advanced pipelines. Many agent frameworks already supported structured output for tools declared within the agent itself — now that capability is officially part of the MCP spec as well.
OAuth 2.1: Resource Server + Resource Indicators
MCP servers are now treated as full OAuth Resource Servers. Clients must use Resource Indicators (RFC 8707) to ensure access tokens aren't misused across different servers.
Resource links in tool call results
Tool responses can now include links to external resources — such as files, logs, or pages — in addition to raw data.
Elicitation
This one's a game-changer: servers can now ask users for input during a session, via the client, with validation handled through JSON Schema. This opens up a new kind of UX for agent interactions.

What is elicitation?

Elicitation is a mechanism in MCP that lets the server pause a tool’s execution until the client provides missing data from the user. A similar concept exists in agent frameworks — often called HITL (Human-In-The-Loop) — where the agent pauses its loop, asks the user for input, and then continues with updated data.

But MCP works differently. The MCP server is isolated: it runs independently, has no knowledge of the frontend, doesn’t control the UX, and can’t talk to the user directly. Typically, the architecture has three layers: the frontend, the agent (backend), and one or more MCP servers connected to the agent.
MCP only communicates with the agent — and that’s it.

MCP Connected to Agent

In this setup, an MCP tool might simply not have the data it needs — and no way to get it on its own.

Take a common case: you build an MCP server for table bookings. It exposes a bookTable tool. The chatbot calls it, but to complete the booking, the tool needs all the inputs — date, time, number of guests, names, special requests. Some of this might be missing, some might be wrong, or the requested slot might be unavailable.

Even without MCP, this kind of human-in-the-loop flow is rarely implemented cleanly in agent frameworks. The usual hack is to create a tool that returns no result — a signal to pause the agent loop. The frontend then renders a UI element (a form, confirm buttons, etc.) asking the user for additional data. Once the user submits, that data is attached as the tool's result, and a new request with updated message history is sent to the agent. The agent sees the original tool call plus the result and decides what to do next.

In this flow, the tool’s input comes from the LLM, and its output comes from the user.

Human-in-the-loop without MCP

In practice, you often have to define two tools:

one on the frontend for collecting or confirming data (gather_booking_info_tool)

and another on the backend for processing it (process_booking_tool)

This comes with a bunch of downsides — context loss on the backend, duplicate requests, extra token usage, and more.

Now, if you're building an MCP server, things get even messier. The tool has no shared execution context with the agent that called it. That means it can’t pause the loop, can’t directly ask for more input — it’s fully decoupled.

Elicitation fixes this. It gives MCP tools a way to request data from the client during execution — and actually wait for it.

MCP Tool with Elicitation

The best part? It all happens within a single request and session.
The server sends an elicitation request — it returns a Promise — and that Promise is resolved with user-provided data once the client responds.

Also this functionality can be used to notify the client about the current progress of the tool execution. MCP server can throw a request every time the task being executed changes, and the client can react to it and, for example, draw a progress bar in the interface.

Elicitation Protocol Format

When a tool realizes it’s missing data, it sends an elicitation/create request, passing a JSON Schema that describes the fields it needs.

For example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "elicitation/create",
  "params": {
    "message": "Please provide your GitHub username",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      },
      "required": ["name"]
    }
  }
}

There are 4 types of fields supported:

string

{
  "type": "string",
  "title": "Display Name",
  "description": "Description text",
  "minLength": 3,
  "maxLength": 50,
  "format": "email" // Supported: "email", "uri", "date", "date-time"
}

number

{
  "type": "number", // or "integer"
  "title": "Display Name",
  "description": "Description text",
  "minimum": 0,
  "maximum": 100
}

boolean

{
  "type": "boolean",
  "title": "Display Name",
  "description": "Description text",
  "default": false
}

enum

{
  "type": "string",
  "title": "Display Name",
  "description": "Description text",
  "enum": ["option1", "option2", "option3"],
  "enumNames": ["Option 1", "Option 2", "Option 3"]
}

In response, the protocol expects to receive a result with the action (accept, decline, cancel) and the requested data:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "accept",
    "content": {
      "name": "octocat"
    }
  }
}

Required action format:

action: "accept": Client explicitly approved and submitted with data
action: "decline": Client explicitly declined the request. The content field is typically omitted.
action: "cancel": Client dismissed without making an explicit choice.

The handler should handle each of these scenarios accordingly.

Create MCP server and MCP client with Elicitation support

I’m going to build an MCP server that runs over HTTP, along with a small chat app based on assistant-ui. Then I’ll wire elicitation requests straight into the UI.

MCP Server

Not all frameworks/sdk support elicitation yet. We can write code using the official modelcontextprotocol/sdk, but I’ll focus on Mastra — an open-source TypeScript agent framework that makes it easier to build agents, MCP servers, clients, and more.
Mastra is built on top of the AI SDK, so it works with most tools that support it.

For the server, I’m using Bun and Hono.js — that gives us a fast HTTP setup with support for multiple MCP servers in one service, plus WebSockets, auth server, and any other logic a real app might need.

Let’s start by creating a new project for the MCP server:

mkdir mcp-server && cd mcp-server

bun init -y

bun add typescript tsx @types/node mastra@latest @mastra/core@latest zod@^3 fetch-to-node hono -D

This commands will create a new project and install mastra.

Now create the necessary files

src/index.ts

import { Hono } from 'hono';

const app = new Hono();

import { toFetchResponse, toReqRes } from 'fetch-to-node';

import mcpServer from './mcp-server';

app.all('/mcp/server', async(c) => {
    const { req, res } = toReqRes(c.req.raw);

    await mcpServer.startHTTP({
        url: new URL(c.req.url),
        httpPath: '/mcp/server',
        req,
        res,
        options: {
            sessionIdGenerator: undefined,
        },
    });

    return await toFetchResponse(res);
});

export default {
    ...app,
    port: 4444,
};

Here we’re setting up a basic web server and mounting our mcpServer at the /mcp/server endpoint using the modern streamable HTTP protocol (You could also use HTTP + SSE, or connect to the MCP server directly via stdio — up to you)

The server will run on port 4444.

mcp-server.ts

import { MCPServer } from '@mastra/mcp';
import tools from './tools';

const mcpServer = new MCPServer({
    version: '0.1.0',
    name: 'MCP server for demonstration purposes',
    description: 'This MCP server shows how to use the MCP server API to create a server that can be used in a chat application.',
    tools,
});

export default mcpServer;

Here we define the MCP server itself — giving it a name, description, and the list of tools it exposes.

tools.ts

import { createTool } from '@mastra/core';
import { z } from 'zod';
import { spawn } from 'child_process';

export const runCommand = createTool({
    id: 'runCommand',
    description: 'Run a shell command on the server. Prompts for confirmation if the command is dangerous.',
    inputSchema: z.object({
        command: z.string().describe('The shell command to run, e.g., "ls"'),
        args: z.array(z.string()).optional().describe('Arguments for the command'),
    }),
    outputSchema: z.object({
        stdout: z.string(),
        stderr: z.string(),
        code: z.number(),
    }),
    async execute({ context }, options) {
        const dangerousCommands = ['rm', 'mv', 'dd', 'shutdown', 'reboot', 'mkfs', 'chmod', 'chown', 'kill', 'killall', 'poweroff', 'halt'];
        const cmd = context.command.trim();
        const args = context.args || [];

        // Ask for confirmation if the command is dangerous
        if (dangerousCommands.includes(cmd)) {
            const elicitation = (options as any)?.elicitation;

            if (!elicitation || typeof elicitation.sendRequest !== 'function') {
                return {
                    code: -1,
                    stdout: '',
                    stderr: 'Elicitation is not available in this context. Cannot confirm dangerous command.',
                }
            }

            const result = await elicitation.sendRequest({
                message: `Are you sure you want to run the dangerous command: '${cmd}'?`,
                requestedSchema: {
                    type: 'object',
                    properties: {
                        confirm: {
                            type: 'boolean',
                            title: 'Confirm',
                            description: `Confirm running '${cmd}'?`,
                        },
                    },
                    required: ['confirm'],
                },
            });

            if (result.action !== 'accept' || !result.content.confirm) {
                return {
                    code: -1,
                    stdout: '',
                    stderr: 'Command was rejected by the user.',
                }
            }
        }

        return new Promise((resolve, reject) => {
            const child = spawn(cmd, args, { shell: true });
            let stdout = '';
            let stderr = '';

            child.stdout.on('data', (data) => { stdout += data.toString(); });
            child.stderr.on('data', (data) => { stderr += data.toString(); });

            child.on('close', (code) => {
                resolve({ stdout, stderr, code: code ?? -1 });
            });

            child.on('error', (err) => {
                reject(err);
            });
        });
    },
});

export default {
    runCommand,
};

For this demo, I’m creating a single tool that runs shell commands on the server (don’t do this in a real app — it’s just for demonstration).
If the command looks dangerous (like rm or kill), the tool asks the user for confirmation before running it.

Now let’s start the MCP server:

bun src/index.ts

Agent + MCP Client

To demonstrate and create a UI agent, I will use assistance-ui.

Create a new Next.js project and install assistant-ui and mastra:

npx assistant-ui@latest create mcp-app
cd mcp-app 
bun add mastra -D

The command will create a new next.js application with a chat interface.

Create a file
.env.local

OPENAI_API_KEY=sk-proj-4fpws4nXpCYXsQVK7DdaUCdLNxMa...

And add your OPENAI API key here.

Now you can run the application and check that the chat works:

Basic assistant-ui chat interface

Now let's create a mastra Agent and connect our MCP server to it:

app/api/chat/route.ts

import { openai } from '@ai-sdk/openai';
import { frontendTools } from '@assistant-ui/react-ai-sdk';
import { Agent } from '@mastra/core';
import { MCPClient } from '@mastra/mcp';
import { createDataStreamResponse } from 'ai';

// Define the MCP server name and URL for connecting to the tool server
const MCP_SERVER_NAME = 'testing';
const MCP_SERVER_URL = 'http://localhost:4444/mcp/server';

// Initialize the MCP client with server configuration
const mcp = new MCPClient({
    id: '1', // Unique client ID
    servers: {
        [MCP_SERVER_NAME]: {
            url: new URL(MCP_SERVER_URL),
        },
    },
});

// Create an AI agent with a model, name, and instructions
const agent = new Agent({
    model: openai('gpt-4o'), // Use OpenAI GPT-4o model
    name: 'Chat Agent',
    instructions: `
    You are a helpful assistant that provides accurate information. 
    Do not ask questions before running tools, just run them. 
    If you see that the user rejects a tool call, then stop and do not try to find another way to perform the task.
    `,
});


// API route handler for POST requests
export async function POST(req: Request) {
    // Parse the incoming request body for chat messages, system prompt, and tool list
    const { messages, system, tools } = await req.json();

    // Create a streaming response for the chat
    const response = createDataStreamResponse({
        status: 200,
        statusText: 'OK',
        async execute(dataStream) {
            // Run the agent and stream its response to the client
            const agentStream = await agent.stream(messages, {
                system, // Optional system prompt
                toolsets: {
                    ...(await mcp.getToolsets()), // Dynamically load toolsets from MCP server
                },
                clientTools: frontendTools(tools), // Add any client-side tools
            });

            // Merge the agent's output into the HTTP data stream
            agentStream.mergeIntoDataStream(dataStream);
        },
        // Custom error handler for the stream
        onError: (error: any) => `Custom error: ${ error.message }`,
    });

    // Return the streaming response to the client
    return response;
}

This code handles incoming requests from the frontend: it creates an agent and an MCP client, then calls the agent.
The agent responds to the frontend using the Stream AI SDK format. It handles tool execution via MCP, processes the results, and can run multiple tools in parallel until it reaches a final answer.

Let’s check that our agent is working and sees the tools exposed by our MCP server:

Agent with MCP tools

Our runCommand tool already knows how to return an elicitation request when a potentially dangerous command (like rm) is detected.
Now it’s time to handle that elicitation request in our app.

app/api/chat/route.ts
In the execute method, add:

// Set up elicitation handler to respond to tool confirmation requests from the server
await mcp.elicitation.onRequest(MCP_SERVER_NAME, async(request) => {
    // Log the server's request and the schema it expects
    console.log('Server request:', request);

    await new Promise(resolve => setTimeout(resolve, 10_000));

    // Respond to the elicitation request
    // NOTE: The action must be one of 'accept', 'decline', or 'cancel' as per the MCP protocol
    // Here, we always decline (for tutorial purposes)
    return {
        action: 'decline',
        content: {
            confirm: false, // Indicate that the dangerous command is NOT confirmed
        },
    };
});

// Run the agent and stream its response to the client
const agentStream = await agent...

Here we subscribe to elicitation events from our MCP server and wait 10 seconds before automatically rejecting the request.

We can now test that the agent runs a safe command (e.g. creating a file), and pauses for 10 seconds when trying to run a dangerous one (like deleting it). After the timeout, it reports that the command wasn’t allowed:

MCP Elicitation decline

That works — but now we need to actually show the confirmation UI to the user.

Unfortunately, it’s not that simple. HTTP streaming only works one way — from the server to the client.
While the agent is responding, executing tools, and waiting for a reply from the MCP server, the frontend can’t send anything back on the same connection.

Because of this limitation, most frameworks require the current thread to be terminated when a tool asks the user for confirmation. Once the user responds, a new request is sent to the agent, where the user input is included as the tool’s result.

But this doesn’t work for us.

With MCP’s elicitation mechanism, the server is still waiting for a response from the backend via a Promise. The user’s confirmation isn’t the tool result — the real result will come later from MCP.
If we close the thread, we lose the connection to MCP, and its response will be dropped.

So we need a custom workaround — something outside the usual assistant-ui or AI SDK flow.

Here’s how I’m solving it:

When an elicitation request comes in, the backend stores the request data inside the current thread.
On the frontend, I’ll define a generative UI tool that shows the tool’s status and, if needed, renders confirmation buttons.

Clicking one of those buttons will trigger a separate request to a dedicated backend endpoint.
The backend will maintain a shared storage of elicitation Promises — so when a response comes in, it resolves the right one and continues the original MCP execution.

Forward elicitation request to the frontend

Let's get started:

First, let's create a Generative UI component for our runCommand tool.

@/components/assistant-ui/run-command-tool.tsx

import { ToolCallContentPartComponent, useMessage } from '@assistant-ui/react';
import { useState } from 'react';

import type { JSONValue } from 'ai';

type ElicitationData = {
    type: 'elicitation';
    toolCallId: string;
    message: string;
    requestedSchema: JSONValue;
};

export const RunCommandTool: ToolCallContentPartComponent = ({
    toolCallId,
    status,
    args,
    result,
}) => {
    const elicitation = useMessage(
        m => (m.metadata.unstable_data as ElicitationData[])?.find(
            d => d.type === 'elicitation' && d.toolCallId === toolCallId
        )
    );
    const content = result?.structuredContent;
    const [isSubmitting, setIsSubmitting] = useState(false);
    const [submitResult, setSubmitResult] = useState<string | null>(null);
    const isRunning = status.type === 'running';

    function handleElicitationResponse(action: 'accept' | 'decline') {
        setIsSubmitting(true);
        setSubmitResult(null);

        fetch('/api/chat/elicitation', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                toolCallId,
                action,
                content: {
                    confirm: action === 'accept',
                },
            }),
        }).then(async(res) => {
            const data = await res.json();

            setSubmitResult(data.success ? 'Submitted!' : 'Failed to submit');
        }).catch((err) => {
            setSubmitResult(`Error: ${ err.message }`);
        }).finally(() => {
            setIsSubmitting(false);
        });
    }

    return (
        <div className="flex flex-col gap-3 py-3 mb-4 w-full rounded-lg border">
            <div className="flex gap-2 items-center px-4">
                <code className="font-mono text-sm font-semibold">
                    { `${ args.command }${ (Array.isArray(args.args) && args.args.length > 0) ? ` ${ args.args.join(' ') }` : '' }` }
                </code>
            </div>

            {/* Elicitation while running, show button to accept or decline */}
            {(isRunning && elicitation != null) && (
                <div className="flex flex-col gap-2 px-4 pt-2 text-xs border-t border-dashed">
                    <pre className="whitespace-pre-wrap">
                        {elicitation.message}
                    </pre>
                    <div className="flex gap-2 mt-2">
                        <button
                            className="px-3 py-1 text-gray-800 bg-gray-200 rounded border border-gray-300 hover:bg-gray-300"
                            onClick={ () => handleElicitationResponse('accept') }
                            disabled={ isSubmitting }
                        >
                            Accept
                        </button>
                        <button
                            className="px-3 py-1 text-gray-800 bg-gray-200 rounded border border-gray-300 hover:bg-gray-300"
                            onClick={ () => handleElicitationResponse('decline') }
                            disabled={ isSubmitting }
                        >
                            Decline
                        </button>
                        {isSubmitting && <span className="ml-2">Submitting...</span>}
                        {submitResult && <span className="ml-2">{submitResult}</span>}
                    </div>
                </div>
            )}

            {/* Show the result of the tool call */}
            {content != null && (
                <div className="flex flex-col gap-2 px-4 pt-2 text-xs border-t border-dashed">
                    <pre className="whitespace-pre-wrap">
                        {typeof content === 'string'
                            ? content
                            : JSON.stringify(content, null, 2)}
                    </pre>
                </div>
            )}
        </div>
    );
};

In the component, we just display the command and its result.
If the current thread includes an active elicitation request, we also show Accept / Decline buttons.
Clicking a button sends a separate request to our backend at /api/chat/elicitation.

Finally, register the thread so assistant-ui can use it:

@/components/assistan-ui/thread.tsx

<MessagePrimitive.Content
    components={ {
        ...
        tools: {
            by_name: {
                runCommand: RunCommandTool,
            },
            Fallback: ToolFallback,
        },
    } }
/>

Now let’s update our elicitation handler on the backend to pass the data through to the frontend:

@/app/api/chat/route.ts

import { addElicitation, rejectElicitation } from './elicitation/elicitationStore';

...
async execute(dataStream) {
  let currentToolCallId: string | null = null;

  // Set up elicitation handler to respond to tool confirmation requests from the server
  await mcp.elicitation.onRequest(MCP_SERVER_NAME, async(request) => {
      const toolCallId = currentToolCallId;

      if (!toolCallId) {
          throw new Error('No tool call ID found');
      }

      const { promise, resolve, reject } = Promise.withResolvers<{
          action: 'accept' | 'decline' | 'cancel';
          content: {
              confirm: boolean;
          };
      }>();

      // Store the resolver globally for cross-request resolution
      addElicitation(toolCallId, resolve, reject);

      // Cancel the elicitation request after 60 seconds
      const timeout = setTimeout(() => {
          rejectElicitation(toolCallId, 'Timeout: elicitation cancelled');
      }, 60_000);

      dataStream.writeData({
          type: 'elicitation',
          toolCallId: currentToolCallId,
          message: request.message,
          requestedSchema: typeof request.requestedSchema?.toJSON === 'function'
              ? request.requestedSchema.toJSON()
              : request.requestedSchema,
      });

      return promise.catch((err) => {
          return {
              action: 'cancel',
              content: {
                  error: err.message,
              },
          };
      }).finally(() => {
          clearTimeout(timeout);
      });
  });

  // Run the agent and stream its response to the client
  const agentStream = await agent.stream(messages, {
      system,
      toolsets: {
          ...(await mcp.getToolsets()),
      },
      // Add any client-side tools
      clientTools: frontendTools(tools),
      onChunk: ({ chunk }) => {
          // Track the current tool call ID
          if ('toolCallId' in chunk) {
              currentToolCallId = chunk.toolCallId;
          }
      },
  });

  // Merge the agent's output into the HTTP data stream
  agentStream.mergeIntoDataStream(dataStream);
}

I use the writeData method to send extra info that the RunCommandTool component uses to show the Accept / Reject buttons.

Now all that’s left is to add the confirmation handler on the backend:

@/app/api/chat/elicitation/route.ts

import { resolveElicitation } from './elicitationStore';

export async function POST(req: Request) {
    const { toolCallId, action, content } = await req.json();
    const success = resolveElicitation(toolCallId, { action, content });

    return new Response(JSON.stringify({ success }), { status: 200 });
}

As well as a store for storing active elicitation requests:

@/app/api/chat/elicitation/elicitationStore.ts

type ElicitationResolver = (value: any) => void;
type ElicitationRejecter = (reason?: any) => void;

interface ElicitationEntry {
    resolve: ElicitationResolver;
    reject: ElicitationRejecter;
}

const elicitationMap = globalThis.elicitationMap || new Map<string, ElicitationEntry>();

if (!globalThis.elicitationMap) {
    globalThis.elicitationMap = elicitationMap;
}

export function addElicitation(toolCallId: string, resolve: ElicitationResolver, reject: ElicitationRejecter) {
    elicitationMap.set(toolCallId, { resolve, reject });
}

export function resolveElicitation(toolCallId: string, value: any) {
    const entry = elicitationMap.get(toolCallId);

    if (entry) {
        entry.resolve(value);
        elicitationMap.delete(toolCallId);

        return true;
    }

    return false;
}

export function rejectElicitation(toolCallId: string, reason?: any) {
    const entry = elicitationMap.get(toolCallId);

    if (entry) {
        entry.reject(reason);
        elicitationMap.delete(toolCallId);

        return true;
    }

    return false;
}

Keep in mind that in a real application you may be working with an edge runtime where this is not possible, or your backend is spread across multiple threads or even servers, in which case you can't just store Map with promises and you need some external solution like Redis with pub/sub or a separate websocket server. But the example above is enough for this article just to show the concept.

Done, check it out

Generative UI powered by MCP elicitation

On the first request, I'm asked to create and then immediately delete newfile.md. I click Decline, so the deletion is blocked.
On the second attempt, I click Accept, and the file is successfully deleted.

Conclusion

Elicitation fills a critical gap in the LLM agent architecture — it brings real user interaction into the loop without breaking flow or context.
With it, MCP servers can do more than just respond — they can ask. That’s a big shift.

Support across frameworks is still limited, but it’s only a matter of time. Frontend tools will catch up too — and when they do, building rich, dynamic agent flows will get way simpler.

Now you’ve got the core and you can go build something with it!

OpenAI Codex as a native agent in your TypeScript (Node.js) app

Maksim Kachurin — Tue, 17 Jun 2025 07:48:23 +0000

What is OpenAI Codex CLI

OpenAI Codex CLI is an open‑source command‑line tool that brings the power of our latest reasoning models directly to your terminal. It acts as a lightweight coding agent that can read, modify, and run code on your local machine to help you build features faster, squash bugs, and understand unfamiliar code. Because the CLI runs locally, your source code never leaves your environment unless you choose to share it.

Put simply — Codex is an AI-powered terminal agent that understands your codebase, makes edits, runs scripts, writes commits, and works entirely on your machine.

Key Functionality:

Multimodal input: pass text, screenshots, or diagrams
Reads your project structure, dependencies, and files
Can suggest or directly apply edits
Integrates with Git (commits, diffs, PRs)
Runs tests, migrations, and shell scripts inside a sandbox
Supports MCP server connections
Approval modes: from manual to fully autonomous

Example:

codex "write unit tests for utils/date.ts"

Codex will find the file, generate the tests, run them, and show the result. If everything passes, it offers to apply the changes.

One thing that sets it apart from tools like Claude Code — it supports multiple model providers, not just OpenAI. You can run it with Gemini, Groq, Anthropic, and any API-compatible LLM.

Why I need JS SDK?

Codex CLI is a powerful tool, but in fact it is just a binary that communicates via stdin/stdout.

It has a non-interactive mode where you can send a request and receive a response in the console. There is a pipe mode where Codex reads and writes JSON — this is closer to an API, but still raw.

You throw data at it in the right format → it responds in its own → you parse → deal with timings, errors, and sessions.

That's how the idea to make a JS SDK that works well with this process was born:

Runs Codex CLI from Node.js
Has a convenient interface for configuration, sending requests, accepting and rejecting changes
Allows you to subscribe to events and errors
Serializes commands and parses responses
TypeScript typed request / response types

What I built: codex-js-sdk

I made an SDK that runs Codex CLI inside a Node.js process and provides a convenient API on top of pipe mode.

You don't have to worry about stdin/stdout, fiddle with timings, write your own parser, or reverse engineer the communication protocol — just connect and use it like a regular LLM agent.

What it can do:
🔄 Runs and manages the Codex CLI process (start, stop, restart, abort)
✉️ Sends requests from the user
📎 Supports sending images
🧠 Allows you to confirm or cancel commands or file changes
📡 Allows you to subscribe to responses from LLM
🗂 Allows you to override configuration, configure providers, etc.

Quick start

First, you will need to install the codex itself.

IMPORTANT: JS SDK only works with the Native (Rust) version of codex. The functionality of the standard and Native versions may differ slightly, but OpenAI clearly plans to develop this version.

Keep in mind that OpenAI Codex itself was released two months ago and is still quite raw, while the Rust version was released a couple of weeks ago and the API protocol is likely to change actively.

Let's start the installation:

To install, run:

npm i -g @openai/codex@native

This will install codex globally (recommended). You can also install it locally in your project, but then you will have to pass the path to the bin file in the JS SDK configuration.

Codex also actively uses ripgrep, so it is also advisable to install it:
MacOS:

brew install ripgrep

Rust:

cargo install ripgrep

Ubuntu / Debian:

sudo apt install ripgrep

Then install the JS SDK in the project:

npm install codex-js-sdk

Next, in any Node.js code where you intend to work with codex:

1. Import the SDK code and types and create an instance

import { CodexSDK, LogLevel } from 'codex-js-sdk';
import { CodexResponse, CodexMessageTypeEnum, ModelReasoningEffort, ModelReasoningSummary, SandboxPermission, AskForApproval } from 'codex-js-sdk';

// Create a new SDK instance
const sdk = new CodexSDK({
    // Optional: Set custom working directory, could be relative to the current working directory (process.cwd())
    cwd: './my-project',
    // Optional: Configure logging level
    logLevel: LogLevel.DEBUG,
    // Optional: Specify custom path to codex binary (if installed locally)
    codexPath: './node_modules/.bin/codex',
    // Optional: Set custom environment variables (by default, the SDK will use the process.env)
    env: {
        OPENAI_API_KEY: 'sk-proj-...'
    }
});

2. Set up response and errors handlers

sdk.onResponse((response: CodexResponse) => {
    console.log('Received response: ', response);

    if (response.msg.type === CodexMessageTypeEnum.TASK_COMPLETE) {
        sdk.stop();
        process.exit(0);
    }
});

sdk.onError((response: CodexResponse) => {
    console.error('Error:', response);
    sdk.stop();
});

*3. Start codex process and send a message: *

// Start the Codex process (if not started yet)
sdk.start();

const requestId = sdk.sendUserMessage([
    { type: 'text', text: 'Hello, What is your task?' }
]);

You will start receiving messages in the onResponse handler:

Received response {
  id: 'a9c62ad3-2215-4d31-a91a-f40d2ae43711',
  msg: { type: 'task_started' }
}

Received response {
  id: 'a9c62ad3-2215-4d31-a91a-f40d2ae43711',
  msg: {
    type: 'agent_reasoning',
    text: '**Explaining my task**\n' +
      '\n' +
      `The user asked, "Hello, what is your task?" It seems they're looking for a brief description, so I'll clarify that I'm an AI assistant focused on coding tasks. I'll summarize my role: "I'm here to help by editing and testing code files, diagnosing issues, and more." I want to keep it straightforward without making any code changes. I'll make sure my response clearly reflects that!`
  }
}

Received response {
  id: 'a9c62ad3-2215-4d31-a91a-f40d2ae43711',
  msg: {
    type: 'agent_message',
    message: 'I’m your on-demand coding assistant: I can browse the repository in our session, edit or add files with precise patches, run builds and tests, diagnose failures, and help you implement or fix features. Just let me know what you need next!'
  }
}

Received response {
  id: 'a9c62ad3-2215-4d31-a91a-f40d2ae43711',
  msg: {
    type: 'task_complete',
    last_agent_message: 'I’m your on-demand coding assistant: I can browse the repository in our session, edit or add files with precise patches, run builds and tests, diagnose failures, and help you implement or fix features. Just let me know what you need next!'
  }
}

As can be seen from the response: we received a message that the task had started, followed by the agent_reasoning information explaining the task, then the answer to the question itself, and finally the completion of the task.

This is enough to wrap it up in a nice chat interface using some assistant-ui or copilotkit and get a prototype of a vibe coding generation service, and you don't even have to write your own agent-loop to work with files!

Advanced: event types, command approval, patches, image input

Now let's take a closer look at the types of events that Codex sends us and the actions we can send back to it:

User requests:
All requests from the user are sent in the following format:

interface Request<Operation> {
    id: string;
    op: Operation;
}

Below, I will only consider the Operation type.

Message from the user
It can be text, an image, or mixed:

type InputItem =
  | { type: 'text'; text: string }
  | { type: 'image'; image_url: string }
  | { type: 'local_image'; path: string };

interface UserInputOperation {
    type: 'user_input';
    items: InputItem[];
}

Via JS SDK:

const requestId = sdk.sendUserMessage([
    { type: 'text', text: 'What is in this pictures?' },
    { type: 'image', image_url: 'data:image/png;base64,iVBORw0KGgo........' },
    { type: 'local_image', path: './assets/flexbe_logo.png' }
]);

Confirmation of command execution:
By default, codex only executes safe commands; for example, it cannot delete a file without asking the user. In response to such a request, the user must reply with the following message:

enum ReviewDecision {
    APPROVED = 'approved',
    APPROVED_FOR_SESSION = 'approved_for_session',
    DENIED = 'denied',
    ABORT = 'abort'
}

interface ExecApprovalOperation {
    type: 'exec_approval';
    id: string;
    decision: ReviewDecision;
}

Using in SDK:

sdk.handleCommand(requestId, true); // approved
sdk.handleCommand(requestId, true, true); // approved for session
sdk.handleCommand(requestId, false); // denied

Confirming changes:
Similar to executing commands, codex will ask for confirmation when changing files:

interface PatchApprovalOperation {
    type: 'patch_approval';
    id: string;
    decision: ReviewDecision;
}

Using in SDK:

sdk.handlePatch(requestId, true); // approved
sdk.handlePatch(requestId, true, true); // approved for session
sdk.handlePatch(requestId, false); // denied

Canceling a request or command/change

interface InterruptOperation {
    type: 'interrupt';
}

Using in SDK:

sdk.abort(requestId);

The SDK also allows you to send raw messages of any type:

sdk.sendRaw({
    id: 'request-id',
    op: {
        type: 'interrupt',
    }
})

Codex response format

To subscribe to messages from Codex, execute the following in SDK:

const dispose = sdk.onResponse((response) => console.log(response));

In addition to several system messages, you can process 13 different messages from Codex:

Task start and completion events (from receiving a message from the user to the final response)

export interface TaskStartedMessage {
    type: CodexMessageTypeEnum.TASK_STARTED;
}

export interface TaskCompleteMessage {
    type: CodexMessageTypeEnum.TASK_COMPLETE;
    last_agent_message?: string;
}

Error during execution:

export interface ErrorMessage {
    type: CodexMessageTypeEnum.ERROR;
    message: string;
}

Model Reasoning:

interface AgentReasoningMessage {
    type: CodexMessageTypeEnum.AGENT_REASONING;
    text: string;
}

Message from agent:

interface AgentMessage {
    type: CodexMessageTypeEnum.AGENT_MESSAGE;
    message: string;
}

Request for confirmation of command execution

export interface ExecApprovalRequestMessage {
    type: CodexMessageTypeEnum.EXEC_APPROVAL_REQUEST;
    command: string[];
    cwd: string;
    reason?: string;
}

Command execution

export interface ExecCommandBeginMessage {
    type: CodexMessageTypeEnum.EXEC_COMMAND_BEGIN;
    call_id: string;
    command: string[];
    cwd: string;
}

Result of command execution

export interface ExecCommandEndMessage {
    type: CodexMessageTypeEnum.EXEC_COMMAND_END;
    call_id: string;
    command?: string[];
    stdout: string;
    stderr: string;
    exit_code: number;
}

Start of communication with the MCP server

export interface McpToolCallBeginMessage {
    type: CodexMessageTypeEnum.MCP_TOOL_CALL_BEGIN;
    call_id: string;
    server: string;
    tool: string;
    arguments?: any;
}

Result of accessing the MCP server

export interface McpToolCallEndMessage {
    type: CodexMessageTypeEnum.MCP_TOOL_CALL_END;
    call_id: string;
    result: {
        is_error?: boolean;
        [key: string]: any;
    };
}

Request to the user to confirm file changes

export interface ApplyPatchApprovalRequestMessage {
    type: CodexMessageTypeEnum.APPLY_PATCH_APPROVAL_REQUEST;
    changes: Record<string, FileChange>;
    reason?: string;
    grant_root?: string;
}

Start of application of changes

export interface PatchApplyBeginMessage {
    type: CodexMessageTypeEnum.PATCH_APPLY_BEGIN;
    call_id: string;
    auto_approved: boolean;
    changes: Record<string, FileChange>;
}

Result of applying changes (success or error)

export interface PatchApplyEndMessage {
    type: CodexMessageTypeEnum.PATCH_APPLY_END;
    call_id: string;
    stdout: string;
    stderr: string;
    success: boolean;
}

Advanced configuration

You can configure codex behavior using the config file located in the ~/.codex/config.toml directory, or by overriding some parameters when initializing the SDK. For example, to change the model to gemini:

const sdk = new CodexSDK({
    config: {
        model: 'gemini-2.5-pro-preview-06-05',
        model_provider: 'gemini',
    }
});

See official codex config.md for details and list of options

You can also override the session parameters of an already running instance. For example, I was able to get the Claude model to work and override the instructions only in this way:

await sdk.configureSession({
    instructions: 'You are a helpful coding assistant, your name is "Flexbe Bot". Provide concise and clear responses.',
    model: 'claude-3-7-sonnet-latest',
    provider: {
        name: 'Anthropic',
        base_url: 'https://api.anthropic.com/v1',
        env_key: 'ANTHROPIC_API_KEY',
        env_key_instructions: 'Create an API key (https://console.anthropic.com) and export it as an environment variable.',
        wire_api: WireApi.CHAT
    },
    model_reasoning_effort: ModelReasoningEffort.NONE,
    model_reasoning_summary: ModelReasoningSummary.NONE,
});

Conclusion

codex-js-sdk allows you to use codex in your Node.js application — you can embed Codex into your dev tools, create a custom code assistant, run autotests before pushing, check patches before merging, or even build a Copilot interface, it's all up to you!

I welcome comments and feedback
👉 GitHub: https://github.com/openai/codex
👉 SDK: https://npmjs.com/package/codex-js-sdk

Getting started with Storybook in SolidJS (with Tailwind CSS)

Maksim Kachurin — Sun, 15 Jun 2025 02:42:06 +0000

SolidJS is a fast, compact, and much-loved framework, especially among those who value performance and minimal abstractions.
It compiles to the lightest possible JavaScript, works directly with the DOM tree, and still has a JSX syntax like React, which makes it especially easy to compose components and understand for those who are used to working with React.
Essentially, you can write familiar code, but without all the burden that the React ecosystem carries.

However, when you start building a full-fledged application from dozens of components, the question quickly arises — how convenient is it to test and display these components in isolation from everything else? Waiting for the whole app to load, walking through the routers, disabling logic? Not exactly a fun dev loop.

And that's where Storybook comes in handy.

What is Storybook?

Storybook is a tool for isolated development of UI components. It allows you to run components outside the application, view them in different states, and document behavior and interaction with props. It's essentially a separate environment where each component — or even a separate part of the UI — is presented as an interactive “story,” with code, visuals, and settings.
You plug in your components, describe how they should be displayed, and get a convenient environment for debugging, demonstrating, and collaborating on the UI.

You can check a real-time example of Storybook with SolidJS in this Stackblitz demo

SolidJS support in Storybook

This is the part where the complications start. Unfortunately, the Storybook team doesn't have enough resources to support all existing — or even just popular — frameworks, so they are mostly focused on the React version.
The storybook-solidjs community adapter is not really supported by the community, has broken dependencies, a number of bugs, no testing support, no automatic generation of documentation from TypeScript typings, and it doesn't work with Storybook 9. You'll be lucky if you can get it to work at all.
Half a year ago, I got it to work by some miracle. But a month ago, something updated, and it stopped running again.

So I decided to take things into my own hands and developed my own adapter for Storybook in SolidJS, as well as a CLI for easy customization.

The current package is published as @kachurun/storybook-solid-vite, but we’re working on moving it under storybook-solidjs, which is the one referenced in the official Storybook docs.
The code is published in the solidjs-community/storybook GitHub repository.

Huge thanks to the folks behind storybook-solidjs. This project wouldn’t exist without the foundation they laid.

Features

Hot Reload – Instant updates as you edit components, powered by Vite
Integrated Testing – Built-in support for component and story testing with Vitest and Playwright
ArgTypes from TypeScript – Prop tables and controls generated directly from your TypeScript types
Addon Ecosystem – Works with popular Storybook addons (Docs, Controls, Actions, Links, etc.)
MDX & Docs – Write rich documentation alongside your stories using MDX
Accessibility (a11y) – Built-in accessibility checks for your components

Setup

For ease of deployment from scratch, I have created a package, create-solid-storybook, that will automatically create all the necessary files and some sample stories.

Execute:

npx create-solid-storybook

If you prefer a different package management system:

Yarn

yarn create-solid-storybook

PNPM

pnpm create solid-storybook

Bun

bunx create-solid-storybook

Important: Storybook 9 requires Node.js version 20 or higher to run.

The utility will automatically deploy the necessary files and sample stories to the storybook folder (you can specify the folder name as the second argument when running the command), install dependencies, and start Storybook.

The browser with the running Storybook will open automatically at http://localhost:6006/.

Project structure:

storybook/
├── .storybook/
│   ├── main.ts # Main configuration file
│   └── preview.ts # Global parameters and decorators
│
├── stories/ # Sample components and stories for them
│
├── tsconfig.json # TypeScript configuration
├── vitest.config.ts # Vitest configuration
└── package.json # Project dependencies and scripts

The main.ts file is where Storybook itself, its plugins, Vite settings, etc., are configured.

The main line for working with SolidJS is the framework setting, which tells Storybook how to work with our component files:

framework: '@kachurun/storybook-solid-vite',

You can change any configuration settings other than this line.

The preview.ts file is connected inside the iframe in which your story is rendered. If you want, for example, to connect some global CSS, you must import it in this file. The file is also responsible for default configuration for all stories.

The stories folder contains sample components and stories for them. Most likely, you will just delete it, but it is needed as an example.
I prefer to keep all stories in this folder and the components themselves outside the Storybook directory, in the source code of the project itself.
Many people prefer to store stories next to their components. In that case, you will need to open the main.ts file and specify the path to your stories files, for example:

stories: [
  '../../src/**/*.mdx',
  '../../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
],

Stories format

The stories format for SolidJS is not different from the React format.

You create a file [componentName].stories.tsx with content like this:

import { fn } from 'storybook/test';
import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    backgroundColor: { control: 'color' },
  },
  args: { onClick: fn() },
};

export const Primary = {
  args: {
    primary: true,
    label: 'Button',
  },
};

Note: each story must export at least one named export.

You can use CSF format:

export const ButtonCSF = (args: ButtonProps) => {
  return <Button size="small" label="Button" {...args} />;
};

Or use decorators to frame the component:

export const WithDecorator = {
  args: {
    size: 'small',
    label: 'Button',
    primary: true,
  },
  decorators: [
    (Story: Component<ButtonProps>, context: { args: ButtonProps }) => {
      return (
        <div class="border border-dashed border-red-500 p-2">
          <Story {...context.args} />
        </div>
      );
    },
  ],
};

Everything is exactly the same as with React components, so you can use the standard Storybook documentation.

Customizing Tailwind CSS 4

Since our Storybook configuration uses Vite for the build, setting up Tailwind will be very easy.

In the running terminal, press Cmd + C to end the Storybook process, navigate to the storybook folder, and install Tailwind:

cd storybook
npm install tailwindcss @tailwindcss/vite

You can skip this step if your project already uses Tailwind.

Then open the .storybook/main.ts file and add the Tailwind plugin in the viteFinal config:

export default <StorybookConfig>{
  ...
  async viteFinal(config) {
    return mergeConfig(config, {
      define: {
        'process.env': {},
      },
      plugins: [
        await import('@tailwindcss/vite').then(module => module.default())
      ],
    });
  },
  ...
}

We use dynamic importing to solve a strange bug in Tailwind CSS that is marked as solved but still occurs.

Next, create a CSS file (the name can be anything) with the contents:

@import "tailwindcss";

If your working project already has a file with this import, skip this step.
I will create this file at the path .storybook/preview.css.

Next, import this file in .storybook/preview.ts:

import './preview.css';
...

Done! You can now run Storybook:

npm run storybook

To test it, let's edit some component — for example, stories/Button.tsx — and add Tailwind classes to it:

export const Button = (_props: ButtonProps) => {
  const [props, attrs] = splitProps(
    mergeProps({ size: 'medium' }, _props),
    ['label']
  );

  return (
    <button
      type="button"
      class="px-4 py-3 text-sm bg-blue-500 text-white rounded-full"
      {...attrs}
    >
      {props.label}
    </button>
  );
};

Next, open the story and make sure the styles are applied.

That's enough to start developing, debugging, and testing your SolidJS components!

Feel free to comment if you have any questions, and feel free to open an issue if you have any problems with your configuration!