Hugging Face API Skill

intent

discover open-source models and datasets on the hugging face hub for free, then run openai-compatible chat completions and embeddings across inference providers with explicit cost control and license awareness. use this when you need open-source model discovery, semantic embeddings, or chat inference backed by models like llama, qwen, mistral, or sentence-transformers, and you want to avoid vendor lock-in while keeping infrastructure costs predictable.

inputs

Required environment variable:

• HF_TOKEN (string, format hf_...): hugging face api token with inference permissions. acquire at https://huggingface.co/settings/tokens. never log or print this value; the mcp server will redact it automatically.

Optional environment variables:

• HF_HUB_BASE_URL (string): override the hub api endpoint (default: https://huggingface.co/api).
• HF_ROUTER_BASE_URL (string): override the inference router endpoint.
• HF_TIMEOUT_MS (integer): request timeout in milliseconds.
• HF_MAX_RETRIES (integer): number of automatic retries on transient failure (default: 3).
• LOG_LEVEL (string): verbosity for mcp server logs.

External connection:

• hugging face inference api (https://huggingface.co/inference) or compatible router. requires valid HF_TOKEN and sufficient account credits.

Context assumed:

• you have a hugging face account with at least read access to the hub.
• you understand openai chat completion message format (role, content).
• you know your cost tolerance for inference calls (billed per provider).

procedure

phase 1: discovery (free)

1. search for candidate models

   • input: task description (e.g. "text-generation", "embeddings"), optional author filter, optional sort (downloads, likes, recency).
   • tool: hf_search_models.
   • output: list of model ids, download counts, and metadata summaries.

2. inspect model details

   • input: exact model id (e.g. "meta-llama/llama-2-7b-hf").
   • tool: hf_model_info.
   • output: full model card including pipeline_tag, cardData.license, gated access status, and last update date.
   • decision: if model is gated or requires acceptance, you must visit the model page manually to accept terms before using it.

3. search for datasets (if needed)

   • input: dataset query, optional filters.
   • tool: hf_search_datasets.
   • output: dataset ids, descriptions, and download counts.

4. confirm inference support

   • input: (none; lists all available models).
   • tool: hf_list_inference_models.
   • output: array of model ids that are currently runnable on the inference router (this list changes as providers update).
   • decision: if your chosen model does not appear in this list, pick a model from the list or use hf_request to reach a custom endpoint.

phase 2: inference (billed)

5. run chat completion

   • prerequisite: model confirmed in hf_list_inference_models and HF_TOKEN is valid.
   • input: model id, messages array (openai format: [{"role": "user", "content": "..."}]), max_tokens (required; must be a positive integer), optional temperature (0.0 to 2.0), optional top_p (0.0 to 1.0).
   • tool: hf_chat.
   • output: single completion object with choices[0].message.content (string), usage.prompt_tokens, usage.completion_tokens, usage.total_tokens, and provider-specific metadata.
   • cost: billed by the provider per token used; check your account's billing settings.

6. generate embeddings

   • prerequisite: model is an embedding model (e.g. "sentence-transformers/all-MiniLM-L6-v2").
   • input: model id, inputs array of strings (batch multiple texts in one call; do not loop per item), optional instruction for some models.
   • tool: hf_embeddings.
   • output: array of embedding vectors (floats), one per input string, plus usage (if available from provider).
   • cost: billed per token or per call depending on provider; batching reduces per-item cost.

7. reach other hub endpoints (advanced)

   • input: custom endpoint path and method (get, post, etc.).
   • tool: hf_request.
   • output: raw json response from the hub or router.
   • decision: use only if the standard tools do not cover your use case.

phase 3: output and audit

8. report results
   • input: model id used, inference tool output (e.g. completion text, embedding vectors, usage stats).
   • output: structured response including model id, exact tokens consumed, and (for chat) the full completion.
   • outcome: user can verify the model choice and cost, and reuse the exact model id for reproducibility.

decision points

if model is not in hf_list_inference_models output:

• do not attempt to call hf_chat or hf_embeddings with that model id; you will receive a model_not_supported error (402 or 403).
• instead, pick a model from the list, or use hf_request to reach a custom inference provider with a compatible openai interface.

if hf_model_info shows the model is gated (requires license acceptance):

• manually visit the model page on huggingface.co, accept the terms, and confirm your token has access.
• do not proceed to inference until you have accepted the gate.

if inference call returns 401 (invalid or expired token):

• stop immediately and verify HF_TOKEN is set correctly and has not expired.
• do not retry the same call without fixing the token; retries will fail identically.

if inference call returns 402 (insufficient credits):

• stop. you cannot proceed without adding credits to your hugging face account.
• optionally, switch to a cheaper model or local inference.

if inference call returns 429 (rate limit exceeded):

• the mcp server will retry up to HF_MAX_RETRIES times with exponential backoff.
• if retries exhaust, slow down your request rate, batch calls, and cache deterministic outputs (e.g. embeddings for the same text).

if inference call times out (network latency or provider slowness):

• retry up to HF_MAX_RETRIES times (automatic via mcp server).
• if timeouts persist, check HF_TIMEOUT_MS and increase it, or switch to a faster model/provider.

if you need reproducibility (e.g. for rag or fine-tuning):

• always pin to an exact model id and optionally a git revision/commit hash (check hf_model_info for available revisions).
• do not rely on "latest" or floating tags.

if you need the same embedding space for indexing and querying:

• use the exact same model id for both indexing and query embedding calls. changing the model id will break semantic similarity.

output contract

successful discovery call output (e.g. hf_search_models):

• json array of objects with fields: model_id (string), downloads (integer), likes (integer), pipeline_tag (string), last_modified (iso 8601 timestamp).

successful model info output (hf_model_info):

• json object with fields: model_id, pipeline_tag, cardData.license (string or null), gated (boolean), last_modified, siblings (list of file metadata), downloads, likes.

successful inference call output (hf_chat):

• json object with structure:

  {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "<generated text>"
        },
        "finish_reason": "length" | "stop"
      }
    ],
    "usage": {
      "prompt_tokens": <integer>,
      "completion_tokens": <integer>,
      "total_tokens": <integer>
    }
  }
  

