Your AI tools, wired into HAL.

Endpoint & auth

POST https://api.chatwithhal.com/mcp
Authorization: Bearer <MCP key>     (or X-API-Key: <MCP key>)

Two kinds of MCP key work here, both under Settings → API and both separate from project API keys. The transport is stateless HTTP — no stdio, no local process.

Without a key, the endpoint answers only discovery (initialize, tools/list, ping), so MCP directories can check the server and list its tools; it is rate limited per IP. Every tools/call needs a key. The server card is at https://api.chatwithhal.com/.well-known/mcp/server-card.json.

• Account MCP key (hal_mcp_…) — full access to every project in the account and every tool. Only account owners and admins can generate it.
• Project MCP key (hal_mk_…) — works in one project and can only call the tools its permissions allow. Use one per bot or integration.

Project MCP keys and permissions

Give each agent a key for one project, with only the permissions it needs. Account owners and admins create project keys under Settings → API → Project MCP keys, pick a name and the permissions, and copy the key once: HAL stores only a hash and can't show it again. The list shows when each key was last used. Revoking a key stops it at once (requests get 401).

• conversations:read — list_conversations, get_conversation, get_conversation_image, list_macros, get_macro, list_message_tags, get_message_tags_stats.
• conversations:reply — reply_to_conversation, set_typing, tag_message, untag_message, update_conversation.
• articles:read — list_article_groups, list_articles, get_article, find_relevant_articles.
• articles:write — create_article_group, update_article_group, create_article, update_article.
• contacts:read — contacts, companies, CRM stages and deals (list and get tools, get_deal_pipeline).
• contacts:write — create and update contacts, companies and deals, link_contact_to_company, set_deal_contact, remove_deal_contact.

Write permissions don't include read; grant both when a bot needs both. Every project key can call list_projects, which returns only its own project. Project keys never get webhooks, broadcasts, email templates, campaigns, images or suppressions, sender domains, workflows, automations, guides, teams, statistics, imports, generate_ai_response_suggestion, merge_companies, delete_deal or list_test_email_recipients.

With a project key, project_id and project_slug are optional and default to the key's project. Naming any other project, or calling a tool the key doesn't allow, returns a tool error such as This key is limited to project SpacePost (…) and does not allow `create_webhook`. Disallowed tools are also left out of tools/list. Each project key has its own rate limit of 200 requests per minute.

Example client config

{
  "mcpServers": {
    "hal": {
      "type": "http",
      "url": "https://api.chatwithhal.com/mcp",
      "headers": { "X-API-Key": "YOUR_MCP_KEY" }
    }
  }
}

Always list projects first

The account key spans your account, so every project-scoped tool takes a project_id or project_slug. Call list_projects once, cache the slugs, and pass one on every subsequent call. For email features specifically, call get_email_capabilities_overview next — it explains campaigns vs. workflows vs. broadcasts, templates, sender domains, and the other choices before you start creating things.

What the endpoint can do

Tool map

