Skip to main content
Glama
deenesjakoruzh
merterbak

Grok MCP

by merterbak
OverviewSchemaRelated ServersScoreDiscussions
Python

Grok-MCP

MCP server for xAI’s Grok API with Web/X search, vision, image/video generation and file support.

Features

  • Agentic Tool Calling: Web search, X search, code execution, and image generation with multi-step reasoning

  • Multiple Grok Models: Access to latest models such as grok-4.6, grok-4.5, grok-build-0.1 and more

  • Image and Video Generation: Create images and videos using Grok Imagine

  • Vision Capabilities: Analyze images with Grok's vision models

  • Files API: Upload, manage, and chat with documents

  • Stateful Conversations: Maintain conversation context as id across multiple requests

  • Local Chat History: Option to save persistent client side chat history as JSON files in chats/

Related MCP server: Grok Image MCP

Prerequisites

Installation

  1. Clone the repository:

git clone https://github.com/merterbak/Grok-MCP.git
cd Grok-MCP

  1. Create a venv environment:

uv venv
source .venv/bin/activate # macOS/Linux or .venv\Scripts\activate on Windows

  1. Install dependencies:

uv sync

Configuration

Claude Desktop Integration

Add this to your Claude Desktop configuration file:

{
  "mcpServers": {
    "grok": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Grok-MCP",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "XAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code Integration

Run this command from inside the project directory:

claude mcp add grok-mcp -e XAI_API_KEY=your_api_key_here -- uv run --directory /path/to/Grok-MCP python main.py

Or if you have a .env file with your key:

 claude mcp add grok-mcp -- uv run --directory /path/to/Grok-MCP python main.py

Verify it's registered:

claude mcp list

Filesystem MCP (Optional)

Claude Desktop can't send uploaded images in the chat to an MCP tool. The easiest way to give access to files directly from your computer is official Filesystem MCP server. After setting it up you’ll be able to just write the image’s file path (such as /Users/mert/Desktop/image.png) in chat and Claude can use it with any vision chat tool.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/<your-username>/Desktop",
        "/Users/<your-username>/Downloads"
      ]
    }
  }
}

For stdio:

uv run python main.py

Docker:

docker compose up --build

Mcp Inspector:

mcp dev main.py

Available Tools

Each tool has a full docstring in src/server.py with its arguments and return format. MCP client surfaces those directly, so this list is just a quick map of what's available.

Note: For using images and files, you must provide paths to chat. See Filesystem MCP (Optional) for setup.

Chat and reasoning

  • chat — standard chat completion with optional persistent history, multi-agent support, and a per request service_tier.

  • chat_with_vision — analyze local or remote images with a Grok vision model.

  • chat_with_files — chat grounded on previously uploaded documents.

  • stateful_chat — continue a server-side stored conversation via response_id.

  • retrieve_stateful_response — fetch a stored response by ID.

  • delete_stateful_response — delete a stored response by ID.

Agentic tools

  • web_search — autonomous web research with domain filters and citations.

  • x_search — autonomous search over X (Twitter) posts, with handle and date filters.

  • code_executor — solve tasks by running Python in a sandbox.

  • grok_agent — unified agent that mixes files, images, web search, X search, code execution, and server-side image generation. Generated images are written to images/.

Image and video

  • generate_image — create or edit images with Grok Imagine (multi-reference editing supported). Pass save=true to write the results to images/ instead of returning temporary URLs.

  • generate_video — text-to-video, image-to-video, or video editing with Grok Imagine.

  • extend_video — extend an existing generated video with a follow-up prompt.

Files

  • upload_file — upload a local document.

  • list_files — list uploaded files with sorting.

  • get_file — fetch file metadata by ID.

  • get_file_content — download file content as text.

  • delete_file — delete a file by ID.

Local chat history

  • list_chat_sessions — list saved sessions in chats/.

  • get_chat_history — get a session's full transcript.

  • clear_chat_history — delete a session's local history file.

Models

  • list_models — list all Grok language and image models with live pricing.

License

This project is open source and available under the MIT License.

Available Tools

10 tools
chatA

Send a text prompt to a Grok model and return its reply.

Replays prior turns from `chats/{session}.json` when a session is given,
then appends the new user message and saves the round trip.

Args:
    prompt: User message to send to the model.
    session: Optional session name. Loads and appends history to `chats/{session}.json`.
    model: Grok model id (default `grok-4.3`).
    system_prompt: Optional system instruction prepended to the conversation.
    agent_count: 4 or 16. Only valid with `grok-4.20-multi-agent` for multi-agent research.
    show_usage: Append a token usage and cost footer to the reply (default False).

