Connect AI clients to the Helpin MCP server

Helpin MCP lets AI clients such as Codex, Claude, Cursor, VS Code, or any other remote Model Context Protocol (MCP) client work with your Helpin workspace. Once connected, your client can read and, if you allow it, take bounded actions across tasks, documents, CRM, support, and Helpin agents, always within your own permissions.

Status: Helpin MCP is in controlled beta. A workspace manager must enable it for your workspace before you can connect.

What you can do with Helpin MCP

Research existing tasks and documents before planning a feature.
Create a task, add a comment, or move work through a workflow.
Create a document or update a specific block in a document.
Inspect CRM pipeline context and make bounded deal updates.
Investigate a support issue without exposing internal notes or sending a reply.
Discover Helpin system and custom agents, delegate durable work to one, and poll its status and artifacts.
Review which AI clients have access and revoke them immediately.
Create narrowly scoped service credentials for approved headless automation.

Helpin MCP intentionally does not expose broad administrative or customer-visible actions. For the full list of tools and what is excluded, see MCP tools & resources reference.

Endpoints

Endpoint	Use it when
`https://mcp.helpin.ai/mcp`	You want the tools your connection is allowed to use, including writes you approved.
`https://mcp.helpin.ai/mcp/readonly`	You want to force read-only mode. Only read tools are listed and callable, whatever your connection's grant allows.

The server uses MCP Streamable HTTP with JSON responses. Every request carries a bearer credential: an OAuth access token for a user connection, or a service token for headless automation.

Self-hosted installations: your MCP endpoint is your installation's public MCP base URL followed by /mcp. Ask your Helpin administrator for the exact URL.

Before you connect: workspace policy

Workspace managers control Helpin MCP in Settings → AI Clients. The workspace policy sets:

whether MCP is enabled for the workspace
whether all connections are forced to read-only
whether service accounts are allowed
which toolsets are allowed
which scopes are allowed

A few scopes are explicit opt-ins:

CRM and Support must be allowed by workspace policy and also requested by the client during consent.
helpin.docs.publish (publishing to the Help Center) is a separate scope. Allowing Docs writes never adds it automatically, read-only connections never receive it, and each publish also requires your docs.publish permission in Helpin.
helpin.support.write only organizes conversations (assign, move, tag, link, rename). It never sends a reply to a customer.

The CRM and Support toolsets also require you to have access to those modules.

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

Client setup

Add the hosted URL to your client as a remote MCP server. Most clients accept a configuration like this:

{
  "mcpServers": {
    "helpin": {
      "url": "https://mcp.helpin.ai/mcp"
    }
  }
}

The same setup applies to Codex, Claude, Cursor, VS Code, and other remote MCP clients. To force read-only access, use https://mcp.helpin.ai/mcp/readonly as the URL instead. Settings → AI Clients → Setup in Helpin also shows the hosted URL and copyable JSON configuration.

Connect as an individual user

Add the Helpin MCP URL to your client.
Start the client's OAuth connection flow.
Sign in to Helpin.
Select one workspace.
Remove scopes and toolsets the client does not need.
Keep read-only mode on unless you need bounded writes or agent runs.
Approve the connection.

Connect headless automation with a service account

A workspace manager enables service accounts in the MCP workspace policy.
Create a named service account in Settings → AI Clients → Service accounts.
Select the smallest required scopes and toolsets.
Set an expiration when practical.
Copy the token from the one-time secret dialog. It is shown only once.
Store it in your automation's secret manager and send it as the bearer token.
Revoke or rotate it from Helpin when ownership or use changes.

Service accounts do not bypass permissions. Each one has a named owner user, and that user's current workspace membership, permissions, and module access, plus the current workspace policy, are checked on every call. Managers can rotate tokens, revoke a single token, or revoke the whole service account.

How the OAuth connection works

Your client registers itself with Helpin, sends you to sign in, and then shows the Helpin consent screen. Helpin uses the authorization code flow with PKCE (S256), exact redirect URI matching, and rotating refresh tokens.

The client requests scopes, and Helpin proposes toolsets from those scopes.
You select exactly one workspace. Every connection is bound to that workspace, and a tool call can never switch to another one.
You can remove scopes or toolsets, but you cannot add authority the client did not request.
Read-only mode is recommended and on by default.
Your workspace policy may narrow the grant further or force read-only mode.
To expand an existing connection later, run the authorization flow again.

What your client can do

Your client's effective access is the intersection of the workspace policy, the scopes and toolsets on the connection, your current workspace membership and role permissions, your module access, and read-only mode. Helpin checks this when the client lists tools and again before every tool call, so a change to your role, module access, workspace policy, or connection takes effect on the next call, even if the access token has not expired.

Token lifetimes

