Provides tools to interact with OpenAI's GPT-5 (with automatic fallback to GPT-4) for advanced reasoning, cost management, multi-turn conversations, and file analysis (PDFs, images, documents).
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., "@GPT-5 MCP Server help me design a REST API for user authentication"
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.
A Model Context Protocol (MCP) server that brings OpenAI's GPT-5 capabilities to Claude Code. Features advanced reasoning, cost management, and conversation handling with automatic GPT-4 fallback.
Collaborative AI: Combine Claude's capabilities with GPT-5's advanced reasoning
Cost Control: Built-in spending limits, preflight estimates, per-conversation budgets
Efficient Context: Context truncation + optional summarization to reduce tokens
Automatic Fallback: Seamlessly falls back to GPT-4 family with retries/backoff
File Support: Process PDFs, images, and documents via Claude Code’s @ syntax
Observability: JSON outputs, usage CSV, optional webhook alerts
Related MCP server: gpt5mcp
OpenAI API Key with GPT-5 access (or GPT-4 for fallback)
Node.js 18+ and pnpm (for local installation)
Docker (optional, for containerized deployment)
Claude Code CLI or Claude Desktop
git clone https://github.com/andreahaku/gpt5_mcp
cd gpt5-mcp
cp .env.example .env
# Edit .env and add: OPENAI_API_KEY=sk-your-key-herepnpm install
pnpm run buildOption A: Docker (Recommended)
# Build Docker image
pnpm run docker:build
# Add to Claude Code
claude mcp add gpt5 -s user -- docker run --rm -i --env-file $(pwd)/.env gpt5-mcp:latestOption B: Local Installation
# Add to Claude Code (replace with your actual path)
claude mcp add gpt5 -s user -- node /path/to/gpt5-mcp/dist/index.jsRestart Claude Desktop to load the new MCP server.
Edit your Claude Desktop config file directly:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"gpt5": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", "/absolute/path/to/.env",
"gpt5-mcp:latest"
]
}
}
}Create a .env file with your OpenAI API key and optional tuning:
# Required
OPENAI_API_KEY=sk-your-api-key-here
# Cost limits (defaults shown)
DAILY_COST_LIMIT=10.00
TASK_COST_LIMIT=2.00
# Reasoning defaults
DEFAULT_TEMPERATURE=0.7
DEFAULT_REASONING_EFFORT=high
# Conversation controls
MAX_CONVERSATION_CONTEXT=10 # messages kept per call
MAX_INSTRUCTION_TOKENS=1500 # truncate very long instructions
CONVERSATION_HARD_CAP_MULTIPLIER=10
# Resource handling
RESOURCE_MAX_TOKENS=1500 # per-resource token budget
RESOURCE_MAX_COUNT=5 # max resources included per call
# OpenAI model and client behavior
OPENAI_RESPONSES_MODEL=gpt-5
OPENAI_FALLBACK_MODELS=gpt-4o,gpt-4o-mini,gpt-4-turbo-preview,gpt-4-turbo,gpt-4,gpt-3.5-turbo
OPENAI_RETRY_COUNT=3
OPENAI_RETRY_BASE_DELAY_MS=300
OPENAI_TIMEOUT_MS=30000
# Alerts
ALERT_WEBHOOK_URL= # optional URL to POST alerts (JSON)consult_gpt5Get GPT-5 assistance with advanced reasoning and file support.
Key parameters:
prompt (required): Your question or task
reasoning_effort: minimal, low, medium, or high (default: high)
task_budget: USD limit for this specific task
max_tokens: hard cap for this response (down-capped by budget)
stream: enable streaming (server aggregates; client receives final text)
start_conversationBegin a multi-turn conversation with GPT-5.
Parameters:
topic (required): What the conversation is about
instructions: Optional system-level guidance
budget_limit: Optional per-conversation budget (USD)
continue_conversationContinue an existing conversation thread.
Parameters:
conversation_id (required): ID from start_conversation
message (required): Your next message
max_tokens: optional cap for this single turn (down-capped by budget)
budget_limit: set/override per-conversation budget
confirm_spending: proceed when near/over budget
stream: enable streaming (server aggregates; client receives final text)
set_conversation_optionsUpdate per-conversation options without sending a message.
Parameters:
conversation_id (required)
budget_limit: set/override per-conversation budget
context_limit: override messages kept in context per call
get_cost_reportView usage statistics and costs.
Parameters:
period: current_task, today, week, or month
set_cost_limitsConfigure spending limits.
Parameters:
daily_limit: Maximum daily spending in USD
task_limit: Maximum per-task spending in USD
"Use GPT-5 to help me design a REST API for user authentication"
"Ask GPT-5 to review this code for security issues""@config.json Ask GPT-5 to review this for security issues"
"@screenshot.png What UI improvements would GPT-5 suggest?""Start a GPT-5 conversation about optimizing database queries"
"Continue the conversation: What about indexing strategies?"# Development
pnpm run dev # Start with hot reload
pnpm run build # Compile TypeScript
pnpm test # Run tests
# Docker
pnpm run docker:build # Build Docker image
pnpm run docker:run # Run in Docker
# Setup
pnpm run install:setup # Interactive installer
pnpm start # Choose how to run (menu)Server not appearing in Claude Desktop:
Verify config file location (see Alternative: Manual Configuration above)
Use absolute paths, not relative paths
Restart Claude Desktop completely (Quit → Restart)
API Key Issues:
Ensure .env file exists with OPENAI_API_KEY=sk-your-key
Key must start with sk-
Server will fallback to GPT-4 if GPT-5 is unavailable
Docker Issues:
# Test Docker image
docker run --rm -i --env-file .env gpt5-mcp:latest
# Rebuild if needed
docker build --no-cache -t gpt5-mcp .Cost Limits:
Configure limits in .env file
Use get_cost_report tool to monitor usage
Daily default: $10, Task default: $2
For more control, set per-conversation budgets via start_conversation or set_conversation_options.
The server preflights costs and may ask for confirm_spending=true to proceed when budgets are tight.
gpt5-mcp/
├── src/ # TypeScript source
├── dist/ # Compiled JavaScript
├── data/ # Persistent usage data
├── tests/ # Jest unit tests
└── docs/ # Additional documentationMIT License - see LICENSE file for details
For issues or questions, please open an issue on GitHub.
task_limit: Maximum per-task spending in USD
get_conversation_metadataReturn conversation object in JSON (metadata + messages).
summarize_conversationCompress older messages into a concise summary to reduce future token usage.
Parameters:
conversation_id (required)
keep_last_n (default 5): number of recent messages to keep verbatim
max_tokens (default 2000): budget for generating the summary
Note: This server uses OpenAI's GPT-5 Responses API when available and automatically falls back to GPT-4 with adjusted parameters if needed.
Consult GPT-5 for planning or coding assistance
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | The prompt to send to GPT-5 | |
| stream | No | Enable streaming mode (server aggregates, client still returns final text) | |
| context | No | Additional context for the prompt | |
| max_tokens | No | Maximum tokens in response | |
| task_budget | No | Budget limit for this specific task in USD | |
| temperature | No | Sampling temperature | |
| confirm_spending | No | User confirmation to proceed with spending that exceeds daily limit | |
| reasoning_effort | No | Reasoning effort level | high |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only mentions planning/coding assistance. It does not disclose potential spending, budget checks, streaming behavior, or cost confirmation implications, despite parameters like task_budget and confirm_spending suggesting these are important.
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 one concise sentence with no repetition or filler. It is front-loaded and efficient, though slightly terse for the underlying complexity; still, it earns a 4 for its compactness.
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 complexity of 8 parameters, no annotations, and no output schema, the description is too sparse to provide complete context. It lacks details about spending, streaming, conversation alternatives, and expected return behavior, making it only minimally adequate.
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% since all 8 parameters have descriptions in the schema. The description itself adds no parameter-level meaning, so 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 uses a specific verb ('Consult') and resource ('GPT-5') with a clear scope ('planning or coding assistance'). However, it does not explicitly distinguish this from sibling tools like start_conversation or continue_conversation, which could also involve consulting GPT-5, so it falls 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?
The description provides no guidance on when to use this tool versus alternatives such as start_conversation or continue_conversation. 'Planning or coding assistance' implies a use case, but there are no exclusionary or alternative-recommendation details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Continue an existing conversation with GPT-5
| Name | Required | Description | Default |
|---|---|---|---|
| stream | No | Enable streaming mode (server aggregates, client still returns final text) | |
| message | Yes | The message to send in the conversation | |
| max_tokens | No | Optional cap for this single response | |
| budget_limit | No | Set or override per-conversation budget in USD | |
| conversation_id | Yes | The ID of the conversation to continue | |
| confirm_spending | No | User confirmation to proceed with spending if budget is tight |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it offers none. It does not mention spending, side effects, streaming behavior, budget limits, or confirmation requirements, all of which are significant for a tool involving monetary costs and conversation state changes. The description is purely a functional statement with no transparency about how the tool behaves.
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, focused sentence with no wasted words, front-loading the core purpose effectively. However, it is extremely sparse, which slightly undercuts its value as a complete tool description, but for conciseness alone it earns a strong score.
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?
The tool has 6 parameters including financial ones (budget_limit, confirm_spending), a streaming flag, and a token cap, yet the description provides no context about return values, cost implications, required confirmations, or streaming behavior. With no output schema and no annotations, this description is severely incomplete for a tool of this complexity.
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 provides 100% coverage of parameter descriptions, so the schema alone adequately documents the parameters. The tool description adds no additional meaning or context beyond the schema, leaving the agent to rely solely on schema descriptions. Per the rubric, baseline 3 is appropriate since schema coverage is high and no extra semantics are provided.
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 'Continue an existing conversation with GPT-5' uses a specific verb (continue) and resource (existing conversation with GPT-5), clearly distinguishing it from sibling tools like start_conversation. It immediately conveys the tool's core action without ambiguity, making it stand out among similar conversational tools.
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 usage: use this tool to continue an existing conversation rather than start a new one (contrasting with start_conversation). However, it does not explicitly state when to use this tool over alternatives like consult_gpt5 or summarize_conversation, nor does it mention any exclusions or prerequisites. The context is clear but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return conversation metadata and messages
| Name | Required | Description | Default |
|---|---|---|---|
| conversation_id | Yes | Conversation ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself, but it only says 'Return conversation metadata and messages'. It implies a read-only operation but provides no details on response structure, pagination, ordering, or potential side effects. This is minimal disclosure.
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, short sentence that front-loads the verb and resource. It is appropriately sized for a simple getter tool, with no unnecessary words, though it could include more detail 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 tool's simplicity—one parameter, no output schema—the description covers the basic purpose. However, it lacks details on what metadata is returned, message format, or any limitations, leaving some gaps for a complete understanding.
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 only parameter, conversation_id, is fully described in the schema as 'Conversation ID', providing 100% schema description coverage. The tool description adds no additional meaning beyond the schema, so the baseline 3 applies.
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 'Return' and names the resource 'conversation metadata and messages', which clearly states the tool's purpose. It distinguishes itself from siblings like summarize_conversation or continue_conversation by focusing on metadata and messages, though it does not explicitly name 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 on when to use this tool versus alternatives such as get_cost_report or set_conversation_options. The description only states the action, omitting context like prerequisites, use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a report of current costs and usage
| Name | Required | Description | Default |
|---|---|---|---|
| period | Yes | The period to report on |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only states 'Get a report' without detailing return format, how 'current' is interpreted relative to the period parameter, or any other behavioral traits such as read-only nature or potential side effects.
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 concise sentence, front-loaded with the action and resource. Every word earns its place, and there is no redundancy.
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 read-only tool with one parameter and no output schema, the description is minimally viable. However, it leaves gaps: it does not explain what 'costs and usage' includes, whether the report is aggregate or detailed, or how the period parameter affects the output. This is adequate but not complete.
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 has 100% coverage for the single parameter 'period' with a clear description and enum. The tool description itself adds no parameter information, so it meets the baseline of 3 without enhancing semantic understanding.
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 the tool's function with a specific verb ('Get') and resource ('report of current costs and usage'). It is distinct from sibling tools like set_cost_limits and get_conversation_metadata, though it could more explicitly delineate its scope compared to those.
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 on when to use this tool versus alternatives. Sibling tools exist (e.g., set_cost_limits), but the description does not mention exclusions or direct users to alternative tools for other use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adjust conversation budget/context options
| Name | Required | Description | Default |
|---|---|---|---|
| budget_limit | No | Per-conversation budget limit in USD | |
| context_limit | No | Messages to keep in context window | |
| conversation_id | Yes | Conversation ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Adjust', implying a mutation, but provides no additional behavioral context. It does not disclose whether the adjustment affects ongoing conversations, when changes take effect, whether any special permissions are needed, or what the tool returns. With no annotations to fall back on, the description carries the full burden, and 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, compact sentence with no fluff or repetition. It is front-loaded with the verb and the key resource. While it could be more informative, conciseness is about efficiency, and this description achieves that perfectly.
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 mutation tool with no annotations and no output schema, this description is notably incomplete. It does not mention side effects, return values, or how it relates to other conversation-management tools. The agent would need to infer behavior from the schema alone, which is not enough for a tool that modifies state.
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 already covers 100% of the parameters, including descriptions for 'budget_limit' (per-conversation budget limit in USD) and 'context_limit' (messages to keep in context window). The description adds a high-level grouping ('budget/context options') but does not provide additional semantics beyond the schema. Thus a baseline score 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 clearly states the action ('Adjust') and the target ('conversation budget/context options'), which gives a clear sense of the resource. However, it does not explicitly distinguish from the sibling tool 'set_cost_limits', which likely also deals with budget settings. The presence of 'conversation_id' in the schema hints at per-conversation scope, but the description alone does not make that distinction.
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 on when to use this tool versus alternatives. With siblings like 'set_cost_limits' and 'get_conversation_metadata', the agent would benefit from knowing that this tool is for adjusting per-conversation budget/context settings, while 'set_cost_limits' is probably for global cost limits. The description gives no such differentiation or prerequisite information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure spending limits for GPT-5 usage
| Name | Required | Description | Default |
|---|---|---|---|
| task_limit | No | Per-task spending limit in USD | |
| daily_limit | No | Daily spending limit in USD |
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. It implies mutation via 'Configure' but does not state whether this overwrites existing limits, requires specific permissions, or has any side effects. It also does not describe the response or error behavior.
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 concise sentence that front-loads the action and resource. There is no filler, redundancy, or unnecessary detail. It is appropriately sized for the tool's simplicity.
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?
The tool is simple with only two optional parameters and no output schema, so the description is close to adequate. However, it lacks usage guidelines and behavioral transparency, making it minimally viable but not fully complete for confident invocation in all scenarios.
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 already provides 100% coverage with clear descriptions for both parameters (task_limit and daily_limit in USD). The description adds only the context that these are for GPT-5 usage, which is minimal additional meaning beyond 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 uses a specific verb 'Configure' with resource 'spending limits for GPT-5 usage', clearly distinguishing it from sibling tools like get_cost_report (which reports costs) and set_conversation_options (which sets conversation options). The scope is unambiguous.
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 on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or relationships to siblings like get_cost_report for viewing limits or set_conversation_options for other settings. The usage context is entirely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new conversation with GPT-5
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The topic or purpose of the conversation | |
| budget_limit | No | Per-conversation budget limit in USD | |
| instructions | No | System instructions for the conversation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing behavior. It only says 'Start a new conversation' without mentioning side effects such as creating a new session, potential costs, or what happens to existing conversations. This is a significant transparency gap for a tool that initiates an action.
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, clear sentence with no redundant information. It is efficiently front-loaded and easy to parse, though not as structured as descriptions with multiple sections.
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 absence of an output schema and annotations, the description should explain what the tool returns (e.g., conversation ID) and provide context about how the parameters interact. It does not, leaving the tool under-specified for agents trying to understand its full effect.
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 describes all three parameters (topic, budget_limit, instructions) with 100% coverage. The tool description itself adds no additional meaning beyond the schema, so the baseline score 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 clearly states the action ('Start a new conversation') and the resource ('GPT-5'), making the tool's purpose unmistakable. The word 'new' distinguishes it from the sibling tool 'continue_conversation', though it does not explicitly name 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?
The intent is implied: use when you want to begin a fresh conversation. However, there is no explicit guidance about when to choose this over 'continue_conversation' or 'consult_gpt5', nor any mention of prerequisites or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize a conversation to reduce context size
| Name | Required | Description | Default |
|---|---|---|---|
| max_tokens | No | Max tokens to allocate for summary generation | |
| keep_last_n | No | How many recent messages to keep verbatim | |
| conversation_id | Yes | Conversation ID |
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 only states that it summarizes to reduce context size but does not disclose whether the conversation is modified, if messages are deleted, whether the operation has side effects, or what happens to the original messages. This is a significant gap for a tool that likely alters conversation state.
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 that efficiently communicates the core function and purpose. It is front-loaded with the action and contains zero filler, making every word earn 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?
The description is insufficient for a tool that likely mutates conversation state, especially with no annotations or output schema. It does not explain what happens to the conversation, what the summary looks like, or how parameters like keep_last_n influence behavior. The complexity and potential side effects demand a more detailed description.
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 already describes all three parameters (100% coverage), so the baseline is 3. The description adds no additional parameter semantics—it does not explain how max_tokens or keep_last_n affect the summarization process or how they interact, leaving the schema to carry the full 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 uses the specific verb 'summarize' and resource 'a conversation' with the clear purpose 'to reduce context size'. It distinguishes itself from sibling tools like continue_conversation or start_conversation because none of them mention summarization.
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 phrase 'to reduce context size' implies when to use the tool, but it does not explicitly state when not to use it or mention alternatives. No exclusions or comparisons to sibling tools are given, so the guidance remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0consult_gpt5continue_conversationget_conversation_metadataget_cost_reportset_conversation_optionsset_cost_limitsstart_conversationsummarize_conversationScored across 8 tools
The purposes of consult_gpt5, start_conversation, and continue_conversation overlap somewhat, as all involve interacting with GPT-5. However, get_cost_* and set_cost_* are clearly distinct, and get_conversation_metadata vs summarize_conversation serve different needs.
Most tools follow a verb_noun pattern (e.g., start_conversation, get_cost_report, set_cost_limits). The exception is consult_gpt5, which embeds the object directly rather than using a generic noun, but the naming style is otherwise consistent.
With 8 tools, the server is well-scoped for managing GPT-5 conversations and costs. Each tool covers a distinct aspect of the workflow without unnecessary bloat, and the count is appropriate for the domain.
The core lifecycle of conversation management and cost control is covered, including starting, continuing, summarizing, and monitoring usage. Minor gaps include the lack of an explicit 'end_conversation' or 'delete_conversation' tool, but agents can likely work around these.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
Agent personas for Claude. 16 tools, 13 personas, 3 workflows. Zero extra API cost. Free.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