Returns:
    The assistant's reply text, plus a token usage and cost footer when `show_usage` is true.
ParametersJSON Schema
NameRequiredDescriptionDefault
modelNogrok-4.3
promptYes
sessionNo
show_usageNo
agent_countNo
system_promptNo

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It effectively discloses the tool's behavior: sending a prompt, replaying prior turns from a session file, appending new messages, and saving the conversation. It also notes constraints like agent_count only valid with a specific model. Minor omission: does not mention that session files are created or modified, but 'saves the round trip' implies persistence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose, followed by structured Arg and Returns sections. It is concise for the complexity but could be slightly tighter. Every sentence adds value, though the explanation of session behavior could be integrated more succinctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters, no output schema, and no enums, the description covers all parameters, return value, and session mechanics. It lacks details on error handling, rate limits, or usage bounds, but the level of detail is adequate for an AI agent to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description compensates fully with a detailed Args section explaining each parameter, including default values, allowed values, and constraints (e.g., agent_count only valid with grok-4.20-multi-agent). This adds significant meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Send a text prompt to a Grok model and return its reply', specifying the verb and resource. It elaborates on session replay and saving, making the tool's purpose distinct from siblings like chat_with_files or chat_with_vision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for text-only chat with optional session persistence but does not explicitly guide when to use this tool versus alternatives (e.g., chat_with_files for file-based queries). No when-not-to-use or alternative names are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

chat_with_filesA

Chat with Grok using one or more previously uploaded files as context.

Attaches the given `file_ids` to the user turn so Grok can read/quote their
contents. Optional `session` persists local chat history across calls.

Args:
    prompt: Question or instruction about the attached files.
    file_ids: IDs of files previously returned by `upload_file`.
    session: Optional session name for persistent history in `chats/{session}.json`.
    model: Grok model id (default `grok-4.3`).
    system_prompt: Optional system instruction prepended to the conversation.
    show_usage: Append a token usage and cost footer to the reply (default False).

Returns:
    Assistant reply, followed by a `**Sources:**` list when the model cites URLs.
ParametersJSON Schema
NameRequiredDescriptionDefault
modelNogrok-4.3
promptYes
sessionNo
file_idsYes
show_usageNo
system_promptNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses that file_ids are attached to the user turn, optional session persists history, and returns assistant reply with sources list. It does not mention auth or error handling, but covers key behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (9 lines), well-structured with general behavior, Args list, and Returns. Every sentence adds value; no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and no output schema, the description covers parameters and return value. Missing details like file type constraints or error conditions, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description's Args section explains each parameter in detail (e.g., session path, default model, usage flag). This adds significant meaning beyond the schema's bare structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool chats with Grok using uploaded files as context. The verb 'Chat' and resource 'files' are specific. It distinguishes from siblings like 'chat' (no files) and 'chat_with_vision' (vision-specific).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for file-based queries ('using one or more previously uploaded files as context'). However, it does not explicitly state when to use this vs. alternatives (e.g., 'chat' without files) or provide contraindications.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_fileA

Permanently delete an uploaded file from xAI.

Args:
    file_id: ID of the file to remove.

Returns:
    Confirmation string with the deleted file ID.
ParametersJSON Schema
NameRequiredDescriptionDefault
file_idYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility for behavioral disclosure. It states 'Permanently delete', indicating destructiveness, and mentions the return type. However, it does not detail side effects, permission requirements, or error scenarios.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise, with three sentences covering purpose, parameter, and return value. No extraneous information is included.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one parameter, no output schema, no nested objects), the description covers the core behavior adequately. It explains the permanent nature of the deletion and the return value, though it lacks error handling context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description must compensate. The description adds minimal value by labeling the parameter as 'ID of the file to remove', but this largely restates the schema field's name and type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the operation (Permanently delete) and the resource (uploaded file from xAI). It distinguishes this tool from siblings like get_file, list_files, and upload_file by explicitly describing a delete operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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 (e.g., when not to use it, prerequisites, or alternatives). It implicitly states usage via the action 'Permanently delete', but lacks explicit contextual guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_stateful_responseA

Delete a stored chat completion from xAI's servers.

Args:
    response_id: ID of the stored response to remove.

Returns:
    Confirmation string with the deleted response ID.
ParametersJSON Schema
NameRequiredDescriptionDefault
response_idYes

TDQS