successful inference call output (hf_embeddings):

• json object with structure:

  {
    "data": [
      {
        "embedding": [<float>, <float>, ...],
        "index": <integer>
      },
      ...
    ],
    "model": "<model_id>",
    "usage": {
      "prompt_tokens": <integer>
    }
  }
  

error response:

• json object with fields: error (string message), error_type (e.g. "model_not_supported", "unauthorized"), http status code (401, 402, 403, 429, 500, etc.).

outcome signal

user knows the skill worked when:

1. discovery phase: hf_search_models returns a non-empty list of model ids matching your query, and hf_model_info successfully retrieves the license and task type for a chosen model.

2. verification phase: hf_list_inference_models includes your chosen model id in its output list, confirming it is runnable.

3. inference phase: hf_chat or hf_embeddings returns a successful response (http 200) with a completion string or embedding vectors, and includes usage showing token counts.

4. audit phase: you can reproduce the exact same result by calling the same tool with the same model id and inputs (deterministic for embeddings; non-deterministic for chat if temperature > 0).

5. cost visibility: the response includes usage.total_tokens so you can estimate provider cost.

failure signals:

• any http error (401, 402, 403, 429, 5xx) stops execution and surfaces the error message and type so you can decide whether to retry, fix credentials, add credits, or switch models.
• timeout or network error is retried automatically up to HF_MAX_RETRIES; if all retries fail, the error is reported and you must investigate connectivity or endpoint availability.

---

common mistakes to avoid

• calling hf_chat or hf_embeddings without first running hf_list_inference_models to confirm the model is supported. result: model_not_supported error and wasted credits if retried.
• embedding one text per call instead of batching multiple texts in a single inputs array. result: higher latency, higher cost, and rate limiting.
• omitting max_tokens from hf_chat calls. result: unbounded generation and runaway costs.
• skipping the license check. result: downstream legal or compliance issues.
• logging or printing the HF_TOKEN value (even if the server redacts it in output). result: potential token exposure in logs.
• hardcoding model ids without re-checking hf_list_inference_models periodically. result: model_not_supported when the provider stops serving that model.

agent checklist

• confirmed hugging face is the right tool (open-source model, discovery, embeddings, or openai-compatible inference needed).
• ran hf_search_models and hf_model_info to discover and inspect candidate model (free).
• ran hf_list_inference_models to confirm the chosen model is currently runnable.
• checked the model card for license and gated access status.
• for chat: set max_tokens to a positive integer.
• for embeddings: batched multiple inputs in a single call, not looped per item.
• verified HF_TOKEN is set and not exposed in logs.
• cited the exact model id in output and reported token usage for cost tracking.

example workflows

find a model and run chat:

1. hf_search_models with task="text-generation" and sort="downloads".
2. hf_model_info on the top result to check license and pipeline_tag.
3. hf_list_inference_models to confirm support.
4. hf_chat with the model id, messages, and max_tokens=256.
5. report the completion and token usage.

build embeddings for rag:

1. decide on an embedding model (e.g. "sentence-transformers/all-MiniLM-L6-v2").
2. hf_list_inference_models to confirm it is available.
3. hf_embeddings with a batch of document texts (e.g. 100 docs per call).
4. store the vectors in a vector db (pinecone, weaviate, etc.).
5. for queries, call hf_embeddings with the same model id on the query text.
6. retrieve top-k similar documents by vector distance.

discover a dataset:

1. hf_search_datasets with a query (e.g. "sentiment").
2. hf_request with endpoint="/datasets/{dataset_id}" to fetch full metadata.
3. manually visit the dataset page if you need to inspect samples or accept gated access.

---

credits: originally authored by simonpierreboucher02 on clawhub. enriched to implexa quality standards with explicit decision points, error handling, output contracts, and security guidance.