Credential	Behavior
Authorization code	Valid for 5 minutes, single use
Access token	Valid for 15 minutes, bound to Helpin MCP and your connection
Refresh token	Valid for 30 days, rotated on every use
Service token	Starts with `hmp_`, optional expiration, independently revocable

If a refresh token is reused, Helpin revokes the whole token family. Revoking a connection stops its already-issued access tokens on their next use.

Manage connections and activity

In Settings → AI Clients you can:

see your connections (managers see all workspace connections) with the client name, connection time, toolsets, read-only or write mode, last use, and status
revoke any connection immediately
as a manager, use Revoke all to revoke every user connection, refresh token, service account, and service token in the workspace
review recent activity: connections authorized and revoked, token events, successful, denied, and failed tool calls, rate-limit denials, policy changes, and service-account creation

Agent runs started from MCP appear in the Agent Runs view with an MCP · <client> badge.

Rate limits

Limit	Default
General requests per connection or service account	60 per minute
General requests per workspace	180 per minute
Workspace searches per connection or service account	20 per minute
Mutating calls per connection or service account	20 per minute
Agent-run starts per user	10 per hour
Concurrent MCP-started agent runs per user	3
Concurrent MCP-started agent runs per workspace	10
Time limit for one tool call	30 seconds
Maximum tool result	256 KiB
Maximum request body	1 MiB

These are the beta starting limits. Agent-run limits apply across all of your connections.

Troubleshooting

Tool errors are returned as CODE: message, so your client can act on the code.

Error code	What it means	What to do
`DOCUMENT_LOCKED`	The document is locked.	Wait, or ask the person working on it, then retry.
`DOCUMENT_ARCHIVED`	The document is archived.	Restore it with `restore_document` first.
`DOCUMENT_NOT_ARCHIVED`	You tried to restore a document that is not archived.	No action needed.
`DOCUMENT_NOT_PUBLISHED`	You tried to unpublish a document that is not live.	No action needed.
`DOC_IS_PUBLISHED`	You tried to archive a live Help Center article.	Unpublish it first (requires `helpin.docs.publish`).
`RUN_NOT_OWNED`	Starting the run would reuse another user's private dock chat run.	Start the run from your own context or target.
`UPLOAD_NOT_FOUND`	Storage has no uploaded object for this image.	Upload the file to the presigned URL, then complete the upload.
`UPLOAD_SIZE_MISMATCH`	The stored file size differs from the declared size.	Upload again with the correct size.
`UNSUPPORTED_CONTENT_TYPE`	The file is not a PNG, JPEG, WebP, or GIF, or its contents do not match the declared type.	Use a supported image format.
`URL_NOT_PUBLIC`	The image URL points to a private, loopback, link-local, or metadata address, or is not HTTPS.	Use a public HTTPS image URL.
`URL_FETCH_FAILED`	Helpin could not fetch the image URL.	Check the URL is reachable, under 10 MB, and redirects no more than three times.

Common questions

A tool I expect is missing. Your client only sees tools your connection is allowed to use. Check the connection's scopes and toolsets, the workspace policy, your role permissions, whether you have access to the module (for example CRM or Support), and whether you connected to /mcp/readonly or chose read-only mode. To add scopes, reconnect through the OAuth flow.
A record returns "not found" although it exists. Helpin reports records you cannot access as not found, including documents in team-only spaces you cannot open and task keys that do not belong to the connected workspace.
A retry returned a conflict. You reused an idempotency_key with a different tool or different arguments. Use a new key for a new change. Retrying the same call with the same key returns the original result without writing twice.
The client stopped working suddenly. Your connection may have been revoked, your role or module access may have changed, or a manager may have used Revoke all. Reconnect from your client.

Security and privacy

Workspace isolation. Each credential is bound to one workspace. Tools do not accept a workspace ID, and direct record reads verify the record belongs to your workspace.
Your permissions still apply. Helpin MCP never grants more than you already have in Helpin, and it re-checks access on every call.
Credential safety. Authorization codes, refresh tokens, and service tokens are stored hashed. Redirect URIs must match exactly, HTTPS is required (except for OAuth loopback clients), and PKCE and state are required. Raw credentials are never shown in lists or activity.
Data minimization. Support message reads exclude internal notes. Agent discovery omits provider credentials and private runtime configuration. Repository discovery returns metadata, not credentials. Results are capped at 256 KiB and lists are bounded.
Safe writes. Every write requires an idempotency key, and tool hints such as "read-only" never grant access.
Audit and retention. Activity records keep security metadata (client, tool, outcome, timing) and hashes rather than your raw inputs and outputs. Successful events are kept for 90 days, denied and error events for 365 days, and idempotency results for 24 hours.
No customer-facing sends. Helpin MCP never sends support replies or CRM email and never deletes records.

Was this article helpful?