A4.3/5.0
Behavior4/5

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 clearly indicates the action deletes a resource from servers and returns a confirmation, implying permanence. However, it lacks details on authorization requirements or potential side effects beyond the deletion itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (three sentences) and well-structured: purpose, argument, return. Every word adds value without any fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one required parameter) and the lack of an output schema, the description is mostly complete. It covers what, how, and the return value. Minor missing details include error handling for invalid IDs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining that 'response_id' is the ID of the stored response to remove, adding meaningful context beyond the schema's title and type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Delete' and the resource 'stored chat completion', making the tool's purpose immediately understandable. It distinguishes itself from sibling tools like 'retrieve_stateful_response' (which retrieves) and 'chat' (which creates).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for removing stored responses but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. No guidance on prerequisites or potential errors.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

extend_videoA

Extend an existing video with a follow-up prompt.

Continues the source video seamlessly from its last frame. `duration` sets
the length of the extension only, not the total output. For example, a
10 second input plus `duration=5` yields a 15 second final video.

Args:
    prompt: What should happen in the extended segment.
    video_url: Public URL of the source video (.mp4, 2–15 s).
    model: Video model (default `grok-imagine-video`).
    duration: Length of the extension in seconds (2–10, default 6).
    show_usage: Append a token usage and cost footer to the result (default False).

Returns:
    Markdown block with the extended video URL and total duration.
ParametersJSON Schema
NameRequiredDescriptionDefault
modelNogrok-imagine-video
promptYes
durationNo
video_urlYes
show_usageNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description explains duration is for extension only, returns markdown with URL and total duration. Lacks details on side effects or auth needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise with a clear top sentence, followed by a paragraph clarifying duration behavior, then a structured Args list. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers parameter semantics and return value; lacks error conditions or edge cases, but overall complete for a tool with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description fully compensates by explaining each parameter's role, constraints (e.g., video_url .mp4 2-15s, duration 2-10, default 6), and behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States 'Extend an existing video with a follow-up prompt' and explains it continues from the last frame, distinguishing it from generate_video which creates new videos.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly indicates when to use (to extend a video) but does not explicitly state when not to use or mention alternatives like generate_video for creation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_fileA
Read-only

Fetch metadata for a single uploaded file.

Args:
    file_id: ID returned by `upload_file`.

Returns:
    Markdown block with the file's ID, filename, size, and creation time.
ParametersJSON Schema
NameRequiredDescriptionDefault
file_idYes

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description aligns with the annotation readOnlyHint=true by stating 'Fetch metadata'. It adds the return format (Markdown block with fields) but does not disclose other behaviors like error handling or authorization needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief with a clear structure: one sentence for purpose, then separated Args and Returns sections. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema. The description covers the input source, the return format, and the core action. It is complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides no description for the file_id parameter (0% coverage). The description compensates by specifying that the ID is 'returned by upload_file', giving the agent a source for the value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Fetch' and clearly specifies the resource 'metadata for a single uploaded file'. It distinguishes from siblings like 'get_file_content' by focusing on metadata retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states the purpose and the source of the file_id ('returned by upload_file'), which implies when to use it. It does not explicitly list alternatives or when not to use, but the context is adequate for an agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_file_contentA
Read-only

Download the raw content of an uploaded file as text.

Bytes are decoded as UTF-8 with replacement for invalid sequences. Output
is truncated to `max_bytes` to avoid overwhelming the response.

Args:
    file_id: ID of the uploaded file.
    max_bytes: Maximum bytes to return (default 500 000).

Returns:
    File text, with a truncation note appended when the content exceeds `max_bytes`.
ParametersJSON Schema
NameRequiredDescriptionDefault
file_idYes
max_bytesNo

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses important behavioral traits beyond the readOnlyHint annotation: UTF-8 decoding with replacement, truncation to max_bytes, and a truncation note. This adds significant context 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with clear sections for Args and Returns. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description includes return format and truncation behavior. It covers all necessary aspects: parameters, encoding, truncation, and default behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining the purpose of 'max_bytes' (to avoid overwhelming response) and its default value. The 'file_id' description is minimal but adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool downloads raw content of an uploaded file as text. It uses a specific verb and resource, differentiating it from sibling tools like 'get_file' (presumably metadata) and 'upload_file'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing raw text content, but does not explicitly state when to use this tool over alternatives like 'get_file'. No exclusions or conditions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_filesA
Read-only

List files previously uploaded to xAI.

