MCP tools & resources reference

This reference lists every tool, resource, and prompt that Helpin MCP exposes, with the scope and Helpin permission each one needs. To connect a client, see Connect AI clients to the Helpin MCP server.

Your client only sees the tools your connection can use right now. tools/list returns the subset allowed by your scopes and toolsets, the workspace policy, your role permissions, module access, and read-only mode. Helpin checks all of these again before every call.

Toolsets and scopes

Toolsets control which product areas are visible. Scopes control what you can do inside them.

Toolset	Read scope	Write or run scope	Notes
`context`	`helpin.context.read`	—	Workspace context, search, teams, members, repositories
`pm`	`helpin.pm.read`	`helpin.pm.write`	Requires the Projects module
`docs`	`helpin.docs.read`	`helpin.docs.write`, `helpin.docs.publish`	`helpin.docs.publish` is a separate opt-in for Help Center publishing
`crm`	`helpin.crm.read`	`helpin.crm.write`	Requires the CRM module and explicit workspace policy
`support`	`helpin.support.read`	`helpin.support.write`	Requires explicit workspace policy; write organizes conversations and never sends replies
`agents`	`helpin.agents.read`	`helpin.agents.run`	Discover agents and start or cancel durable runs

The recommended default grant is context, pm, docs, and agents with helpin.context.read, helpin.pm.read, helpin.docs.read, and helpin.agents.read, in read-only mode.

helpin.docs.publish is never added automatically when Docs writes are allowed, and read-only connections never receive it.

Conventions for all tools

Task keys

Any tool that takes task_id also accepts the task key shown in Helpin, such as HEL-120. The current workspace key and retired aliases both work. Keys that do not resolve in the connected workspace are reported as not found.

Idempotency keys on writes

Every tool that changes data requires an idempotency_key of 8 to 128 characters. The key is scoped to your connection or service account and kept for 24 hours.

Retrying the same call with the same key returns the stored result without writing again.
Reusing a key with a different tool or different arguments returns a conflict instead of writing.

Inputs

Every tool publishes a JSON Schema, and unknown properties are rejected.
You cannot pass a workspace ID. The workspace always comes from the connection.
String lengths and list sizes are bounded.
Each call must finish within 30 seconds.

Result envelope

Every successful result uses the same structure, delivered as both structured content and a text summary:

{
  "summary": "Human-readable result",
  "data": {},
  "links": {
    "workspace": "https://app.helpin.ai/..."
  }
}

Results are capped at 256 KiB.

Tools

In the tables below, Scope is the OAuth scope the connection needs, and Permission is the Helpin permission your role needs. Write tools also require an idempotency_key.

Context

Tool	Purpose	Scope	Permission
`get_current_context`	Returns the connected user or service identity, workspace, role, scopes, toolsets, modules, read-only state, and Helpin URL	`helpin.context.read`	Workspace read
`search_workspace`	Searches accessible tasks, planning objects, documents, members, CRM records, and support conversations with a bounded query	`helpin.context.read`	Search
`list_workspace_teams`	Lists teams in the connected workspace	`helpin.context.read`	Workspace read
`list_workspace_members`	Lists workspace members	`helpin.context.read`	Workspace members read
`list_repositories`	Lists connected repository metadata, without credentials	`helpin.context.read`	Integrations read

Projects

All Projects tools require the Projects module. Read tools need helpin.pm.read and PM read permission; write tools need helpin.pm.write and PM edit permission.

Tool	Mode	Purpose
`list_tasks`	Read	Lists bounded task records
`get_task`	Read	Loads one task
`get_task_context`	Read	Loads bounded task context; linked documents also need Docs read, and Git links need context read
`list_task_checklist`	Read	Lists up to 100 checklist items on a task
`list_task_comments`	Read	Lists a task's comments and replies; authors are returned by ID and name only
`list_epics` / `get_epic`	Read	Lists epics or loads one epic
`list_sprints` / `get_sprint` / `list_sprint_tasks`	Read	Lists sprints, loads one sprint, or lists its tasks
`list_objectives` / `get_objective`	Read	Lists objectives or loads one objective
`list_pm_labels`	Read	Lists task labels
`list_team_workflows_with_stages`	Read	Lists team workflows and their stages
`create_task`	Write	Creates a task
`create_task_batch`	Write	Creates up to 50 implementation-ready tasks in one epic
`update_task`	Write	Updates bounded task fields, without deleting, archiving, or moving the task between teams
`add_task_comment`	Write	Adds a comment with normal Helpin activity and notifications
`update_task_state`	Write	Moves a task through an allowed workflow transition
`set_task_dependencies`	Write	Creates validated, cycle-free dependencies between tasks
`create_task_checklist_item`	Write	Adds a checklist item
`update_task_checklist_item`	Write	Updates checklist text, completion, position, or due date, without deleting the item
`archive_task` / `restore_task`	Write	Archives a task so it leaves boards and lists, or restores it
`create_epic` / `update_epic`	Write	Creates or updates an epic
`create_sprint` / `update_sprint`	Write	Creates or updates a sprint
`create_objective` / `update_objective` / `update_key_result`	Write	Creates or updates objectives and key results
`ensure_task_label`	Write	Finds or creates a task label

