Skip to main content
Glama
AskMarcel

AskMarcel

Official
by askmarcel

AskMarcel is a remote, hosted MCP server (Streamable HTTP). There is nothing to install or self-host — point your MCP client at the endpoint and authenticate. The server connects AI agents to real manufacturer documentation so answers cite the exact manual and page number instead of hallucinating — or abstain when the source is missing.

Breaking change (November 2026). The server went from 15 tools to 7, and REST moved to /v2. The old tool names (diagnose, diagnose_v2, diagnose_guided, search_technical_docs, get_error_code, get_procedure, get_product_sheet, get_pdf_page_snapshot, resolve_model, get_model_coverage, get_diagnostic_summary) are removed, with no alias. See the migration table and the changelog.


Marcel Inside — branch it behind your bot

Use AskMarcel as Marcel Inside: plug manufacturer-sourced HVAC knowledge behind your existing chatbot, voicebot, or agent — without rebuilding your stack. Compatible with ManyChat, ElevenLabs, Voiceflow, Intercom, Claude, ChatGPT, Gemini, and custom MCP clients.


Related MCP server: CHARM

Why AskMarcel

General-purpose LLMs guess at HVAC specifics — refrigerant charge, error-code meanings, wiring, fault trees. AskMarcel grounds every response in indexed manufacturer PDFs and returns the source page, so a field technician or an agent can trust and verify the answer. See HVAC-Bench for the published benchmark.

  • 126 brands · 900+ models · 400,000+ error codes indexed

  • Deterministic error-code lookup (not a guess), tied to an exact equipment — no family substitution

  • Abstention when no exact manual exists, and an emergency stop when a danger is reported (CO, gas, high voltage…): no search, no handling instructions

  • Cited sources: a provenance_token per hit gives the full procedure or the exact PDF page

  • Tracked diagnostic sessions (Beta) — hypotheses, discriminating next action, technician journal

  • FR / EN, focused on the European HVAC/RACH market

Two uses, one contract

Use

Tools

Access units

Documentary lookup (read): what does the manufacturer say for this equipment and this code?

resolve_equipment, lookup_fault, get_source

lookup_fault: 1 unit, only when a source is actually served. Everything else: 0

Tracked intervention (session, Beta): hypotheses, actions, measurements, repair, verification

start_diagnostic, respond_to_diagnostic, get_diagnostic, close_diagnostic

A session quota, consumed once at creation

A lookup does not diagnose. A session consumes the evidence, it does not replace it. Every lookup answer carries a next step towards the session.


Tools

The server exposes 7 tools. Full reference in docs/tools.md.

GA — documentary lookup (3)

Tool

What it does

resolve_equipment

Resolve brand + model to an exact equipment (exact or alias, never a range). Optional error_code / market add the documentary coverage. Free.

lookup_fault

Sourced lookup from an error code or symptom. Status: found, no_exact_source, model_ambiguous, equipment_required, emergency.

get_source

Full procedure by provenance_token, or the cited PDF page (view: "page", signed 5-minute URL). Free. The token is the capability: no bare chunk_id or document_id.

Beta — diagnostic session (4)

Tool

What it does

start_diagnostic

Open a tracked session (equipment resolution, manufacturer fault lookup, hypotheses, first safe action). request_id required.

respond_to_diagnostic

Append a typed observation, measurement or technician assessment.

get_diagnostic

Read or resume a session. include: "summary" returns the deterministic summary.

close_diagnostic

Close the session (terminal).

Annotations are honest: the three lookup tools and get_diagnostic are readOnlyHint: true; session writes are not; close_diagnostic is destructiveHint: true. All tools set openWorldHint: false (closed corpus). Unknown input fields are rejected (strict schemas).

Stability: beta · release_channel: beta on session responses · qualified HVAC professional required.


Quick start

1. Get an API key

Create a free key at https://app.askmarcel.app/developers. The server also supports OAuth 2.0 (PKCE + Dynamic Client Registration) for clients that discover auth automatically. Session tools need the diagnostics.* scopes (see authentication).

2. Connect your MCP client

Ready-to-use configs live in examples/. The general form for any Streamable HTTP MCP client:

{
  "mcpServers": {
    "askmarcel": {
      "type": "streamable-http",
      "url": "https://mcp.askmarcel.app",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop / Cursor / VS Code: see the matching file in examples/. Replace YOUR_API_KEY with your key.

3. Ask a question

"Daikin Altherma showing error U4 — what does it mean and how do I clear it?"

The agent calls resolve_equipment, then lookup_fault, and returns the cause, the steps and the source manual page — or an explicit abstention when no exact manual exists. If the user reports a danger, the answer is the emergency message and nothing else.

For a full field loop on a heat pump, use start_diagnostic → respond_to_diagnostic → close_diagnostic (see skill hvac-harnais-session).


MCP vs REST vs Chat API

Surface

Endpoint

Protocol

Use case

MCP server (this repo)

https://mcp.askmarcel.app

JSON-RPC Streamable HTTP (tools/call)

Connect Claude, Cursor, VS Code, or any MCP client

REST v2

https://api.askmarcel.app/v2

JSON over HTTPS

POST /v2/lookups, POST /v2/equipment/resolve, GET /v2/sources/{token}, /v2/diagnostic-sessions. OpenAPI: /v2/openapi.json

Chat API (web / mobile / extension)

https://app.askmarcel.app/api/chat

AI SDK v5 SSE

Full conversational UI — not for MCP clients

The MCP server does not use the AI SDK chat stream. If you build a custom agent with the Vercel AI SDK, use MCP tools via JSON-RPC — not the web chat endpoint. The /v1/* REST routes are gone.


Authentication

Two supported methods (details in docs/authentication.md):

  1. API key (Bearer): Authorization: Bearer YOUR_API_KEY

  2. OAuth 2.0: discovery via https://mcp.askmarcel.app/.well-known/oauth-protected-resource

Scopes: docs.read (lookup, equipment, sources), diagnostics.read, diagnostics.write.


Claude Skills

The skills/ folder contains ready-to-use Agent Skills that wrap these tools into HVAC workflows:

  • hvac-error-lookup — brand + error code → sourced explanation (resolve_equipment, lookup_fault, get_source).

  • hvac-diagnostic — symptom lookup with citations and the emergency stop (lookup_fault).

  • hvac-harnais-session — Beta session loop (start_diagnostic … close_diagnostic).


REST API SDK

For custom agents that call the REST API directly (not MCP), use the npm package @askmarcel/sdk or the Python client generated from the OpenAPI — both target /v2 (lookups, equipment resolution, sources, diagnostic sessions).



License

Code and content in this repository (documentation, examples, skills) are released under the MIT License. The AskMarcel hosted service and its underlying data are proprietary and governed by the AskMarcel terms.


🇫🇷 En français

AskMarcel est un serveur MCP distant et hébergé (Streamable HTTP) qui connecte les agents IA à la documentation technique HVAC/RACH sourcée constructeur. Rien à installer : on pointe son client MCP sur l'endpoint et on s'authentifie. Chaque réponse cite le manuel et la page exacte — ou s'abstient quand la source manque.

  • Endpoint : https://mcp.askmarcel.app

  • Nom registre : io.github.askmarcel/mcphvac

  • Manifeste : 1.3.0-beta.1 — 7 outils en production (3 GA + 4 session Beta)

  • Doc & clé API : https://app.askmarcel.app/developers

  • Marcel Inside (B2B) : https://askmarcel.app/fr/connecteurs

  • Tier Developer gratuit : 50 appels / mois

  • Couverture : 126 marques · 900+ modèles · 400 000+ codes erreur indexés

Changement cassant (novembre 2026). 15 outils → 7, REST passe en /v2. Les anciens noms sont supprimés, sans alias : table de migration dans docs/tools.md.

Deux usages, un contrat. Lookup documentaire (lecture) : resolve_equipment, lookup_fault, get_source. Intervention suivie (session Beta) : start_diagnostic, respond_to_diagnostic, get_diagnostic, close_diagnostic. Le lookup ne diagnostique pas ; la session consomme la preuve, elle ne la remplace pas.

Unités d'accès. Seul lookup_fault consomme, 1 unité, quand une source est réellement servie. Abstention, urgence, équipement manquant, résolution et sources : 0. La session a son propre quota, consommé à la création.

Urgence et abstention. Un danger signalé (CO, gaz, haute tension…) renvoie emergency : aucune recherche, aucune consigne de manipulation. Sans manuel exact : no_exact_source ou model_ambiguous.

Skills : lookup code erreur, lookup symptôme, session Beta — voir skills/.

SDK REST : @askmarcel/sdk (npm) et client Python généré depuis l'OpenAPI, sur /v2.

Connexion rapide : créez une clé sur https://app.askmarcel.app/developers, puis utilisez une des configs du dossier examples/. Remplacez YOUR_API_KEY par votre clé.

MCP vs Chat API : ce dépôt documente le serveur MCP (JSON-RPC sur mcp.askmarcel.app). Le chat web/mobile utilise une API distincte (SSE AI SDK v5 sur /api/chat) — les deux protocoles ne sont pas interchangeables.

Détails des outils : docs/tools.md · Authentification : docs/authentication.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents with instant, structured access to electronic component datasheets, pinouts, and electrical specifications without requiring PDF uploads. It enables seamless part searching, design validation, and side-by-side component comparisons across major hardware providers.
      14
      76 npm
      12
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents with authoritative OEM automotive repair data including part numbers, torque specs, fluid capacities, and service procedures for vehicles 1982-2013 across 80+ makes, sourced from factory service manuals.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables users to resolve HVAC model and nameplate references, search OEM documents for fault codes and specifications, and receive written answers with page-level citations for Carrier, Trane, and Lennox equipment.
      5
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to query a verified bilingual technical knowledge base for the Thermia Duo 12 heat pump and verify facts against original manuals via section search, terminal and register lookup, schematic access, and PDF page rendering or text extraction.
      10
      MIT