Responses API și MCP pe Groq: unelte server-side, servere MCP și conectori în Groq: LPU și GroqCloud API

client = OpenAI(base_url="https://api.groq.com/openai/v1", api_key=...)
client.responses.create(model="openai/gpt-oss-120b", input=..., tools=[{"type": "mcp", ...}])

Responses API (POST /openai/v1/responses) este în beta și se folosește cu clientul OpenAI, cu base_url="https://api.groq.com/openai/v1"; SDK-ul groq nu are încă metoda responses. Acceptă text și imagini ca intrare, raționament, Structured Outputs și function calling. Nu păstrează conversații pe server: trimiți singur istoricul la fiecare cerere. Nu sunt acceptate previous_response_id, store, truncation, include, safety_identifier, prompt_cache_key și prompt.

Uneltele built-in browser_search (căutare web prin Exa) și code_interpreter (Python într-un sandbox E2B) merg doar cu openai/gpt-oss-20b și openai/gpt-oss-120b. Un tool de tip mcp indică un server MCP la distanță (HTTPS): Groq descoperă uneltele cu tools/list, le dă modelului, execută apelurile cu tools/call și întoarce răspunsul final, totul într-o singură cerere. Remote MCP este în beta și merge pe modelele cu tool use (GPT-OSS, qwen/qwen3.8-27b și modelele Enterprise listate). Un server MCP vede tot contextul cererii, deci conectează doar servere de încredere.

Conectorii MCP (beta) sunt servere gata făcute pentru Google Workspace, doar citire: connector_gmail, connector_googlecalendar și connector_googledrive. Primesc un token OAuth 2.0 în câmpul authorization. Cu antetul Groq-Beta: inference-metrics, răspunsul conține în metadata timpii queue_time, prompt_time, completion_time și total_time.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
type: "mcp"	Tool care indică un server MCP la distanță.
server_label	Numele serverului, folosit în răspuns.
server_url	Adresa endpoint-ului MCP.
headers	Antete de autentificare; Groq le ascunde din loguri.
server_description	Ajută modelul să decidă când folosește serverul.
require_approval	Dacă apelurile cer aprobare umană (de exemplu never, always).
allowed_tools	Lista uneltelor permise de pe server.
connector_id / authorization	Conector Google Workspace și tokenul OAuth al utilizatorului.
{"type": "browser_search"}	Căutare web server-side (doar GPT-OSS).
{"type": "code_interpreter", "container": {"type": "auto"}}	Execuție de cod Python server-side (doar GPT-OSS).

Exemple practice și scenarii reale

Exemplul 1: Cerere simplă prin clientul OpenAI

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["GROQ_API_KEY"], base_url="https://api.groq.com/openai/v1")
r = client.responses.create(
    model="openai/gpt-oss-20b",
    input="Spune un fapt despre Lună într-o singură propoziție.",
)
print(r.output_text)

Exemplul 2: Server MCP la distanță (Hugging Face)

r = client.responses.create(
    model="openai/gpt-oss-120b",
    input="Ce modele sunt populare acum pe Hugging Face?",
    tools=[{
        "type": "mcp",
        "server_label": "Huggingface",
        "server_url": "https://huggingface.co/mcp",
        "require_approval": "never",
    }],
)
print(r.output_text)

Exemplul 3: Căutare web și execuție de cod built-in

r = client.responses.create(
    model="openai/gpt-oss-20b",
    input="Cât face 1312 x 3333? Scrie doar rezultatul.",
    tool_choice="required",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
)
print(r.output_text)

Exemplul 4: Conectorul Gmail

r = client.responses.create(
    model="openai/gpt-oss-120b",
    input="Arată-mi e-mailurile necitite din săptămâna aceasta.",
    tools=[{
        "type": "mcp",
        "server_label": "Gmail",
        "connector_id": "connector_gmail",
        "authorization": os.environ["GOOGLE_OAUTH_TOKEN"],   # scope gmail.readonly
        "require_approval": "never",
    }],
)

Greșeli frecvente și capcane

• Te bazezi pe previous_response_id pentru conversații. Pe Groq nu este acceptat; trimite istoricul în input.
• Ceri browser_search sau code_interpreter unui model care nu este GPT-OSS. Uneltele built-in sunt acceptate doar de GPT-OSS 20B și 120B.
• Conectezi un server MCP necunoscut. Serverul primește conținutul cererii, inclusiv promptul de sistem și istoricul.
• Folosești un server MCP local (stdio) ca tool mcp. Remote MCP cere un server accesibil prin HTTPS; pentru stdio orchestrezi singur apelurile, ca la tool calling local.

Noțiuni și module înrudite

• groq-tool-calling-json
• groq-compound-inference
• groq-reasoning