Docs

All Docs tools require the Docs module. Read tools need helpin.docs.read and Docs read permission; write tools need helpin.docs.write and Docs edit permission. Publish tools need helpin.docs.publish and Docs publish permission. Every tool that takes a document_id also enforces space access, so documents in team-only spaces you cannot open are reported as not found.

Tool	Mode	Purpose
`list_spaces`	Read	Lists Docs spaces you can see, with IDs for creating collections and documents
`list_collections`	Read	Lists collections, optionally within one space
`search_icons`	Read	Searches the icon catalog before you assign an icon to a space, collection, or document
`search_documents`	Read	Searches documents
`list_documents`	Read	Lists bounded document metadata
`get_document`	Read	Loads one document record
`read_document`	Read	Reads document content, with a version for `edit_document`
`get_document_blocks`	Read	Returns addressable blocks for precise updates
`read_documents`	Read	Summarizes up to 50 documents in one call: status, word count, empty body, Help Center live state, and unpublished changes; inaccessible IDs are returned in `not_found`
`create_space`	Write	Creates an internal or external-capable space, without publishing content
`update_space`	Write	Updates space metadata, without changing its public URL or publishing state
`create_collection`	Write	Creates a top-level or nested collection
`update_collection`	Write	Updates or reparents a collection
`create_document`	Write	Creates a document
`update_document`	Write	Renames a document or updates its excerpt and tags
`move_document`	Write	Moves a document to another space or collection
`link_document_to_object`	Write	Links a document to an epic, task, support conversation, deal, contact, or company
`insert_document_block`	Write	Inserts new content between existing blocks without rewriting them
`update_document_block`	Write	Updates one specific block
`edit_document`	Write	Atomically applies up to 20 edits (replace text, replace or delete a block range, insert) against the version from a read; nothing is applied on conflict
`prepare_document_image_upload`	Write	Returns a presigned upload URL for a PNG, JPEG, WebP, or GIF image up to 20 MB
`complete_document_image_upload`	Write	Confirms the upload once storage reports the declared size, and returns markdown to insert
`upload_document_image_from_url`	Write	Copies a public HTTPS image up to 10 MB into Helpin and returns markdown to insert
`archive_document`	Write, destructive	Archives a document; refuses a live Help Center article with `DOC_IS_PUBLISHED`
`restore_document`	Write	Restores an archived document to draft
`publish_document`	Publish	Publishes a document; in an external-capable space it also becomes a live Help Center article
`unpublish_document`	Publish, destructive	Removes a live Help Center article and returns the document to draft

Images. Uploaded images stay private while the document is a draft. Publishing to the Help Center copies referenced images into the public version. Image URLs must be HTTPS and public: private, loopback, link-local, and metadata addresses are refused, including on redirects (at most three). File contents must match the declared image type.

Help Center

Tool	Mode	Purpose	Scope	Permission
`get_help_center_article`	Read	Shows live state, live slug, unpublished changes, social preview metadata, and reader feedback (helpful, not helpful, views)	`helpin.docs.read`	Docs read
`update_help_center_article_metadata`	Publish	Sets the social preview title, description, HTTPS image, and alt text; omitted fields are kept and `null` clears a field	`helpin.docs.publish`	Docs edit
`list_help_center_redirects`	Read	Lists redirects with search and pagination	`helpin.docs.read`	Docs admin
`create_help_center_redirect`	Publish	Redirects an old public path to a collection or article after merges or archives	`helpin.docs.publish`	Docs admin

CRM

All CRM tools require the CRM module and must be allowed by workspace policy. Read tools need helpin.crm.read and CRM read permission; write tools need helpin.crm.write and CRM edit permission.

Tool	Mode	Purpose
`list_contacts` / `get_crm_contact`	Read	Lists a minimized set of contacts, or loads one contact
`list_crm_companies` / `get_crm_company`	Read	Lists companies, or loads one company
`list_deals` / `get_crm_deal`	Read	Lists deals with core pipeline context, or loads one deal
`list_crm_pipelines`	Read	Lists pipelines and their stages
`list_crm_associations`	Read	Lists links between CRM records
`list_crm_signals`	Read	Lists CRM signals with their provenance
`create_crm_deal`	Write	Creates a deal for an existing company or contact
`update_crm_deal`	Write	Updates a deal
`update_deal_stage`	Write	Moves a deal to another stage using pipeline validation
`add_deal_note`	Write	Adds a note to a deal
`add_crm_activity`	Write	Logs an activity on a CRM record
`update_crm_contact` / `update_crm_company`	Write	Updates a contact or company
`link_crm_objects` / `unlink_crm_association`	Write	Links or unlinks CRM records
`set_primary_contact_company`	Write	Sets a contact's primary company

Support

All Support tools require the Support module and must be allowed by workspace policy. Read tools need helpin.support.read and Support read permission; write tools need helpin.support.write and Support edit permission. Write tools organize conversations only. They never send a reply.

