MCP / A2A Tab

The MCP / A2A tab configures Model Context Protocol (MCP) integration and the Heym Agent's Agent2Agent (A2A) face. MCP lets AI clients (Claude, ChatGPT, Gemini, Cursor, and any MCP-compatible tool) call your Heym workflows as tools.

Heym supports two modes: a default server that exposes all MCP-enabled workflows under a single endpoint, and named servers that give each logical group of workflows its own dedicated URL and API key.

Both modes can expose two kinds of tools: individual workflows, and the Heym Agent, the whole Chat tab engine behind one heym_chat tool, which other agents can also reach over A2A.

Default MCP Server

The default server is always available at {origin}/api/mcp/sse. All workflows with MCP toggled on appear as tools here.

MCP API Key

• Keys are stored as SHA-256 digests, so Heym cannot show you an existing key. The tab reports whether one is set, not what it is.
• Generate / Regenerate – The new key is displayed once, right after you create it. Copy it then; reloading the tab hides it for good.
• Use this key when connecting Claude Desktop, Cursor, or other MCP clients to Heym
• Lost a key? Regenerate it. The previous key stops working immediately.

Connection Methods

• API Key – Use the MCP API key for programmatic connections. The tab can copy a ready-to-use JSON config and includes an Add to Cursor button for one-click Cursor setup.
• Claude – The tab shows the MCP server URL and setup steps for Claude. Leave OAuth Client ID and Secret blank; Claude registers automatically and authenticates via Heym OAuth.
• ChatGPT – The tab shows the MCP server URL and setup steps. In ChatGPT, open Plugins (chatgpt.com/plugins), select + and Add custom MCP server, paste the URL under Connection, choose OAuth, and select Create as a plugin; ChatGPT registers automatically. If Add custom MCP server is missing, turn on Developer mode under Settings → Security and login (a workspace admin may need to allow it).
• Gemini – The tab shows the MCP server URL and setup steps for a Gemini custom app: in gemini.google.com, Settings → Connected Apps → Add a custom app, paste the URL and leave Advanced features closed; Gemini registers automatically and authenticates via Heym OAuth. Once connected, Heym also works in the Gemini mobile app.

Workflow MCP Toggle

Each workflow can be exposed as an MCP tool:

• Enable – The workflow's tools become available to all clients connected to the default server
• Disable – The workflow is not exposed

Workflow cards show the description and a preview of input field names so you can see what each tool expects before enabling it.

Queued runs and heym_execution_status

A workflow with a concurrency limit may be busy when a client calls it. The call then returns at once with a result that is not an error:

{
  "status": "queued",
  "execution_id": "6f1c0c2e-...",
  "queue": { "position": 2, "size": 5, "running": 1, "limit": 1 },
  "next_step": "Call heym_execution_status with this execution_id every 5-10 seconds until status is success, error, cancelled or expired."
}

The client polls the heym_execution_status tool with that execution_id. It returns the same body as the status URL: queued with the current position, running, then success or error with the outputs. It only finds runs of workflows that the same server exposes. The tool is listed on the default server and on each named server only while at least one of its workflows has a concurrency limit. When the workflow's queue is full, the call returns an error, "Concurrency queue is full".

Memory tools: get_user_memory and set_user_memory

The default server always lists two more tools, with or without heym_chat, so any MCP client shares one memory with Heym's Chat and Heym Work. The memory is your User Rules.

• append adds one line.
• replace rewrites the whole text and only lands when revision matches the stored text. On conflict, the result carries the current text and revision to merge and retry.
• Text that looks like an API key, token, password or other credential is refused, and nothing is saved.
• Named servers do not list these tools. A workflow named get_user_memory or set_user_memory is not listed on the default server.

Heym Agent

The Heym Capabilities section turns the Chat tab engine into a single MCP tool named heym_chat. Enable it on the default server, on any named server, or on both — each surface keeps its own toggle and model selection.

