MCP and AI assistants

MCP lets an AI assistant read HCAPP data at your request: list tasks, analyze their fields, and summarize comments. You ask a question in natural language, and the assistant retrieves data through the HCAPP connection.

Pilot version

An administrator must enable MCP on the HCAPP server and register your AI application. Check availability before setting up the connection. This first version is read-only; compatibility with your particular AI client needs to be verified when connecting.

What you can do

• View the bot's available forms and permissions.
• List tasks in a form, filtered by dates, author, responsible user, and status.
• Read an individual task's fields and comments.
• Load additional pages of tasks and comments for analysis.

Creating, updating, or deleting tasks and posting comments through MCP are not available yet. The connection enforces this restriction even if the bot has broader permissions in the regular Bot API.

What you need

1. An AI application supporting remote MCP over Streamable HTTP and OAuth. The connection is not tied to one model or provider.
2. A connection for that application registered by the administrator. Registration is manual in this pilot; not every MCP client supports this setup method.
3. A separate HCAPP user with the BOT role and a valid Bot API token.
4. Read only access for the bot to the required forms.

See Users for creating a bot and issuing a token. Configure permissions in each form's Access tab.

The first version supports analytics for forms where the bot may read all tasks. Forms with restrictions on individual tasks are not accessible through MCP yet. Do not broaden access to confidential tasks just to enable the connection.

Connect HCAPP

1. Add a remote MCP server in your AI application's settings. Menu names vary between applications.

2. Enter the HCAPP address:

   https://api.hcapp.ee/mcp

   For a test server, use the address supplied by your administrator. The address above is for production and becomes available after MCP is enabled in that environment.

3. Select OAuth. For a published HCAPP plugin, the integration owner configures the Client ID and Client Secret once; users do not obtain or generate this secret. For a manually configured connection, the integration administrator sets these fields. Do not put your Bot token in them.

4. Start connecting. An HCAPP page opens and names the application requesting access.

5. Paste your Bot API token into the field on the HCAPP page and allow read access.

6. Return to your AI application, select the HCAPP connection, and ask it to show available forms.

Do not send your Bot token in a conversation with the assistant. OAuth connects the AI application to HCAPP: you authorize access with your Bot token, and the application receives a separate read-only credential.

The MCP connection lasts up to 8 hours. Reconnect when it expires. If the Bot token expires or is revoked sooner, access ends sooner.

Example requests

After connecting, try:

Show the HCAPP forms available for analytics.

Show tasks in the “Requests” form created during the last seven days.

Read task ID 123 and briefly summarize its comments.

Load the remaining comments on this task and prepare a timeline of the discussion.

Use names and IDs from your own company. For reports, specify a period and ask the assistant to state how many tasks it read and whether any pages remain.

Filters and loading data

Tasks can be filtered by creation date, the form's primary date, author, direct responsible user, and exact status. The responsible-user filter does not currently match group assignments. Specify a timezone for date ranges when it is not clear from your request.

Each request returns up to 50 records. Reading a task initially loads 20 comments; more can be loaded separately. One page is not a complete list: to report totals for an entire form, the assistant must read every matching page.

Task lists contain summaries. Task fields are retrieved separately. Comments may include attachment information, but MCP does not download file contents or include conversations from separate messaging channels.

Request limits

MCP and the Bot API share read quotas per bot: up to 300 task reads, 60 task-list requests, 60 form-list requests, and 60 comment-list requests per minute. Using another AI application or IP does not provide an additional quota. get_task consumes both the task-read and comment-list quotas.

MCP also limits total requests to 120 per minute per bot and 300 per IP, including protocol requests. Exceeding a limit returns 429 with a Retry-After header: wait for the specified delay before retrying.

How the assistant discovers HCAPP capabilities

Publishing this guide does not automatically connect HCAPP to AI applications. A user or administrator first adds the MCP address and authorizes access. The connected client then requests the server description and available tools; there is no need to upload the Bot API description manually.

Tool	Purpose
list_forms	The bot's forms and whether analytics can read them (analytics_read)
list_tasks	Filtered task lists and additional pages
get_task	Task fields and the first page of comments
list_comments	Read comments and load more pages

Access and disconnecting

Retrieved data is sent to your chosen AI application. Grant the bot access only to forms you intend to use with that application. The form list shows the bot's own permissions, not other users' access rules.

Permissions, bot activity, and token validity are checked on every MCP request. To stop access, revoke the Bot token, block the bot, or remove its access to the relevant form. This does not delete data already sent to the AI application.

If the connection fails:

• MCP address unavailable — ask the administrator whether MCP is enabled in this environment.
• OAuth or redirect URL error — the administrator needs to check the AI application's registration; replacing the Bot token will not resolve this error.
• Connection expired — reconnect with a valid Bot token.
• Form missing or unavailable for analytics — check bot permissions and restrictions on individual tasks.

Related topics

• External integrations
• Users and bots
• Form access
• Bot API authentication

Authorization page

The HCAPP page supports English and Russian, identifies the requesting application and explains the data it may read. Enter only a Bot API token issued in the same environment. A normal HCAPP password does not authorize MCP.

An invalid token can be corrected on the page. The bot must have at least one form available for analytics. Cancel returns to the application without granting access. If the connection link has expired, start again from the AI application.

Data shared with the assistant

The assistant receives the form, task and comment data it requests within the bot’s permissions. The original Bot token is not sent to the assistant; HCAPP issues a separate read-only credential. Revoking access stops future requests, but does not erase data already received by the AI provider. Check that provider’s data handling settings before connecting company data.

Support

Contact support@hcapp.ee with the environment, application name and error message. Never include tokens or client secrets. See the HCAPP privacy policy and terms.

Field filters

The assistant can discover field IDs, names, types and supported operators using list_form_fields, then pass field_filters to list_tasks. Conditions are combined with AND and applied in the database before pagination.

For “unpaid Speedtrans invoices”, it first searches the name field in the accessible counterparties form. It then uses the matching task ID in a linked_task_eq filter on the expense form's counterparty field, together with an amount/balance filter such as gt: 0. Ambiguous names require clarification. The assistant must identify the correct balance field and its meaning rather than assume every numeric field represents unpaid debt.

Text supports case-insensitive equality and literal substring matching. Numeric fields support comparisons. Date fields support comparisons with timezone-aware ISO timestamps; a date period is compared by its start. Existing creation-date and primary-date ranges remain available. Empty/not-empty filters are also supported. Table child columns and unsupported field types cannot be filtered in this version; the server returns an error instead of silently omitting a condition.

Linked form IDs are shown only when readable by the bot. Resolving a name requires access to that linked form. Refresh the AI client's tool list or reconnect after this server update.