Args:
    limit: Maximum number of files to return (default 100).
    order: `"asc"` or `"desc"` sort order (default `"desc"`).
    sort_by: Field to sort by, such as `"created_at"`.

Returns:
    Markdown list of files with ID, filename, and size, or a placeholder when empty.
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
orderNodesc
sort_byNocreated_at

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true. The description adds behavior beyond annotations by specifying the return format (Markdown list with ID, filename, size, or placeholder) and default parameter values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with separate Args and Returns sections. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a simple listing tool: it explains the action, parameters, and return format. No output schema is present, so the return description is essential and provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining all three parameters: limit (max number, default 100), order (asc/desc, default desc), and sort_by (field, default created_at). This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List files previously uploaded to xAI,' which is a specific verb+resource. It distinguishes from siblings like get_file, delete_file, and upload_file by focusing on listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is provided. The description is self-explanatory, but lacks alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

retrieve_stateful_responseA
Read-only

Fetch a stored chat completion from xAI by its response ID.

Args:
    response_id: ID returned by a prior `stateful_chat` call.

Returns:
    The stored assistant reply and its `**Response ID:**`, or a not-found message.
ParametersJSON Schema
NameRequiredDescriptionDefault
response_idYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses return behavior (the reply and Response ID or a not-found message) which adds value beyond the readOnlyHint annotation. It does not cover rate limits or detailed error scenarios, but the annotation already ensures safe usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise with two sentences and an Args bullet, front-loading the main purpose. Every sentence is necessary and no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with one parameter and a readOnly annotation, the description covers the essential inputs and outputs. Minor gap: no mention of error handling for invalid IDs, but overall complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema description coverage is 0%, the description's 'Args' section explains that 'response_id' is the ID from a prior 'stateful_chat' call, adding significant meaning beyond the schema's type and title.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Fetch a stored chat completion' with a specific resource and identifier, clearly differentiating from siblings like 'stateful_chat' (creation) and 'delete_stateful_response' (deletion).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It specifies the prerequisite of a prior 'stateful_chat' call, providing clear context for use. However, it does not explicitly state when not to use or list alternatives, though the sibling names imply the distinctions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upload_fileA

Upload a local file to xAI so it can be attached to later chats.

Supported types include PDFs and text documents (see xAI file docs). The
returned file ID can be passed to `chat_with_files` or `grok_agent`.

Args:
    file_path: Absolute or relative path to the local file.
    expires_after: Optional TTL in seconds. The file is deleted from xAI
        automatically once it expires (omit to keep the file indefinitely).

Returns:
    Markdown block with the assigned file ID, filename, and size.
ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes
expires_afterNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses behavioral traits such as automatic file deletion after a TTL and the ability to keep files indefinitely. It does not cover auth requirements or error handling, but the provided info is sufficient for basic usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: one introductory paragraph followed by clear bullet-style parameter descriptions. No redundant sentences; every piece of information serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no output schema), the description covers purpose, parameters, return value (Markdown block with file ID, filename, size), and integration with other tools. It lacks details on error scenarios or file size limits, but is largely complete for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does so thoroughly: file_path is described as 'Absolute or relative path to the local file,' and expires_after as 'Optional TTL in seconds. The file is deleted from xAI automatically once it expires (omit to keep the file indefinitely).' This adds essential meaning beyond the bare schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Upload a local file to xAI so it can be attached to later chats.' It uses a specific verb ('upload') and resource ('local file to xAI'), and distinguishes it from sibling tools like get_file or chat_with_files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions supported file types (PDFs, text documents) and explains how the returned file ID is used with chat_with_files or grok_agent, providing context for when to use this tool. However, it doesn't explicitly state when not to use it or mention alternatives for different file handling.

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. Dates show when Glama detected each change.

  1. 12 tool updates
    • Removedchat_with_vision
    • Removedclear_chat_history
    • Removedcode_executor
    • Removedgenerate_image
    • Removedgenerate_video
    • Removedget_chat_history
    • Removedgrok_agent
    • Removedlist_chat_sessions
    • Removedlist_models
    • Removedstateful_chat
    • Removedweb_search
    • Removedx_search
  2. 11 tool updatesv1.0.1
    • Changedchat1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedchat_with_files1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedchat_with_vision1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedcode_executor1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedextend_video1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedgenerate_image1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedgenerate_video1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedgrok_agent1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedstateful_chat1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedweb_search1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
    • Changedx_search1 field changed
      • addedInput schema / properties / show_usage
        Added value: +{
+  "default": false,
+  "title": "Show Usage",
+  "type": "boolean"
+}
  3. 4 tool updates
    • Changedgenerate_video2 fields changed
      • addedInput schema / properties / reference_image_paths
        Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Reference Image Paths"
