Connect an AI assistant with MCP

Activity Messenger supports Model Context Protocol (MCP), which lets a compatible external AI client discover and use your organization's permitted AM actions. You can look up information, work with reports, prepare changes and continue supported tasks in AM. Changes that require approval still need your review in Activity Messenger.

Before connecting

You need:

A remote MCP client that supports Streamable HTTP and a custom Bearer token.
An active, confirmed AM user with permission to use the assistant in the organization.
An MCP token issued by an authorized operator for that user and organization.

AM hosts MCP within its existing application. You do not need to install a separate MCP server. Clients that require OAuth discovery and consent cannot connect to this Bearer-token integration yet.

Deploying MCP does not create a token or connect a client automatically. Ask an authorized operator for the appropriate scope:

Read-only: supported information lookups without conversation or change-workflow tools.
Full catalogue: all currently permitted catalogue actions and their conversation, preparation, review and workspace tools. The operator must issue this token with --allow-changes.

A full-catalogue token does not grant additional AM roles. The user's current organization and module permissions remain authoritative. Existing read-only tokens are not automatically upgraded.

Configure the connection

Add a remote MCP server in your compatible client.
Select Streamable HTTP and enter this server URL, replacing the organization placeholder with the ID associated with your token:
```
https://activitymessenger.com/api/mcp/organization/<organization-id>
```
Store the issued secret in the client's protected Bearer authorization setting. If the client uses a custom header, use Authorization: Bearer <mcp-token>.
Connect and let the client initialize MCP and discover its tools. Clients managing headers directly should send Content-Type: application/json and accept application/json, text/event-stream.

Never include the secret in the URL or paste it into an ordinary conversation. Each connection is scoped to one organization and user. Use a separate connection for another organization.

Tokens are valid for 1–90 days, with 30 days by default. The secret is displayed once when issued. An authorized operator can revoke a token; expiry or revocation also prevents its pending native approvals and execution from continuing.

Discover what the client can do

The client discovers tools using tools/list. It must follow nextCursor until there are no more pages; the first page alone is not the complete list. Pages contain 15 tools by default and up to 50 when requested.

With a full-catalogue token, use discover_application_actions to find actions and get_application_action to inspect the selected action's exact inputs. The available tools depend on the user's current permissions.

“Full catalogue” means all currently registered and permitted actions, including tasks performed through native AM editors. Several actions may share one MCP tool. It does not mean every AM feature has a dedicated server-side change tool, or that editor tasks can finish without AM open.

Browse the complete action and tool catalogue for registered capabilities grouped by module, including tool names, required inputs, credential scope and review requirements.

Prepare and review a change

A typical workflow is:

The client calls start_mcp_session with your request. AM returns conversation and run IDs, an am_url review link and an upload URL.
The client discovers the intended action, checks its input contract and prepares the proposal using the native preparation tool or prepare_application_action.
The client calls apply_assistant_draft for the prepared proposal. This requests human review; it does not approve or apply the change by itself.
Open am_url and sign in to AM as the user associated with the token. Review the actual proposal and approve or reject it there.
The client checks get_mcp_session for the current state and completion receipt. A queued or pending response is not evidence that the change completed.

For example, when creating a class and then its reminder, review the class first. After creation completes, the client uses the actual returned record IDs to prepare the reminder for its own review.

The token cannot approve its own proposal and does not sign the browser in. Each MCP conversation belongs to the exact token, user and organization; a different token for the same user cannot reuse it.

An active external turn blocks another native chat turn. Use close_mcp_turn to finish an idle external turn, then begin_mcp_turn for the next request. Active approvals and running tools must finish through their own workflow.

Editor tasks, files and reports

Some catalogue actions hand off to AM's native browser workspace through request_application_task. Open the returned AM link and keep the page open. A browser_required response means the task needs this handoff, not that it has completed. Current permissions and native confirmation rules still apply.

For files, the client uploads the actual file to the returned upload_url, using the same Bearer token and multipart field file. Supported types are JPG/JPEG/PNG/GIF/WebP, PDF and XLS/XLSX, up to 10 MiB per file. Uploads are private and conversation-bound. Attach the returned file token to the next message using begin_mcp_turn; upload alone does not attach or use the file. Remote URLs and server paths are not file inputs.

Reports can return stored result IDs for later chart inputs. Large contextual results provide a tool_result_id; the client can retrieve them with read_mcp_result and follow next_offset without rerunning the action.

Troubleshooting

Some tools are missing: finish tool-list pagination, check the token's scope and confirm the user's current module permissions. Conversation and action-discovery tools require a full-catalogue token.
The connection returns HTTP 401: check the secret, organization ID, expiry/revocation and whether the user remains active and confirmed. HTTP 403 can indicate permissions, a disallowed browser origin or a connection without HTTPS.
A proposal stays pending: open its AM link, sign in as the token's user and review it. Continue checking the conversation until the native work completes.
A browser task waits: keep the AM review page open so its native workspace can operate.
A request is interrupted: contextual calls use an am_call_id. Retry with the same ID and identical arguments. Do not invent a new ID to bypass an uncertain change. Replayed calls preserve their original stored result; check the conversation for later decisions and receipts.
A result is too large: narrow the native filters or pagination, or read the stored result when an ID is returned. Standalone oversized reads do not have a stored conversation result.

JSON requests are limited to 64 KiB for read-only tokens and 2 MiB for full-catalogue tokens. MCP permits 60 requests per minute per IP and, by default, per token; uploads have an additional 20-per-minute IP limit. HTTP 429 includes Retry-After. Dates follow the native action's organization-timezone rules.