$ cat hyperagent-mcp-report.md

Hyperagent MCP — Inter-Agent Communications

A Practical Guide to Intra- and Cross-Instance Agent Communication · June 26, 2026 · Status: Tested & Validated

Executive Summary

Hyperagent exposes a hosted Model Context Protocol (MCP) server that enables any MCP-compatible client — including other Hyperagent agents — to programmatically control your workspace: enumerate agents, start threads, send messages into live sessions, and retrieve results. This report documents what was built, tested, and learned in a live two-agent session, and what it means for autonomous agent-to-agent coordination.

1. MCP Server Tools

Hyperagent's MCP server runs at https://hyperagent.com/api/mcp and exposes six tools to any authenticated client:

Tool	What It Does
`list_agents`	Returns every agent in the workspace: id, name, description
`list_threads`	Returns threads newest-first, paginated (up to 100 per page)
`get_thread`	Reads a thread's messages and live running status; supports polling
`create_thread`	Starts a new background thread on any agent; returns immediately
`send_message`	Injects a user-turn message into any existing thread
`create_attachment_upload`	Uploads a file without passing bytes through context

Authentication

OAuth 2.0 Authorization Code + PKCE. No client secret exists by design — security comes from the PKCE code verifier. The resulting bearer token is workspace-scoped.

2. Intra-Instance Communication

Within a single Hyperagent workspace, any agent holding the workspace token can do all of the following:

Discover the full agent roster

list_agents returns every agent in the workspace. In testing: 23 agents. By contrast, Hyperagent's native delegation tools (ListSpawnableAgents, ListInvocableAgents) returned zero because no allowlists were configured. The MCP endpoint provides unfiltered workspace visibility that native tools do not.

Read any thread's history

list_threads + get_thread give complete read access to all threads — 1,281 threads in the test workspace, browsable by newest-first with cursor pagination. Any thread's full message history is readable.

Start new agent sessions

create_thread fired against any agent ID starts a new background thread, returns a threadId immediately. Caller polls get_thread until isRunning: false, then reads final messages. Proven async task-dispatch pattern — no live-mode required.

Inject messages into live sessions

send_message delivered a user-turn message into a currently active session, confirmed with {"queued":true}. The message arrived as a genuine user turn — indistinguishable from human input. An agent can send to its own session, another agent's session, or any thread in the workspace.

Key Finding — Token Portability

The bearer token is workspace-scoped, not agent-scoped. Any agent in the network that holds it can perform all of the above operations. Token security is a network-wide concern, not a per-agent one.

3. Inter-Instance Communication (Cross-Workspace)

Two agents in separate Hyperagent workspaces communicated bidirectionally using the MCP API.

The architecture

Each workspace has its own bearer token, issued through a separate OAuth flow
Workspace A's token cannot access Workspace B's threads — tokens are scoped to their issuing workspace
To send from A to B, Agent A uses Workspace B's token
Both tokens must be held by both agents for full bidirectional access

What was demonstrated

Agent in Workspace A sent a message into a thread in Workspace B using Workspace B's token
Agent in Workspace B confirmed receipt and processed the message
Agent in Workspace A read the response by polling get_thread using Workspace B's token
Full bidirectional message exchange completed between agents in separate workspaces

What cannot be done across workspaces

**What cannot be done across workspaces:** - Workspace A's token cannot `list_agents` in Workspace B — that call always returns the issuing workspace's agents. To see Workspace B's agents, an agent must use Workspace B's token. - Cross-workspace `list_threads` is similarly scoped — each token only sees its own workspace's threads. With Workspace B's token, an agent can read Workspace B's threads; with Workspace A's token, it can only see Workspace A's.

4. Timing & Polling

Component	Measured	Notes
`send_message` call	~108ms	HTTP round-trip; returns queued:true
Queue → recipient processes	Indeterminate	Depends on recipient's active state
Once active → response	5–15s	Agent inference time

The Waking Problem

send_message queues a user turn in the recipient's thread. It does not auto-trigger the recipient agent unless live-mode or an external poller is configured. Without waking, a message can sit in the queue indefinitely.

Live-Mode Assessment

Live-mode runs a scheduled heartbeat (minimum observed 30 min) using a lightweight model. It does appear to trigger on incoming message arrival — in testing, an agent began processing within 66 seconds of an MCP message being queued. However:

Live-Mode Not Viable for Production

Cost: ~$4/day per agent for heartbeats alone
Architectural mismatch: designed for external monitoring, not agent-to-agent messaging
Uncertainty: 66s trigger behavior may not be consistent

Polling Is Required

No push/webhook/SSE mechanism exists. The sender must poll get_thread to detect responses.

Correct Polling Implementation

Compare the ID or timestamp of the latest message, not the message count. Using messageLimit=N always returns N messages regardless of whether new messages were added — the count comparison will never change.