+}
      • addedInput schema / properties / reference_image_urls
        Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Reference Image Urls"
+}
    • Changedgrok_agent1 field changed
      • addedInput schema / properties / enable_image_search
        Added value: +{
+  "default": false,
+  "title": "Enable Image Search",
+  "type": "boolean"
+}
    • Changedupload_file1 field changed
      • addedInput schema / properties / expires_after
        Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Expires After"
+}
    • Changedweb_search1 field changed
      • addedInput schema / properties / enable_image_search
        Added value: +{
+  "default": false,
+  "title": "Enable Image Search",
+  "type": "boolean"
+}
  4. 22 tool updates
    • Addedchat
    • Addedchat_with_files
    • Addedchat_with_vision
    • Addedclear_chat_history
    • Addedcode_executor
    • Addeddelete_file
    • Addeddelete_stateful_response
    • Addedextend_video
    • Addedgenerate_image
    • Addedgenerate_video
    • Addedget_chat_history
    • Addedget_file
    • Addedget_file_content
    • Addedgrok_agent
    • Addedlist_chat_sessions
    • Addedlist_files
    • Addedlist_models
    • Addedretrieve_stateful_response
    • Addedstateful_chat
    • Addedupload_file
    • Addedweb_search
    • Addedx_search
  5. 22 tool updates
    • Removedchat
    • Removedchat_with_files
    • Removedchat_with_vision
    • Removedclear_chat_history
    • Removedcode_executor
    • Removeddelete_file
    • Removeddelete_stateful_response
    • Removedextend_video
    • Removedgenerate_image
    • Removedgenerate_video
    • Removedget_chat_history
    • Removedget_file
    • Removedget_file_content
    • Removedgrok_agent
    • Removedlist_chat_sessions
    • Removedlist_files
    • Removedlist_models
    • Removedretrieve_stateful_response
    • Removedstateful_chat
    • Removedupload_file
    • Removedweb_search
    • Removedx_search
  6. 22 tool updates
    • Addedchat
    • Addedchat_with_files
    • Addedchat_with_vision
    • Addedclear_chat_history
    • Addedcode_executor
    • Addeddelete_file
    • Addeddelete_stateful_response
    • Addedextend_video
    • Addedgenerate_image
    • Addedgenerate_video
    • Addedget_chat_history
    • Addedget_file
    • Addedget_file_content
    • Addedgrok_agent
    • Addedlist_chat_sessions
    • Addedlist_files
    • Addedlist_models
    • Addedretrieve_stateful_response
    • Addedstateful_chat
    • Addedupload_file
    • Addedweb_search
    • Addedx_search
  7. 22 tool updates
    • Removedchat
    • Removedchat_with_files
    • Removedchat_with_vision
    • Removedclear_chat_history
    • Removedcode_executor
    • Removeddelete_file
    • Removeddelete_stateful_response
    • Removedextend_video
    • Removedgenerate_image
    • Removedgenerate_video
    • Removedget_chat_history
    • Removedget_file
    • Removedget_file_content
    • Removedgrok_agent
    • Removedlist_chat_sessions
    • Removedlist_files
    • Removedlist_models
    • Removedretrieve_stateful_response
    • Removedstateful_chat
    • Removedupload_file
    • Removedweb_search
    • Removedx_search
  8. 6 tool updates
    • Changedchat1 field changed
      • addedInput schema / properties / agent_count
        Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Agent Count"
+}
    • Changedchat_with_files2 fields changed
      • removedInput schema / properties / file_ids / default
        Removed value: -null
      • changedInput schema / required
        Previous value: -[
-  "prompt"
-]New value: +[
+  "prompt",
+  "file_ids"
+]
    • Addedextend_video
    • Changedgenerate_image5 fields changed
      • removedInput schema / properties / image_path
        Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Image Path"
-}
      • addedInput schema / properties / image_paths
        Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Image Paths"
+}
      • removedInput schema / properties / image_url
        Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Image Url"
-}
      • addedInput schema / properties / image_urls
        Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Image Urls"
+}
      • addedInput schema / properties / resolution
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Resolution"
+}
    • Changedgrok_agent1 field changed
      • addedInput schema / properties / agent_count
        Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Agent Count"
+}
    • Changedupload_file1 field changed
      • removedInput schema / properties / filename
        Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Filename"
