Extend agents with integrations

HQ agents gain new capabilities from three kinds of integration: MCP servers (tool backends), skills (instruction packs), and Slack channels (where the HQ bot can post). Each is installed once at the workspace level and then attached to individual agents. All requests use the base URL https://api.hq.zone and a personal access token: Authorization: Bearer hq_pat_.... Most install and uninstall operations require the admin scope; the catalog and status reads require agents:read.

Installing an MCP server or skill makes it available to the workspace. To put it in front of a specific agent, attach it with the agent’s MCP/skill subset — see Attach skills and MCP servers.

Check connection status

Before browsing the catalogs, you can fetch a single overview of what the workspace has connected. See Connection status.

curl https://api.hq.zone/v1/api/connect/status \
  -H "Authorization: Bearer $HQ_TOKEN"
# → {
#   "slack": { "connected": true, "team_name": "Acme" },
#   "teams": { "connected": false, "org_name": null },
#   "extension": { "web_store_url": null, "download_url": null },
#   "recommendations": [ ... ],
#   "detected": [ ... ]
# }

The slack and teams objects report whether each is connected (with the team or org name when available). extension carries the browser-extension URLs (null until published). recommendations lists suggested or accepted integrations/skills enriched with catalog display_name, description, category, icon_url, confidence, priority, and rationale; detected lists the technology signals the profiler found about your org’s site and DNS. This read requires the agents:read scope.

MCP servers

MCP servers expose tools your agents can call. Some are one-click toggles; others need a credential before they will work.

Browse the catalog

List every active MCP server together with your workspace’s install state. See MCP catalog.

curl https://api.hq.zone/v1/mcp/catalog \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "servers": [ { "slug": "github", "display_name": "GitHub",
#       "credential_model": "tenant_api_key", "effective_enabled": false,
#       "allowed_scopes": ["team","user"], ... } ] }

Each server reports slug, display_name, description, category, publisher, transport, trust_tier, version, default_enabled, credential_model, tenant_enabled, effective_enabled, install_status, allowed_scopes, featured, featured_rank, and icon_url. This read requires the admin scope.The credential_model drives how you install:

none / platform — a one-click toggle; no credential needed.
tenant_api_key — paste an API key (see Install with an API key below).
tenant_oauth — connect through OAuth, then install with the resulting credential reference.

Fetch a server’s brand icon (public, no auth) from MCP icon:

curl https://api.hq.zone/v1/mcp/catalog/<SLUG>/icon
# → image/svg+xml (404 when the server has no icon)

Install (no credential)

For none and platform servers, install by slug. See Install MCP.

curl -X POST https://api.hq.zone/v1/mcp/installs \
  -H "Authorization: Bearer $HQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"slug": "<SLUG>"}'
# → { "slug": "<SLUG>", "enabled": true }

The body accepts slug, an optional credential_ref (for tenant_api_key / tenant_oauth servers), and an optional config blob. Re-installing is idempotent and preserves the prior credential_ref and config when you omit them.

Installing a tenant_api_key or tenant_oauth server without a credential_ref returns 400. An unknown or inactive slug returns 404.

Install with an API key (tenant_api_key servers)

For servers whose credential_model is tenant_api_key, store the key and install in one call. See Set MCP key.

curl -X POST https://api.hq.zone/v1/mcp/installs/<SLUG>/api_key \
  -H "Authorization: Bearer $HQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"api_key": "<TOKEN>", "scope": "team"}'
# → { "slug": "<SLUG>", "enabled": true,
#     "credential_ref": "<UUID>", "scope": "team" }

The body takes api_key and an optional scope: team (shared across the workspace, the default) or user (private to you). The chosen scope must be in the server’s allowed_scopes, and user scope requires a resolvable calling user. The key is sealed and, where the backend supports it, validated against the upstream before being saved. Pasting a new key for an existing install rotates the credential in place.

An empty key, a server whose credential_model is not tenant_api_key, a disallowed scope, or a failed validation probe returns 400. An unknown or inactive slug returns 404.

Attach it to an agent

Installing only makes the server available to the workspace. To equip an agent, replace its MCP subset with the slugs you want — an empty list means “everything installed.” See Attach skills and MCP servers.

curl -X PUT https://api.hq.zone/v1/agents/<AGENT_ID>/mcp \
  -H "Authorization: Bearer $HQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"enabled": ["<SLUG>"]}'

Uninstall

Disable the server for your workspace. See Uninstall MCP.

curl -X DELETE https://api.hq.zone/v1/mcp/installs/<SLUG> \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "slug": "<SLUG>", "enabled": false }

This works even for servers that are enabled by default with no prior install (it records an explicit opt-out). It also clears any stored tenant credential, so a later re-install of a credentialed server must supply a fresh one.

For the OAuth dance that produces a credential_ref for tenant_oauth servers, see the OAuth guide.

Skills

Skills are instruction packs that shape how agents work. The catalog mixes platform skills with any your workspace has authored.

Browse the catalog

List every active skill with your workspace’s install state. See Skills catalog.

curl https://api.hq.zone/v1/skills/catalog \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "skills": [ { "slug": "research", "display_name": "Research",
#       "profile": "claude-sdk", "locked": false,
#       "required_integrations": [ { "slug": "web", "display_name": "Web Search", "met": true } ],
#       "effective_enabled": true, ... } ] }