Tool	Mode	Purpose
`list_support_conversations`	Read	Lists conversations with optional status and text filters
`get_support_conversation`	Read	Loads one conversation
`list_conversation_messages`	Read	Lists public messages; internal notes are excluded
`list_support_inboxes` / `list_support_tags` / `list_support_assignees`	Read	Lists inboxes, tags, or people you can assign
`assign_support_conversation`	Write	Assigns a conversation
`move_support_conversation`	Write	Moves a conversation to another inbox
`add_support_conversation_tag` / `remove_support_conversation_tag`	Write	Adds or removes a tag
`link_support_conversation_task`	Write	Links a conversation to a task
`link_support_conversation_contact`	Write	Links a conversation to a CRM contact
`update_support_conversation_subject`	Write	Renames a conversation

Agents

Tool	Mode	Purpose	Scope	Permission
`list_agents`	Read	Lists system and custom agents you can use, without provider credentials or private runtime configuration	`helpin.agents.read`	PM read
`start_agent_run`	Write	Starts one durable Helpin agent run for an explicit target and returns a run handle	`helpin.agents.run`	PM edit
`get_agent_run`	Read	Polls a run's status, output summary, artifacts, and links	`helpin.agents.read`	PM read
`cancel_agent_run`	Write, destructive	Requests cancellation of an active run	`helpin.agents.run`	PM edit

start_agent_run targets are workspace, task, epic, sprint, objective, document, crm_deal, crm_contact, and support_conversation. You can add up to 20,000 characters of additional_context.

Runs use the agent's saved configuration and appear in Helpin's Agent Runs view with an MCP · <client> badge. Completion is polling-based: call get_agent_run until the run finishes or needs input. A run never attaches to another user's private dock chat run; if it would, you get RUN_NOT_OWNED. Other users' dock chat runs are reported as not found.

Resources

Resources give addressable read access with the same authorization as the matching tool. A resource is available only when its backing tool is visible to your connection.

Resource	Returns the same as
`helpin://workspace/current-context`	`get_current_context`
`helpin://tasks/{task_id}`	`get_task`
`helpin://documents/{document_id}`	`get_document`
`helpin://crm/deals/{deal_id}`	`get_crm_deal`
`helpin://support/conversations/{conversation_id}`	`get_support_conversation`
`helpin://agent-runs/{run_id}`	`get_agent_run`

Prompts

Helpin MCP offers six workflow prompts. Each one is available only when the tools it needs are visible to your connection.

Prompt	What it does
`plan_feature`	Researches related Helpin work, drafts a feature plan, and creates approved documents and tasks
`prepare_release`	Reviews release evidence, blockers, docs gaps, and agent work, without deploying
`delegate_to_helpin_agent`	Selects an agent, starts one durable run, polls it, and reports artifacts
`triage_customer_issue`	Investigates a support issue and prepares product follow-up, without sending a reply
`docs_maintenance`	Finds stale documentation and makes narrow block-level updates; publishes or archives only on explicit request
`review_pipeline`	Reviews CRM pipeline evidence and makes only explicitly confirmed writes

Error codes

Errors are returned as CODE: message.

Code	Returned when
`DOCUMENT_LOCKED`	The document is locked
`DOCUMENT_ARCHIVED`	The document is archived
`DOCUMENT_NOT_ARCHIVED`	You restore a document that is not archived
`DOCUMENT_NOT_PUBLISHED`	You unpublish a document that is not live
`DOC_IS_PUBLISHED`	You archive a live Help Center article
`RUN_NOT_OWNED`	Starting a run would reuse another user's private dock chat run
`UPLOAD_NOT_FOUND`	No uploaded image object was found in storage
`UPLOAD_SIZE_MISMATCH`	The uploaded image size differs from the declared size
`UNSUPPORTED_CONTENT_TYPE`	The image is not PNG, JPEG, WebP, or GIF, or its contents do not match the declared type
`URL_NOT_PUBLIC`	The image URL is not a public HTTPS address
`URL_FETCH_FAILED`	The image URL could not be fetched

Records you cannot access, including task keys outside your workspace and documents in spaces you cannot open, are reported as not found. Reusing an idempotency_key with a different tool or arguments returns a conflict.

What is deliberately not exposed

Helpin MCP enforces these exclusions on the server. They are not just prompt instructions.

Deleting Helpin records (documents and tasks can be archived and restored instead)
Sending customer support replies or creating public reply drafts
Changing support conversation status
Publishing without the helpin.docs.publish scope and your Docs publish permission
Replacing a whole document's content in one call (use version-checked edit_document)
Applying unapproved document change proposals
Sending CRM email, and CRM enrichment, merge, or bulk changes
Member, role, workspace security, or billing administration
Installing integrations or managing their credentials
Raw Git, GitHub, storage, OAuth, or provider credentials
Local shell, filesystem, or unrestricted repository tools
Deployment actions
Completion webhooks (poll get_agent_run instead)

Was this article helpful?