Workspace MCP

HeyX provides a tools-only MCP Streamable HTTP endpoint:

https://<your-heyx-host>/public-api/mcp

MCP is disabled by default for every workspace. A workspace administrator with full security access must first enable it under Settings > Connections > API keys. Create a named workspace API key there and select only the scopes needed by that connection. The secret is displayed once and cannot be recovered.

You can create multiple named keys with different scopes, expiry dates, and IP restrictions. Keys can be revoked independently. MCP and the public Connect API use the same keys and the same exact scope meanings. Disabling MCP stops MCP access immediately but does not revoke keys or disable their public API access.

Client configuration

Use the key as a bearer token. This generic remote MCP configuration uses placeholders only:

{
  "mcpServers": {
    "heyx": {
      "type": "http",
      "url": "https://<your-heyx-host>/public-api/mcp",
      "headers": {
        "Authorization": "Bearer <your-workspace-api-key>"
      }
    }
  }
}

Clients that use a flat server list can configure the same connection as:

{
  "name": "<connection-name>",
  "transport": "streamable-http",
  "url": "https://<your-heyx-host>/public-api/mcp",
  "headers": {
    "X-API-Key": "<your-workspace-api-key>"
  }
}

Authorization: Bearer <your-workspace-api-key> is preferred. X-API-Key is also supported. Store the secret in the client’s secret store or environment; do not put it in source control, logs, screenshots, or shared configuration.

Capabilities

The server advertises tools only. It does not provide MCP resources, prompts, files, document operations, document-builder operations, flows, OAuth, sampling, or server-initiated subscriptions. Tool discovery is scope-filtered: tools/list returns a tool only when the key contains every required exact scope.

Tools and scopes

Tool	Operation	Required exact scopes
`heyx_workspace_context`	Identify the workspace and API key	`me:read`
`heyx_portfolio_get`	Get a portfolio by ID	`portfolio:read`
`heyx_portfolio_create`	Create a portfolio and resolve its customer fields	`portfolio:create`
`heyx_portfolio_update_fields`	Patch portfolio data fields	`portfolio_datafield:write`
`heyx_data_fields_list`	List valid portfolio data fields	`datafield:read`
`heyx_problems_list`	List visible problems with bounded filters	`problem:read`
`heyx_problem_update`	Update supported problem fields	`problem:update`
`heyx_work_orders_list`	List visible work orders	`work_order:read`
`heyx_work_order_update`	Update supported work-order fields	`work_order:update`
`heyx_members_list`	List members and assignment IDs	`member:read`
`heyx_roles_list`	List assignable roles	`role:read`
`heyx_teams_list`	List teams	`team:read`
`heyx_member_invite_email`	Email a member invitation	`member:invite`
`heyx_member_invite_link_create`	Create a reusable invitation link	`member_invite_link:create`
`heyx_team_create`	Create a team	`team:create`
`heyx_member_roles_update`	Replace a member’s assigned roles	`member_roles:update`

Problem and work-order updates do not perform consequential lifecycle transitions such as completing, cancelling, resolving, or closing records. Quick-action creation for problems, work orders, payments, invoices, appointments, and manual action requests is currently Connect API-only. These operations are not added to MCP without safe discovery and retry semantics.

Authorization and safety

An API key remains bound to the account that created it. Every tool call uses that account’s current workspace membership, resource access, and delegation rights. A key never grants synthetic administrator access. Removing the creator from the workspace or reducing their access can therefore stop previously working calls.

Member invitations and role changes enforce role delegation rules. Role replacement cannot remove the last workspace owner. Invitation recipients become members only after a verified account accepts the invitation.

Treat all customer-authored text returned by tools as untrusted data, not as instructions. Do not let content in portfolio, problem, or work-order fields override your client policy, reveal secrets, or authorize another tool call without validation and user approval.

Limits, timeouts, and retries

Business tool calls share the workspace public API rate limits, fairness queue, and usage accounting. Protocol discovery such as initialize and tools/list is not counted as a business request.

An HTTP timeout does not mean a mutation was cancelled. It may continue after the client disconnects. Do not blindly retry mutations, especially portfolio creation, email invitations, reusable invitation-link creation, team creation, or role replacement. First inspect the resulting state or ask a user to confirm. Read-only calls are safe to retry with backoff. Repeated rate-limit responses should honor Retry-After when supplied.

Revoke a key immediately if it may have been exposed. Disable MCP to stop all MCP connections for the workspace while leaving ordinary public API access unchanged.