5. Security Implications & Token Management

Current risk model

A single workspace token grants complete read/write access to all agents, threads, and data in that workspace. There is no secondary authentication mechanism (such as a one-time code or session validator). Once a token is generated, it provides unrestricted access until revoked.

Token compromise cascade

Once a workspace token is shared — whether accidentally, through a compromised system, or intentionally — any holder can re-share it with others without the original issuer knowing or consenting. This creates a cascade risk: the token can propagate through multiple parties, each able to pass it on independently. Revocation is possible at hyperagent.com/settings/mcp-access, but re-sharing is not trackable.

MCP vs. Native Delegation

The MCP access model is broader and less granular than Hyperagent's native delegation tools:

Native delegation: ListSpawnableAgents respects allowlists; ListInvocableAgents respects approval gates
MCP: list_agents returns all agents; no allowlists, no approval gates

If you use MCP, you are opting into unfiltered workspace visibility.

Mitigation strategy

Compartmentalize: Do not store sensitive credentials, proprietary data, or critical automation logic in threads accessible via MCP
Token management: Treat workspace tokens like production credentials — store them securely, rotate them periodically, and minimize who holds them
Use for delegated work only: MCP is ideal for agent-to-agent task dispatch and coordination. If you need to control access to specific agents or threads, use Hyperagent's native delegation and approval tools instead
Monitor access: Audit which agents hold workspace tokens and what they're doing with them. Revoke connections at hyperagent.com/settings/mcp-access when no longer needed

6. Recommended Communication Patterns

Pattern 1 — Check at Turn Start

Zero cost. At the beginning of every work turn, each agent checks the other's thread for new messages before doing its primary work. Overhead: one get_thread call per turn. Effective for coordination where minute-level lag is acceptable.

Pattern 2 — Lightweight Scheduled Polling

Low cost. A cheap-model scheduled invocation (every 5–15 min) checks for new messages, processes if found, replies if needed. Uses Hyperagent's native scheduler or an external cron. Cost: a few cents/day. Maximum lag = polling interval.

Pattern 3 — Async Task Dispatch

Proven, no polling infrastructure. Agent A uses create_thread to start a background task on Agent B, polls get_thread until isRunning: false, reads result. Confirmed working in production — agent started a task on another's session, executed immediately without human intervention, reported completion. Recommended for discrete inter-agent work.

Agent A: create_thread(agentId: "B", prompt: "do X")  → threadId
         [poll get_thread(threadId) until isRunning == false]
         read final messages → result

Pattern 4 — Message Injection into Live Session

Useful when agents are already conversing and one needs to inject context or direction. Requires the target thread to be actively running or in live-mode.

Agent A: send_message(threadId: "active-thread", text: "context for agent")
Agent in "active-thread": receives message as user turn, processes, responds

Pattern 5 — Shared External Mailbox

Most durable. Both agents read/write to a shared external resource (e.g., an R2 bucket with known key structure). Agent checks mailbox at turn start or on schedule. Fully platform-agnostic, crash-recoverable, auditable. Best for high-reliability workflows.

7. Architecture Recommendations

For discrete inter-agent work (Bob-initiated):
Bob directs Agent A to delegate a task to Agent B. Agent A uses create_thread on Agent B, passes a self-contained task description, polls get_thread for completion, reports back. No continuous polling infrastructure — works within a single Bob-triggered turn.

For continuous background coordination:
A lightweight scheduled polling script (Pattern 2) checks both agents' threads at regular intervals. State (last-seen message ID) persisted in shared external storage. Cost-effective and controllable.

For Bob-triggered coordination sessions:
Bob opens a session with Agent A and instructs it to coordinate with Agent B on a specific task. Agent A handles the MCP communication (create_thread or send_message), does the polling loop within the session, and presents Agent B's results to Bob when complete.

Token management:

Each workspace's bearer token stored in a secure, persistent location accessible to all agents that need it
Token expiry is unknown — a daily health check (one list_agents call) that alerts on 401 is recommended
Token refresh requires a browser OAuth flow — build an alerting mechanism so token expiry doesn't silently break workflows

8. What This Enables for Agent Networks

The MCP API enables a multi-agent network to:

Delegate tasks cross-instance — one agent starts a thread on another and gets results asynchronously
Share workspace intelligence — the full agent roster and thread history of any connected workspace is readable by any agent holding that workspace's token
Inject context into live sessions — messages can be added to active agent threads for real-time coordination
Operate across organizational boundaries — different Hyperagent workspaces (different accounts, teams) can communicate if they each hold the other's token

Fundamental Constraint

The MCP API is a pull model — no push, no webhooks, no persistent connections. All coordination requires polling. The async task dispatch pattern (Pattern 3) is the cleanest fit: fire-and-forget, poll for completion, retrieve result.