-}
  9. 21 tool updates
    • Addedchat
    • Addedchat_with_files
    • Addedchat_with_vision
    • Addedclear_chat_history
    • Addedcode_executor
    • Addeddelete_file
    • Addeddelete_stateful_response
    • Addedgenerate_image
    • Addedgenerate_video
    • Addedget_chat_history
    • Addedget_file
    • Addedget_file_content
    • Addedgrok_agent
    • Addedlist_chat_sessions
    • Addedlist_files
    • Addedlist_models
    • Addedretrieve_stateful_response
    • Addedstateful_chat
    • Addedupload_file
    • Addedweb_search
    • Addedx_search
  10. 21 tool updates
    • Removedchat
    • Removedchat_with_files
    • Removedchat_with_vision
    • Removedclear_chat_history
    • Removedcode_executor
    • Removeddelete_file
    • Removeddelete_stateful_response
    • Removedgenerate_image
    • Removedgenerate_video
    • Removedget_chat_history
    • Removedget_file
    • Removedget_file_content
    • Removedgrok_agent
    • Removedlist_chat_sessions
    • Removedlist_files
    • Removedlist_models
    • Removedretrieve_stateful_response
    • Removedstateful_chat
    • Removedupload_file
    • Removedweb_search
    • Removedx_search
  11. 8 tool updates
    • Changedchat1 field changed
      • changedInput schema / properties / model / default
        Previous value: -"grok-4"New value: +"grok-4-1-fast-reasoning"
    • Changedchat_with_files1 field changed
      • changedInput schema / properties / model / default
        Previous value: -"grok-4-1-fast"New value: +"grok-4-1-fast-reasoning"
    • Changedchat_with_vision1 field changed
      • changedInput schema / properties / model / default
        Previous value: -"grok-4"New value: +"grok-4-1-fast-reasoning"
    • Changedcode_executor1 field changed
      • changedInput schema / properties / model / default
        Previous value: -"grok-4-1-fast"New value: +"grok-4-1-fast-reasoning"
    • Changedgrok_agent1 field changed
      • changedInput schema / properties / model / default
        Previous value: -"grok-4-1-fast"New value: +"grok-4-1-fast-reasoning"
    • Changedstateful_chat1 field changed
      • changedInput schema / properties / model / default
        Previous value: -"grok-4"New value: +"grok-4-1-fast-reasoning"
    • Changedweb_search1 field changed
      • changedInput schema / properties / model / default
        Previous value: -"grok-4-1-fast"New value: +"grok-4-1-fast-reasoning"
    • Changedx_search1 field changed
      • changedInput schema / properties / model / default
        Previous value: -"grok-4-1-fast"New value: +"grok-4-1-fast-reasoning"
  12. 7 tool updates
    • Changedchat2 fields changed
      • addedInput schema / properties / session
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Session"
+}
      • removedInput schema / properties / store_messages
        Removed value: -{
-  "default": false,
-  "title": "Store Messages",
-  "type": "boolean"
-}
    • Changedchat_with_files1 field changed
      • addedInput schema / properties / session
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Session"
+}
    • Changedchat_with_vision1 field changed
      • addedInput schema / properties / session
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Session"
+}
    • Addedclear_chat_history
    • Addedget_chat_history
    • Changedgrok_agent1 field changed
      • addedInput schema / properties / session
        Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Session"
+}
    • Addedlist_chat_sessions
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0
Disambiguation5/5

Every tool has a clearly distinct purpose: chat variants are separated by modality (plain, files, vision), content generation is split by type (image, video, video extension), search is split by source (web, X), file operations form a clean CRUD set, and the all-in-one grok_agent combines them without overlap.

Naming Consistency5/5

Tool names follow a predictable pattern: chat_with_* for chat variants, generate_* for content generation, search for both search tools, verb_file for file operations, and stateful_chat/retrieve/delete_stateful_response for stateful conversations. The only minor deviation is code_executor and grok_agent, but they still convey their role clearly.

Tool Count4/5

With 22 tools, the server covers a broad range of capabilities (chat, files, images, video, search, code execution) without feeling bloated. While slightly higher than the typical 3-15 range, each tool earns its place given the multimodal nature of Grok.

Completeness5/5

The tool surface is remarkably complete: all chat modalities (text, files, vision, stateful, agentic), full file lifecycle (upload, list, get, delete, get content), image and video generation with editing, web and X search with filtering, code execution, and model listing. There are no obvious gaps for the platform's stated purpose.

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/merterbak/Grok-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server