• Conversations — get_conversation (messages + attachment metadata), get_conversation_image (native image content for private visitor attachments; >2MB images are resized ≤1600×1600), reply_to_conversation (optionally with up to 5 file attachments as base64), list_conversations (filter by status and by spam: spam: "exclude" hides spam like the inbox, "only" lists it for review), update_conversation (status, assignee, snooze, and is_spam: true does what Mark as spam does in the inbox, so the conversation leaves the inbox and the sender's next conversations go to spam; false undoes it; recorded in the conversation's activity as MCP).
• CRM — list_contacts, create_contact/update_contact, list_crm_stages, list_companies (filter by stage), list_companies_by_stage (read-only board with stage totals), get_company, create_company/update_company, link_contact_to_company.
• Deals — list_deals, get_deal (with history), get_deal_pipeline (stage totals, win rate, deals past their close date), create_deal/update_deal, set_deal_contact/remove_deal_contact, delete_deal. get_company and get_contact include their deals.
• AI — generate_ai_response_suggestion: HAL's draft for a conversation, built from your help content. Advisory only — it is stored as a non-sendable suggestion and never delivered to the visitor; your agent composes and sends its own reply via reply_to_conversation.
• Migration — import_conversation / import_conversations (up to 100 per call): silent imports with no webhooks, notifications, or AI side effects. Visitor matching order: email → user_id → external_id → create. 1–1000 messages per conversation, visitor / agent / system roles, internal notes supported.
• Visitor workflows — get_workflow_builder_reference (trigger shapes, graph rules, condition operators, email block types), list_workflows / get_workflow / create_workflow / update_workflow / delete_workflow, validate_workflow (checks a full graph without saving it), set_workflow_enabled, reorder_workflows, list_workflow_executions / get_workflow_execution.
• Lifecycle email — list_email_templates / create_email_template / update_email_template / delete_email_template, preview_email_template / validate_email_template, get_workflow_email_defaults / update_workflow_email_defaults (project-wide defaults for new send_email nodes). For simple linear campaigns there's also create_email_campaign / update_email_campaign / enable_email_campaign / disable_email_campaign / delete_email_campaign — a trigger → conditions → one email shape; branching workflows built with create_workflow report editable_as_campaign: false and must be edited with update_workflow instead. Image blocks need a hosted URL — upload_email_image (from base64 bytes or a source URL) / list_email_images / delete_email_image manage a per-project image library and return an email_url to use in image blocks. Blocks also include full-width section containers (background color, padding, an optional full-bleed hero that breaks out of the card's side padding, and color overrides for their children), list and quote blocks, and a theme that supports light/dark color pairs — call get_workflow_builder_reference for the full block/theme schema and a worked example_newsletter document.
• Broadcasts — one-off emails (same block design as lifecycle email) sent to an audience of contacts, now or scheduled. list_broadcasts / get_broadcast / create_broadcast / update_broadcast / delete_broadcast (accepts a category, default marketing), preview_broadcast_audience (count, suppressed count for that category, and a sample before you send), get_broadcast_audience_fields (builtin contact/company fields, sampled metadata keys, valid operators). schedule_broadcast / cancel_broadcast, list_broadcast_recipients for per-recipient delivery status. send_broadcast_now emails the real, live audience immediately — it requires confirm_recipient_count to exactly match the current preview_broadcast_audience count, so always preview and get explicit confirmation first.
• Email categories & suppression — list_email_categories / update_email_categories manage a project's unsubscribe categories (e.g. marketing, product updates, transactional); a category with unsubscribable: false always sends unless the address bounced or complained. list_email_suppressions, suppress_email_recipient, unsuppress_email_recipient, and get_email_unsubscribe_status all take an optional category (default all, meaning every category) so an address can opt out of just one category instead of everything.
• Test sends — send_test_workflow_email, send_test_email_template, send_test_email_campaign, and send_test_broadcast_email only deliver to addresses returned by list_test_email_recipients — users on your own account, never a visitor.
• Events — track_event tracks a lifecycle event exactly like the public track-event API and immediately fires matching enabled api_trigger workflows for real contacts, including real email sends. Pass dry_run: true to see which workflows would match without tracking anything or sending email; list_event_names shows event names already seen in a project.

Metadata, same rules everywhere

Contact and company writes accept the same flat metadata as the REST API — plain scalars, ≤ 50 keys, ≤ 10KB, replace-on-write. The limits live in CRM data model.

Boundaries that stay enforced

• Account scoping — tools only see the account the key belongs to.
• Project scoping — a project MCP key only reaches its own project and the tools its permissions allow, checked before every tool call and again where the tool loads the project.
• AI guardrails — the suggestion tool runs the same evidence, confidence, and injection checks as the dashboard.
• No silent sends — nothing reaches a visitor unless a tool explicitly calls reply_to_conversation.
• Test emails stay internal — send_test_workflow_email, send_test_email_template, and send_test_email_campaign reject any recipient that isn't a user on your account.
• track_event can trigger real email sends — always check dry_run results before calling it without dry_run against real contacts.

Ideas

• Point a coding agent at production support: "summarize this week's billing conversations and open an issue for the top bug."
• Migrate from another helpdesk with the import tools, then let an agent reconcile stage totals against the old system.
• Let an internal AI assistant answer "what's the status of Acme?" from live CRM state.