Grimoire

Ghid operator pentru Native MCP Client

4 min read

Ghid operator pentru Native MCP Client

Ce face

native-mcp este clientul MCP integrat în Hermes Agent. Se conectează la servere MCP la pornirea agentului, descoperă tool-urile expuse de ele și le înregistrează ca tool-uri native, lângă tool-urile built-in precum terminal sau read_file.

Nu ai nevoie de un bridge CLI separat pentru utilizarea normală. Dacă serverul MCP este definit corect în configurație, Hermes îl pornește sau îl contactează, citește lista de tool-uri și le face apelabile direct de agent.

Numele tool-urilor urmează convenția:

mcp_{server_name}_{tool_name}

Exemple:

  • server filesystem, tool read_file → mcp_filesystem_read_file
  • server github, tool list-issues → mcp_github_list_issues
  • server my-api, tool fetch.data → mcp_my_api_fetch_data

Hyphen-urile și punctele sunt transformate în underscore pentru compatibilitate cu API-urile LLM.

Când îmi folosește

Îți folosește când vrei capabilități externe disponibile direct în Hermes:

  • servere MCP locale prin npx, uvx sau altă comandă;
  • integrări cu filesystem, GitHub, baze de date sau API-uri;
  • servere remote HTTP / StreamableHTTP;
  • tool-uri disponibile automat în conversații, fără apel manual din terminal;
  • mai multe servere MCP conectate simultan, cu prefix separat pe fiecare server.

Pentru apeluri MCP ad-hoc, one-off, din terminal, fără configurare permanentă, folosește skill-ul mcporter în loc.

Vezi și All guides pentru restul ghidurilor.

Cum îl invoc / declanșez

Nu există o comandă conversațională universală de tip „invocă native-mcp”. Declanșarea este la nivel de runtime: Hermes citește mcp_servers din ~/.hermes/config.yaml la startup și descoperă serverele definite acolo.

Config minim pentru stdio:

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

După modificare, repornește Hermes Agent. Nu există hot-reload curent pentru adăugarea sau eliminarea serverelor.

La pornire, Hermes:

  1. citește serverele din configurație;
  2. se conectează la fiecare server;
  3. rulează descoperirea tool-urilor;
  4. înregistrează tool-urile cu prefixul mcp_<server>_*;
  5. le injectează în toolset-urile platformei.

Pentru stdio:

mcp_servers:
  server_name:
    command: "npx"
    args: ["-y", "pkg-name"]
    env:
      SOME_API_KEY: "<value>"
    timeout: 120
    connect_timeout: 60

Pentru HTTP:

mcp_servers:
  server_name:
    url: "https://example.invalid/mcp"
    headers:
      Authorization: "Bearer <token>"
    timeout: 180
    connect_timeout: 60

Un server trebuie să aibă fie command, fie url, nu ambele.

Exemplu practic

Vrei un server MCP local bazat pe uvx, care expune tool-uri de timp.

  1. Instalează SDK-ul MCP, dacă lipsește:
pip install mcp

sau:

uv pip install mcp
  1. Adaugă în ~/.hermes/config.yaml:
mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]
  1. Repornește Hermes Agent.

După restart, Hermes ar trebui să descopere tool-urile serverului și să le înregistreze cu prefixul mcp_time_*, de exemplu mcp_time_get_current_time dacă serverul expune acel tool. Agentul le poate folosi natural când cererea are nevoie de acea capabilitate.

Output / unde aterizează

Output-ul principal nu aterizează într-un fișier de utilizator. Rezultatul este în registrul intern de tool-uri Hermes: tool-urile MCP devin tool-uri first-class și sunt disponibile în conversațiile deservite de procesul agentului.

Rezultatele apelurilor de tool sunt returnate către agent ca JSON, de regulă în forma:

{"result": "..."}

sau:

{"error": "..."}

Conexiunile sunt persistente pe durata procesului Hermes. Dacă o conexiune cade, clientul încearcă reconectarea cu backoff exponențial, până la limita configurată intern. La oprirea agentului, conexiunile sunt închise curat.

Limite / gotchas

Ai nevoie de pachetul Python mcp; dacă lipsește, suportul MCP este dezactivat și poți vedea mesajul MCP SDK not available -- skipping MCP tool discovery.

Pentru servere npx, ai nevoie de Node.js. Pentru servere uvx, ai nevoie de uv. Pentru HTTP / StreamableHTTP, versiunea instalată de mcp trebuie să includă suportul HTTP; altfel serverul respectiv poate eșua, iar celelalte continuă.

Dacă nu există cheia mcp_servers, sau este goală, nu există servere de descoperit.

Pentru stdio, Hermes nu transmite întreg environment-ul shell-ului către subprocess. Moștenește doar variabile de bază și XDG_*; secretele trebuie adăugate explicit în env. Nu pune valori reale în exemple publice, chat sau documentație. Folosește placeholders.

Erorile încearcă să redacteze automat token-uri și chei, dar asta nu este o scuză să le expui.

Sampling-ul MCP este suportat și activ implicit: serverele pot cere completări LLM prin agent în timpul execuției. Pentru servere neîncredere, dezactivează-l explicit:

sampling:
  enabled: false

Tool-urile MCP pot accesa datele și sistemele la care le dai acces prin server. Configurează doar servere de încredere, limitează scope-ul, verifică path-urile, token-urile și header-ele, și repornește agentul după modificări.

Graph View