Each skill reports slug, display_name, description, category, publisher, profile, version, default_enabled, trust_tier, locked, requires, required_integrations (each with slug, display_name, and whether it is met), tenant_enabled, effective_enabled, install_status, featured, featured_rank, and icon_url. A locked skill is system-required and always on. This read requires the agents:read scope.Inspect a skill’s full pack — its SKILL.md (listed first) and any other files — with Skill content:

curl https://api.hq.zone/v1/skills/catalog/<SLUG>/content \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "slug": "<SLUG>", "display_name": "...", "profile": "claude-sdk",
#     "trust_tier": "...", "editable": false,
#     "files": [ { "path": "SKILL.md", "content": "...", "is_external": false } ] }

editable is true only for your own workspace-authored skills. Large external files are listed with empty content. Fetch a skill icon (public, no auth) from Skill icon.

Install

Enable a skill for your workspace by slug. See Install skill.

curl -X POST https://api.hq.zone/v1/skills/installs \
  -H "Authorization: Bearer $HQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"slug": "<SLUG>"}'
# → { "slug": "<SLUG>", "enabled": true }

The body accepts slug and an optional config blob. Re-installing is idempotent and preserves the prior config when omitted.

System-locked skills cannot be installed this way (they are always on) and return 400; an unknown or inactive slug returns 404. Requires the admin scope.

Author a workspace skill (upload)

Create a skill from your own content. See Upload skill. The body is either inline markdown or a multi-file pack.

# Inline markdown — wrapped automatically as SKILL.md
curl -X POST https://api.hq.zone/v1/skills/upload \
  -H "Authorization: Bearer $HQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"kind": "markdown", "name": "Release Notes Style",
       "description": "How we write release notes",
       "body_markdown": "# Release Notes\n..."}'
# → 201 { "slug": "t:<TENANT>:release-notes-style", "version": "0.1.0" }

# Multi-file pack — each file is base64-encoded; must include SKILL.md at the root
curl -X POST https://api.hq.zone/v1/skills/upload \
  -H "Authorization: Bearer $HQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"kind": "files", "name": "Release Notes Style",
       "files": [ { "path": "SKILL.md", "content_base64": "<BASE64>" } ]}'
# → 201 { "slug": "t:<TENANT>:release-notes-style", "version": "0.1.0" }

Fields: name (3–60 chars; letters, digits, spaces, hyphens, underscores — used to derive the slug), optional description, optional profile (claude-sdk, hermes, or openai-agents; defaults to claude-sdk), optional provides (a capability slot such as app-design), and the body discriminated by kind (markdown with body_markdown, or files with a list of { "path", "content_base64" }). Re-uploading with the same derived slug updates the skill in place.

Limits: up to 50 files, 256 KiB total raw content, 64 KiB markdown, and a 1 MB request body. Exceeding them — or a pack with no SKILL.md at the root — returns 400. Requires the admin scope.

Attach it to an agent

Replace the agent’s skill subset with the slugs you want — an empty list means “everything installed.” See Attach skills and MCP servers.

curl -X PUT https://api.hq.zone/v1/agents/<AGENT_ID>/skills \
  -H "Authorization: Bearer $HQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"enabled": ["<SLUG>"]}'

Uninstall or delete

Disable a skill for your workspace (opting out even of a default-enabled one). See Uninstall skill.

curl -X DELETE https://api.hq.zone/v1/skills/installs/<SLUG> \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "slug": "<SLUG>", "enabled": false }

System-locked skills cannot be disabled (they return 400). To remove a workspace-authored skill permanently — including its install records — use Delete skill:

curl -X DELETE https://api.hq.zone/v1/skills/t:<TENANT>:<NAME> \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "slug": "t:<TENANT>:<NAME>", "deleted": true }

Only your own workspace-authored (T3) skills may be deleted; deleting a platform skill or another workspace’s skill returns 403, and an unknown slug returns 404. Both operations require the admin scope.

Slack channels

Once Slack is connected, the HQ bot can post to channels it is a member of (for example, from a scheduled run). These endpoints let you see and grow that membership.

See where HQ can post

List the channels the HQ bot already belongs to — the set it can deliver to. See List Slack channels.

curl https://api.hq.zone/v1/api/slack/channels \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "connected": true,
#     "channels": [ { "id": "C0123ABCD", "name": "general", "is_private": false } ] }

Each channel has id, name, and is_private. When connected is false, the workspace has no active Slack install and channels is empty — connect Slack first. This read requires the agents:read scope.

Find channels HQ can join

List the public channels HQ is not yet in but can self-join. See List joinable channels.

curl https://api.hq.zone/v1/api/slack/channels/joinable \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "connected": true,
#     "channels": [ { "id": "C09XYZ", "name": "announcements", "is_private": false } ] }

Private channels are intentionally excluded — Slack forbids a bot from self-joining them, so a member must run /invite @HQ instead. Requires the admin scope.

Join a channel

Self-join HQ to a public channel by id. See Join Slack channel.

curl -X POST https://api.hq.zone/v1/api/slack/channels/<CHANNEL_ID>/join \
  -H "Authorization: Bearer $HQ_TOKEN"
# → { "joined": true,
#     "channel": { "id": "<CHANNEL_ID>", "name": "announcements", "is_private": false } }

Joining is idempotent on Slack’s side. If the workspace has no live Slack install, or Slack refuses the join, the call returns 400. Requires the admin scope.

To connect Slack in the first place, see the Connection status read and the OAuth guide.

​Check connection status

​MCP servers

​Skills

​Slack channels

Check connection status

MCP servers

Skills

Slack channels