Grok MCP

Implementation Reference

• src/server.py:304-393 (handler)

  The main grok_agent tool handler function decorated with @mcp.tool(). This function implements a comprehensive AI agent that can use web search, X (Twitter) search, code execution, handle file attachments, process images (from URLs or local paths), accept system prompts, and return citations. It creates an XAI client chat session with configurable tools and parameters.
  @mcp.tool() async def grok_agent( prompt: str, model: str = "grok-4-1-fast", file_ids: Optional[List[str]] = None, image_urls: Optional[List[str]] = None, image_paths: Optional[List[str]] = None, use_web_search: bool = False, use_x_search: bool = False, use_code_execution: bool = False, allowed_domains: Optional[List[str]] = None, excluded_domains: Optional[List[str]] = None, allowed_x_handles: Optional[List[str]] = None, excluded_x_handles: Optional[List[str]] = None, from_date: Optional[str] = None, to_date: Optional[str] = None, enable_image_understanding: bool = False, enable_video_understanding: bool = False, include_inline_citations: bool = False, system_prompt: Optional[str] = None, max_turns: Optional[int] = None ): client = Client(api_key=XAI_API_KEY) tools = [] if use_web_search: web_params = build_params( allowed_domains=allowed_domains, excluded_domains=excluded_domains, enable_image_understanding=enable_image_understanding, ) tools.append(xai_web_search(**web_params)) if use_x_search: x_params = build_params( allowed_x_handles=allowed_x_handles, excluded_x_handles=excluded_x_handles, from_date=datetime.strptime(from_date, "%d-%m-%Y") if from_date else None, to_date=datetime.strptime(to_date, "%d-%m-%Y") if to_date else None, enable_image_understanding=enable_image_understanding, enable_video_understanding=enable_video_understanding, ) tools.append(xai_x_search(**x_params)) if use_code_execution: tools.append(code_execution()) include_options = ["code_execution_call_output"] if include_inline_citations: include_options.append("inline_citations") chat_params = {"model": model, "include": include_options} if tools: chat_params["tools"] = tools if max_turns: chat_params["max_turns"] = max_turns chat = client.chat.create(**chat_params) if system_prompt: chat.append(system(system_prompt)) content_items = [] if file_ids: for fid in file_ids: content_items.append(file(fid)) if image_urls: for url in image_urls: content_items.append(image(image_url=url)) if image_paths: for path in image_paths: ext = Path(path).suffix.lower().replace('.', '') base64_img = encode_image_to_base64(path) content_items.append(image(image_url=f"data:image/{ext};base64,{base64_img}")) content_items.append(prompt) chat.append(user(*content_items)) response = chat.sample() client.close() result = [response.content] if response.citations: result.append("\n\n**Sources:**") for url in response.citations: result.append(f"- {url}") return "\n".join(result)
• src/server.py:304-304 (registration)

  The @mcp.tool() decorator registers the grok_agent function as an MCP tool, making it available for use by the protocol.
  @mcp.tool()
• src/utils.py:40-45 (helper)

  The build_params helper function used by grok_agent to filter out None values and build clean parameter dictionaries for web search and x_search tools.
  def build_params(**kwargs): result = {} for key, value in kwargs.items(): if value: result[key] = value return result
• src/utils.py:13-18 (helper)

  The encode_image_to_base64 helper function used by grok_agent to convert local image files to base64 strings for inclusion in chat messages.
  def encode_image_to_base64(image_path: str): path = Path(image_path) if not path.exists(): raise FileNotFoundError(f"Image file not found: {image_path}") with open(image_path, "rb") as image_file: return base64.b64encode(image_file.read()).decode("utf-8")
• src/utils.py:8-10 (helper)

  XAI_API_KEY configuration loaded from environment and used by grok_agent to authenticate with the XAI client.
  XAI_API_KEY = os.getenv("XAI_API_KEY", "") if XAI_API_KEY: os.environ["XAI_API_KEY"] = XAI_API_KEY