chatgpt-webui-mcp
Provides tools for interacting with ChatGPT via its web UI, enabling AI agents to send prompts, manage conversations, generate images, and perform long-running tasks like deep research using various GPT models.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chatgpt-webui-mcpdeep research on quantum computing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
quick start
install from npm:
npm i -g chatgpt-webui-mcpmanual run:
CHATGPT_SESSION_TOKEN="your_token_here" chatgpt-webui-mcpfrom source:
npm install
npm run build
CHATGPT_SESSION_TOKEN="your_token_here" node dist/index.jsimportant: this uses chatgpt's internal webui api with a session cookie. for personal/local tinkering only - not affiliated with openai.
overview
chatgpt-webui-mcp is a standalone MCP server that drives chatgpt.com via camofox (UI automation).
it is built for long-running tasks (gpt-5.2 pro runs that take 1h+), deep research, and image generation mode.
getting your session token
open https://chatgpt.com and log in
open devtools
application -> cookies ->
https://chatgpt.comcopy the value of
__Secure-next-auth.session-token
configuration
because this server uses stdio or sse, you configure it as a local command (or remote url) and pass the token via env.
mcp client config (claude desktop, opencode, etc)
{
"mcpServers": {
"chatgpt-webui": {
"command": "node",
"args": ["/absolute/path/to/chatgpt-webui-mcp/dist/index.js"],
"timeout": 7200000,
"env": {
"CHATGPT_SESSION_TOKEN_FILE": "/path/to/session-token.txt",
"CHATGPT_BROWSER_BASE_URL": "http://127.0.0.1:9377",
"CHATGPT_WAIT_TIMEOUT_MS": "7200000"
}
}
}
}legacy CHATGPT_CAMOFOX_* env vars are still supported for compatibility.
CHATGPT_TRANSPORT=httpcloak is intentionally unsupported (use camofox).
when model/thinking are omitted, requests default to gpt-5-2 (auto), not pro.
opencode workflow (the natural language style)
if you want to type commands like:
with chatgpt webui on gpt 5.2 pro extended thinking: <prompt>do deepresearch with chatgpt webui on <topic>
use this tool:
tool | what it does |
| parses your sentence into the right call and runs it |
example:
{
"name": "chatgpt_webui_command",
"arguments": {
"command": "with chatgpt webui on gpt 5.2 pro extended thinking: write a 1-page memo about X",
"mode": "auto"
}
}long runs (recommended)
use the unified tools:
tool | description |
| main tool. |
| check/wait for background runs ( |
why: deep research and gpt-5.2 pro can take a long time and may exceed a single client timeout. mode=auto returns a run_id for long jobs.
image generation
set create_image=true to switch chatgpt into image generation mode before sending the prompt.
notes:
image_urlsis best-effort (derived from page links + visited urls) and may be empty depending on how chatgpt renders images in the webui.fallback screenshot output is returned in
image_data_url(notimage_urls) when enabled and size-capped.enable fallback with
CHATGPT_IMAGE_SCREENSHOT_FALLBACK=1.cap fallback size with
CHATGPT_IMAGE_SCREENSHOT_MAX_BYTES(default2097152, 2 MiB).for reliable retrieval, you can also use the conversation_id and open the chatgpt UI.
self-test
# env
CHATGPT_SESSION_TOKEN="your_token_here" npm run self-test
# cli flag
npm run self-test -- --token "your_token_here"
# file
echo "your_token_here" > ~/.config/chatgpt-webui-mcp/session-token.txt
npm run self-test -- --token-file ~/.config/chatgpt-webui-mcp/session-token.txtremote deployment over tailscale (optional)
if you want background runs to survive for a long time, run this server as an always-on SSE service.
copy templates from this repo:
deploy/systemd/chatgpt-webui-mcp.env.exampledeploy/systemd/chatgpt-webui-mcp-sse.shdeploy/systemd/chatgpt-webui-mcp.service
install and enable service (user service):
mkdir -p ~/.config ~/.config/systemd/user ~/.local/bin ~/.local/share/chatgpt-webui-mcp
cp deploy/systemd/chatgpt-webui-mcp.env.example ~/.config/chatgpt-webui-mcp.env
cp deploy/systemd/chatgpt-webui-mcp-sse.sh ~/.local/bin/chatgpt-webui-mcp-sse.sh
cp deploy/systemd/chatgpt-webui-mcp.service ~/.config/systemd/user/chatgpt-webui-mcp.service
chmod 600 ~/.config/chatgpt-webui-mcp.env
chmod 755 ~/.local/bin/chatgpt-webui-mcp-sse.sh
systemctl --user daemon-reload
systemctl --user enable --now chatgpt-webui-mcp.servicepoint opencode (cloud host) to the endpoint:
{
"mcp": {
"chatgpt-webui": {
"type": "remote",
"url": "http://<tailscale-ip>:8791/sse",
"enabled": true,
"timeout": 7200000,
"oauth": false
}
}
}tools
tool | description |
| validate token and return session payload |
| list available models |
| natural-language command wrapper |
| unified prompt tool (wait/background) |
| check/wait for background runs |
| direct wait-style prompt tool (legacy/simple) |
project structure
chatgpt-webui-mcp/
├── deploy/
│ └── systemd/
│ ├── chatgpt-webui-mcp.env.example
│ ├── chatgpt-webui-mcp-sse.sh
│ └── chatgpt-webui-mcp.service
├── src/
│ ├── index.ts # MCP server
│ └── chatgpt-webui-client.ts # WebUI automation client
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── LICENSE
├── INSTALL.md
└── README.mdlicense
mit
author
Available Tools
9 toolschatgpt_webui_askC
Send a prompt to ChatGPT WebUI using session token auth and return assistant text.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model slug override. Examples: gpt-5-2, gpt-5-2-pro, gpt-5-1-instant, research. Ignored when deep_research=true. | |
| prompt | Yes | Prompt to send. | |
| workspace | No | Preferred workspace label if ChatGPT shows workspace selection (e.g. PRO, Personal). | |
| model_mode | No | Quick model mode selector that maps to GPT-5.2 variants. | |
| create_image | No | Enable image-generation mode in ChatGPT UI. | |
| deep_research | No | Enable Deep Research flow. When true, model selection switches to research mode. | |
| conversation_id | No | Optional conversation id to continue an existing chat. | |
| wait_timeout_ms | No | Max wait for response completion in milliseconds (supports long GPT-5.2 Pro runs). | |
| reasoning_effort | No | UI reasoning control. Mainly relevant for thinking-capable models. | |
| parent_message_id | No | Optional parent message id for continued conversation state. | |
| deep_research_site_mode | No | Optional Deep Research sites mode override. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It discloses the auth mechanism (session token) and the synchronous return of assistant text, but says nothing about side effects like conversation creation, quota consumption, long deep-research waits, timeout behavior, or error cases. For a tool with 11 parameters and no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the core action and output. It is concise and readable, though for a tool of this complexity it is arguably too terse to earn a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description alone must explain return values, behavior, and usage context beyond the schema. It only states the basic action and return type, missing details about synchronous vs. async behavior, session requirements, wait_timeout implications, and what the assistant text actually looks like. This is inadequate for an 11-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter. The description adds minimal parameter meaning—it only echoes the 'prompt' concept and the auth context. Baseline 3 is appropriate because the schema carries the parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action—sending a prompt to ChatGPT WebUI—and its output (assistant text). It also mentions the authentication mechanism, which helps anchor the tool's role. However, it doesn't explicitly differentiate itself from sibling tools like chatgpt_webui_ask_async_start or chatgpt_webui_prompt, relying mostly on the word 'return' to imply synchronous behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus the async variants (chatgpt_webui_ask_async_start/status/result) or when a session must be established first. The description implies a one-shot synchronous ask, but does not state prerequisites, suitability for long-running operations, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
chatgpt_webui_ask_async_resultB
Get result for a background ask job. Optionally wait for completion by providing wait_timeout_ms.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id returned by chatgpt_webui_ask_async_start. | |
| wait_timeout_ms | No | Optional max wait for completion before returning current state. | |
| poll_interval_ms | No | Polling interval while waiting. Default: 2000ms. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It mentions that waiting is optional but does not describe what happens when the job is incomplete, whether the call returns current state, or how polling behaves beyond the schema definitions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with no wasted words. It states the core purpose in one sentence and adds the key optional behavior in a short second clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool, the description covers the basic purpose and optional waiting behavior. However, with no output schema and no annotations, it omits useful context about what the result looks like and how incomplete jobs behave, so it is only minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds a small amount of meaning by saying wait_timeout_ms waits for completion, but it does not go beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: 'Get result for a background ask job.' It is specific enough for an agent to identify the tool's responsibility, though it does not explicitly contrast it with ask_async_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool instead of ask_async_status or how it relates to ask_async_start. The only usage hint is the optional wait_timeout_ms, which is more about parameter behavior than tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
chatgpt_webui_ask_async_startA
Start a background ChatGPT ask job and return immediately with a job id. Use this for long-running tasks like Deep Research and Pro runs.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model slug override. Examples: gpt-5-2, gpt-5-2-pro, gpt-5-1-instant, research. Ignored when deep_research=true. | |
| prompt | Yes | Prompt to send. | |
| workspace | No | Preferred workspace label if ChatGPT shows workspace selection (e.g. PRO, Personal). | |
| model_mode | No | Quick model mode selector that maps to GPT-5.2 variants. | |
| create_image | No | Enable image-generation mode in ChatGPT UI. | |
| deep_research | No | Enable Deep Research flow. When true, model selection switches to research mode. | |
| conversation_id | No | Optional conversation id to continue an existing chat. | |
| wait_timeout_ms | No | Max wait for response completion in milliseconds (supports long GPT-5.2 Pro runs). | |
| reasoning_effort | No | UI reasoning control. Mainly relevant for thinking-capable models. | |
| parent_message_id | No | Optional parent message id for continued conversation state. | |
| deep_research_site_mode | No | Optional Deep Research sites mode override. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It effectively discloses the key behavior: the tool starts a background job, does not wait for completion, and returns immediately with a job id. It could also mention that results are retrieved via the async_status/result siblings, but this is strongly implied by the sibling tool names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core behavior is front-loaded, and the usage guidance follows immediately. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters and no output schema, the description tells the agent the essential invocation contract: it starts a background job and returns a job id. The full async workflow is not spelled out, but sibling tools and the return-immediately statement make it sufficiently complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description adds no direct parameter meaning beyond referencing long-running and Deep Research/Pro use cases, which loosely maps to deep_research and model_mode but does not materially improve on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: start a background ChatGPT ask job and immediately return a job id. It also distinguishes this from synchronous ask and from the async status/result siblings by emphasizing background execution and long-running tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this for long-running tasks like Deep Research and Pro runs, which gives clear guidance on when this tool is appropriate. It does not explicitly name a synchronous alternative or say when not to use it, but the context and sibling names make that inference straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
chatgpt_webui_ask_async_statusC
Get status for a background ask job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id returned by chatgpt_webui_ask_async_start. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Get status' implies a read-only operation, but nothing is disclosed about possible statuses, whether the call blocks, what happens if the job_id is invalid or expired, or whether the result is consumed by calling this endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for a simple status-check tool, though it could be slightly expanded with usage context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. The agent knows it gets a status, but not what statuses to expect, when to call this versus ask_async_result, or how to interpret the response. The schema documents only the input, leaving key runtime behavior unknown.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for job_id is clear and references the start tool, providing complete parameter meaning. The tool description adds little beyond the word 'background', but since schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Get status' and a specific resource 'background ask job', which clearly conveys the tool's function. It is distinguishable from siblings like ask_async_start and ask_async_result by the word 'status', though it does not explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus the sibling tools. It implies the agent should call this after starting a job, but it does not say that, nor does it mention when to prefer ask_async_result over status or how polling should behave.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
chatgpt_webui_commandB
Natural-language command wrapper. Converts phrases like 'with chatgpt webui on gpt 5.2 pro extended thinking: ...' into a chatgpt_webui_prompt call.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Optional override. If omitted, inferred from command and defaults. | |
| command | Yes | Natural language command string. | |
| wait_for_ms | No | Optional wait window for background mode before returning running state. | |
| poll_interval_ms | No | Polling interval when wait_for_ms is set. Default 2000ms. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It does reveal the defining behavior — it is a wrapper that converts NL into a prompt call — but leaves the execution model ambiguous: does it merely return the constructed call or does it execute it and wait? Given the wait/poll/mode parameters imply execution and waiting behavior, this ambiguity is a material transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words; the wrapper concept is front-loaded before the illustrative example. The example phrase is somewhat long, but it earns its place by showing the expected input shape. Slightly verbose example keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations and no output schema, the description is thin. It does not say whether the tool executes the prompt or returns the converted call, does not explain how mode/wait/poll relate to the wrapper behavior, and does not guide the agent on choosing this over chatgpt_webui_prompt. An agent is left with material uncertainty about invocation and return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so a baseline of 3 applies even with no parameter detail in the description. The example phrase adds mild value by illustrating what a natural-language 'command' looks like (model and feature tokens embedded in prose), but the schema already documents all four parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('converts') acting on a natural-language command resource, with a concrete example of the input format. It also names its transformation target (chatgpt_webui_prompt call), which begins to distinguish it from that sibling. It does not fully carve out its role against the other siblings (ask, run), so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: if a user expresses an intent as a natural-language phrase, this tool wraps it. However, there is no explicit when/when-not guidance, no named alternatives beyond the target prompt tool, and no statement about when one would prefer chatgpt_webui_prompt directly. An agent must infer the selection logic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
chatgpt_webui_modelsA
List available ChatGPT WebUI models for the current account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. 'List' suggests a read-only operation and 'current account' adds useful scoping, but the description does not disclose return format, potential pagination, or account/session prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word contributes meaning: the verb, the resource, and the scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool, the description is nearly complete: it states the resource and scope clearly. With no output schema, a brief mention of what the returned model list contains would make it fully complete, but the current text is adequate for the common case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description cannot be expected to explain parameter meanings. The 'current account' phrasing adds useful context about implicit scoping, matching the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), a clear resource ('ChatGPT WebUI models'), and a scope ('current account'). It clearly differentiates this from the action-oriented sibling tools such as ask, run, and command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—whenever the current account's available models are needed—but it does not explicitly reference sibling tools or state any exclusions. Usage guidance is present by inference rather than direct instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
chatgpt_webui_promptB
Unified prompt entrypoint. mode=auto uses background runs for long tasks (Deep Research, Pro/Thinking, image generation) and direct wait for short tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Execution mode. auto chooses best mode. wait blocks for result. background returns run_id. | |
| model | No | Model slug override. Examples: gpt-5-2, gpt-5-2-pro, gpt-5-1-instant, research. Ignored when deep_research=true. | |
| prompt | Yes | Prompt to send. | |
| workspace | No | Preferred workspace label if ChatGPT shows workspace selection (e.g. PRO, Personal). | |
| model_mode | No | Quick model mode selector that maps to GPT-5.2 variants. | |
| wait_for_ms | No | Optional extra wait window for background mode before returning running state. | |
| create_image | No | Enable image-generation mode in ChatGPT UI. | |
| deep_research | No | Enable Deep Research flow. When true, model selection switches to research mode. | |
| conversation_id | No | Optional conversation id to continue an existing chat. | |
| wait_timeout_ms | No | Max wait for response completion in milliseconds (supports long GPT-5.2 Pro runs). | |
| poll_interval_ms | No | Polling interval when wait_for_ms is set. Default 2000ms. | |
| reasoning_effort | No | UI reasoning control. Mainly relevant for thinking-capable models. | |
| parent_message_id | No | Optional parent message id for continued conversation state. | |
| deep_research_site_mode | No | Optional Deep Research sites mode override. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does reveal one non-obvious trait — auto mode routes long tasks to background runs and short tasks to direct waits — but it never discloses that sending a prompt mutates conversation state, what a successful call returns, or how wait vs background outcomes differ.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 24-word sentence with no filler, and the most decision-relevant nugget (auto mode's dispatch strategy) is included. The structure is efficient, though the brevity borders on under-specification for a tool this complex.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool — 14 parameters, 4 enums, no output schema, no annotations, and 8 siblings with overlapping roles — yet the description is only one sentence. It doesn't explain return values, conversation state effects, or how it differs from ask/run/command, so an agent cannot reliably decide to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline of 3 applies: the schema already documents all 14 parameters, including enum meanings for mode, model_mode, reasoning_effort, and deep_research_site_mode. The description adds nothing about parameters, and the schema's own descriptions are adequate but not exceptional (e.g., 'Enable Deep Research flow').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description calls the tool a 'Unified prompt entrypoint' but supplies no verb and never explicitly states that it submits a prompt to ChatGPT. With siblings like ask, run, and command available, an agent cannot tell which tool handles a plain prompt submission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The mode=auto explanation is genuinely useful, telling agents that long tasks (Deep Research, Pro/Thinking, image generation) are dispatched to background runs while short tasks wait directly. However, no guidance is given for when to choose this tool over chatgpt_webui_ask, run, or command, and no exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
chatgpt_webui_runB
Unified run checker. Use run_id from chatgpt_webui_prompt background mode (or job_id from legacy async tools).
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | Legacy alias for run_id. | |
| run_id | No | Run id from chatgpt_webui_prompt. | |
| wait_timeout_ms | No | Optional max wait for completion before returning running state. | |
| poll_interval_ms | No | Polling interval while waiting. Default: 2000ms. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of disclosing behavior. It only calls the tool a 'run checker' and states what inputs to provide; it does not describe what the tool returns, whether it consumes/deletes the run result, how errors are handled, or whether polling has side effects. The schema's parameter descriptions cover wait/poll mechanics, but the overall behavior remains opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core purpose, and the second sentence adds the essential input-source guidance. There is no redundant fluff. The only minor issue is that 'Unified run checker' is a label rather than a full sentence, which slightly reduces clarity but does not waste space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has no output schema and no annotations, so the description needs to provide enough context for an agent to understand the tool's behavior and return values. It fails to describe what response the agent should expect, what happens if the run is not found, what the default behavior is without wait_timeout_ms, or whether the result can be retrieved after the tool returns. The input-side guidance is useful, but the output and behavioral side is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all four parameters with descriptions, so the baseline is 3. The description adds extra meaning beyond the schema by specifying that run_id must come from chatgpt_webui_prompt background mode and that job_id is from legacy async tools. This clarifies the relationship and origin of the identifiers, going slightly beyond the schema's wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool as a 'Unified run checker' and clarifies that it operates on run IDs from chatgpt_webui_prompt background mode or legacy async job IDs. This gives a specific resource and distinguishes it from sibling tools like ask_async_status. However, 'run checker' is not as explicit as a direct verb like 'poll' or 'wait for', and the exact action is somewhat implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells users to use run_id from chatgpt_webui_prompt background mode or job_id from legacy async tools, which provides clear guidance on when to use this tool. It does not explicitly enumerate when not to use sibling tools, but the phrase 'unified' plus the reference to legacy tools implies it replaces or consolidates them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
chatgpt_webui_sessionA
Validate ChatGPT session token and return session details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read-only validation action, but does not disclose what happens with an invalid token, whether any side effects occur, or what 'session details' includes. This leaves behavioral ambiguity for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that is front-loaded with the primary action and outcome. Every word contributes value, with no filler or redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool, the description is reasonably complete: it states the purpose and the return concept. However, it lacks usage timing, error behavior, and detail about what session details are returned, especially given there is no output schema to fill that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there is no parameter burden to document. The description's mention of a session token is contextually useful, though it is not a formal parameter. With 0 parameters, the baseline is appropriately high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Validate'), a clear resource ('ChatGPT session token'), and an expected outcome ('return session details'). This clearly distinguishes it from sibling tools like chatgpt_webui_ask or chatgpt_webui_models, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus the siblings. The description implies it could be used to check session validity before other operations, but it does not state this explicitly or provide any when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
9 tool updates
v0.1.6- First observed
chatgpt_webui_ask - First observed
chatgpt_webui_ask_async_result - First observed
chatgpt_webui_ask_async_start - First observed
chatgpt_webui_ask_async_status - First observed
chatgpt_webui_command - First observed
chatgpt_webui_models - First observed
chatgpt_webui_prompt - First observed
chatgpt_webui_run - First observed
chatgpt_webui_session
TDQS
Scored across 9 tools
There is significant functional overlap: chatgpt_webui_ask, chatgpt_webui_prompt, chatgpt_webui_command, and chatgpt_webui_ask_async_start all initiate ChatGPT prompts. The distinction between direct ask, unified prompt, and natural-language wrapper is not immediately clear, and the run checker overlaps with async status/result tools.
Tools consistently share the chatgpt_webui_ prefix and use snake_case, but the action style is mixed: ask/start are verbs, while session/models/command/prompt/run are nouns. The async subfamily is internally consistent, but the overall naming pattern is not uniform.
Nine tools is within a reasonable range for a ChatGPT WebUI integration. However, several tools appear redundant due to the coexistence of legacy async functions, a unified prompt entrypoint, and a command wrapper, making the set slightly larger than needed.
The core workflow of sending prompts and retrieving results is covered, including background execution for long-running tasks. Notable gaps include no explicit cancellation/abort for background jobs and no conversation-history or context management, which limits full lifecycle coverage.
Maintenance
Related MCP Connectors
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceMCP server that enables AI tools to control local browser sessions for ChatGPT, Claude, and other AI services, supporting querying, navigation, file uploads, and artifact management.28 npm558Mozilla Public 2.0- AlicenseNot gradedqualityCmaintenanceLocal MCP server bridging ChatGPT Web to local tools for file, shell, git, test, and process management with secure policy controls.MIT
- AlicenseAqualityBmaintenanceMCP server that drives chat.sakana.ai via headless Chrome with persistent sessions. Enables AI assistants to interact with Sakana AI chat through tools like session management, with ToS gate and browser automation.533 npmMIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server for automated interaction with Gemini's web interface using Playwright and LangGraph, enabling task execution, deep research, file uploads, chat management, and dynamic selector verification via MCP tools.1MIT