When it is on, heym_chat appears in tools/list alongside your workflow tools. An MCP client sends one natural-language message and the Heym engine takes it from there, with the same abilities the Chat tab has:

• Build a workflow, test-run it with sample inputs, fix it, and finish when a run passes (see Build mode)
• Inspect and run your existing workflows
• Report analytics, recent executions, and upcoming cron schedules
• Explain where workflows fail and why they are slow: the workflows that ran most, failed most and are slowest, and the node types with the most time, errors and calls, over the last 1, 3 or 6 hours, 24 hours, 7 or 30 days, or all time
• Report the run history of one workflow: how many times it ran, status counts, when it ran, and on request the inputs, outputs, and per-node errors of a single run
• Report what is running right now: how many executions are active, their workflow names, how long each has been running, the node each is currently on, and a link to the live run
• List boards, create cards, and read card detail on the Board tab
• List your dashboards (Heym Work's pages) with the widgets on each, find which dashboard a workflow is on, add a new widget to a dashboard and build its workflow, put an existing workflow on a dashboard as a widget, rename or delete a widget, or tidy a dashboard's layout (see Dashboard › From Chat and MCP)
• Inspect data tables and rows, create tables, add or remove columns, insert, update or delete rows, and wire tables into workflows
• Create, edit and run prompt and agent eval suites, including an agent's baseline: reported, built from runs, or stated as numbers. The result lists the Evals link of every suite saved in the call.
• Create or update your credentials on Heym's own page (see Credentials)
• Read teams and global variables, and search the documentation
• Approve, edit, or refuse pending human-in-the-loop reviews

Capabilities added to the Chat tab later become available through heym_chat automatically — there is no per-capability toggle to keep in sync.

These capabilities run inside heym_chat: tools/list shows heym_chat and your workflow tools, never the chat's internal tools such as the eval suite ones. The memory tools are the one exception: heym_chat uses them too, and the default server also lists them on their own.

Build mode

heym_chat always runs the Chat engine in build mode, the same mode the Chat tab uses. In one call the assistant can save a new workflow, run it with realistic sample inputs, read the run report, fix what failed, and run it again, up to five test runs per call. When the latest run of the latest save passes, it finishes with a one-sentence summary, and the reply ends with Verified: the latest test run of the saved workflow passed.

When a call creates or edits a workflow, the reply lists each one with its full editor link, such as https://heym.example.com/workflows/<id>, and the links inside the assistant's answer are full links too. They use your configured Heym address (FRONTEND_URL) and open for people signed in to Heym who can access that workflow.

• Test runs are real runs. Their side effects happen, and they appear in the workflow's run history like any other run.
• Saves take the editor's path: a change to the graph keeps the previous graph in the workflow's Edit History.
• To change a workflow it built earlier, continue the thread with the same conversation_id. The assistant updates that workflow instead of creating a new one, and it only changes workflows you can edit.
• When the five test runs are used up, the assistant stops and explains what still fails.

heym_chat can inspect your tables and rows, create tables, add or remove columns, and insert, update or delete rows. Give it a table name, UUID or DataTable link, for example: “Add two string columns, name and surname, to https://heym.example/?tab=datatable/<table-id>.” It changes the table directly and preserves existing columns and values when adding columns.

Writes require ownership or write access through a direct or team share. Read-only access allows inspection. Row writes use the DataTable tab's type, default, required and unique checks; partial imports report rejected rows. Removing columns deletes their values from every row. As in the DataTable tab, column removal and clearing all rows ask for confirmation first; reply with the same conversation_id to confirm. Deleting a selected row needs no extra confirmation.

Credentials

heym_chat sees the credentials you own and the ones shared with you, by name and type, the same way the Chat tab does. When a workflow it builds needs a credential, it asks which one to use, as a question in the result. Answer it with the same conversation_id.

To add a credential, or to update one you own, the assistant opens Heym's credential form on a Heym page, /credentials/setup/<id>. You sign in to Heym there, enter the key or connect the account, and press save. The value goes straight to Heym: the MCP client and its model only learn the credential's name and type. Do not paste keys into the MCP client; ask for the form instead.

How the page reaches you depends on the client:

The page only opens for the Heym account that started the request, so a forwarded link is useless to anyone else. A form stays open for 24 hours, and you can decline it from the page. Once you save or decline it, the step in the Chat tab conversation shows the result.

Credential and model

heym_chat runs the engine on your Heym account, so it needs an LLM credential of its own:

If either is missing, the tool still appears in tools/list but each call returns an error telling you to finish the setup in this tab.

LLM and Agent nodes in a workflow heym_chat builds run on this credential and model, including a credential someone shared with you, so test runs work without another setup step. When heym_chat edits a workflow, LLM and Agent nodes that already have a credential keep it, along with their model.

Arguments and history

Every call is written to your Chat tab history as a normal conversation, marked with a plug icon in the conversation list. Messages, tool cards, and clarification pauses look exactly like a conversation you started yourself, and you can open the thread and keep talking in the browser. Each result returns its conversation_id so the MCP client can continue the same thread instead of opening a new one on every call.

When the assistant needs clarification, it pauses and says so; reply with the answers using the same conversation_id.

Enable A2A

While the Heym Agent is on, the card shows an Enable A2A checkbox. Tick it and other agents can send the Heym Agent tasks over the Agent2Agent protocol (A2A 1.0). The card then lists the Agent Card URL and the JSON-RPC endpoint, each with a copy button, and a curl that fetches the card. A2A uses the same key and OAuth sign-in as MCP. Turning the agent off turns A2A off too. See A2A for the methods, task states and an example.

Progress

A long heym_chat call reports what the agent is doing as MCP progress (notifications/progress), in the words the Chat tab shows, for example Testing the workflow · attempt 2/5. Clients that reset their timeout on progress keep waiting while the agent works.

Named MCP Servers

Named servers let you segment workflows into isolated MCP endpoints. Each server has its own URL and API key, so different AI clients, teams, or use cases can connect to exactly the workflows they need.

Creating a Named Server

1. Type a name in the input field at the bottom of the MCP tab (e.g. CRM Tools)
2. Click Create — a new server card appears immediately
3. Click the card to expand it

Per-Server Settings

Each server card shows:

Workflow Assignment

Workflow assignment is per-server and independent of the default server toggle. A workflow can be enabled on the default server and on multiple named servers simultaneously, or on none.

Toggling a workflow moves it to the top of the assigned list, so the row you just changed stays visible instead of scrolling away.

Authentication

Named servers support the same authentication methods as the default server:

• X-MCP-Key header – Pass the server's API key directly (API clients, Cursor). Header only: keys are not accepted as a ?key= query parameter, because URLs end up in access logs, proxy logs and browser history.
• Claude, ChatGPT and Gemini OAuth – Add the server URL to the client's connectors, plugins or custom apps; leave credentials blank and the client registers via OAuth automatically. The bearer token must travel in the Authorization header, not as ?token=.
• Session token – Issued during the SSE handshake; scoped to the specific server so tokens from one named server cannot access another. This short-lived ?session= parameter is unaffected.

Deleting a Named Server

Click the X icon on a server card header. Deletion removes the server and all its workflow assignments; workflows themselves are not affected.

SSE Endpoint

Both endpoints support the SSE transport (GET, MCP spec 2024-11-05) and Streamable HTTP transport (POST, MCP spec 2025-03-26). Claude, ChatGPT and Gemini use OAuth 2.1 / PKCE for secure sign-in on both.

Related

• Why Heym – MCP as a first-class primitive in Heym
• Agent Node – Agent node with MCP tool support
• Agent Architecture – MCP client, tool dispatch, orchestrator
• Triggers – MCP as a workflow entry point
• Chat Tab – The engine behind the heym_chat tool
• A2A – The Heym Agent over the Agent2Agent protocol
• Workflows Tab – Create and manage workflows
• Node Types – AI nodes overview
• Contextual Showcase – Compact page guide for dashboard surfaces