MCP clients
Connect Claude Code, Claude, Cursor, or another MCP client so it can start work with your Hyperagent agents.
An MCP client can start work with any agent you can reach
Connect the client to your Hyperagent account once. It can discover your available agents, start a thread, follow the work in the background, and read the result back where you asked.
The connection belongs to your account rather than one agent. There is no per-agent MCP switch to enable on Connections. Your client discovers the personal, shared, and workspace agents your account can currently reach.
This is inbound MCP: an external AI client starts work with Hyperagent. To give a Hyperagent agent tools from an external server, use Custom MCP.
Model Context Protocol is the standard the client uses to discover and call these Hyperagent tools. You configure one remote server connection rather than a separate integration for every agent.
How an MCP invocation works
Create a thread
The client calls create_thread with an agent and a
self-contained message. Hyperagent starts the work and immediately returns a
threadId.
Poll in the background
The agent continues after the tool call returns. The client polls
get_thread, checking both running and approval status before
treating the last message as a result.
Read or follow up
After the run finishes without a pending approval, read the last assistant
message for the result. Use
send_message to continue the same thread or open it in
Hyperagent.
The run is asynchronous. There is no single call that waits for the entire job and returns its final answer. Closing or disconnecting the client does not turn the thread into a hidden process; it remains a normal Hyperagent thread that appears in your thread list and in list_threads, ready to open or continue.
An MCP run acts with the same trust as a turn you send in Hyperagent
The OAuth connection belongs to you, so work started by the client acts with your existing access. Use the same care you would when sending the request from the Hyperagent app.
Connect your client
Every supported client points to https://hyperagent.com/api/mcp and completes OAuth in a browser. There is no API key for you to generate or paste.
Open MCP access settings
Switch to Personal workspace, then open Settings → MCP access. Copy the server URL from Connect an app.
Add Hyperagent to the client
Run:
claude mcp add --transport http hyperagent https://hyperagent.com/api/mcpLaunch Claude Code, run /mcp, select hyperagent, and
complete the browser sign-in.
Open Settings → Connectors → Add custom connector, name the connection, and enter the server URL. Connect and approve access in the browser.
Connecting from behind a VPN or firewall
The Claude web and desktop apps reach Hyperagent from Claude's servers, not your machine. If your instance sits behind a VPN or firewall, allow that traffic. Otherwise the connector signs in but can't open the session. Claude Code connects from your own machine and isn't affected.
Register the server, then sign in:
codex mcp add hyperagent --url https://hyperagent.com/api/mcp
codex mcp login hyperagentThe login command opens the browser for OAuth. Check the connection
with codex mcp list.
Add Hyperagent to ~/.cursor/mcp.json (or a project's
.cursor/mcp.json):
{
"mcpServers": {
"hyperagent": {
"url": "https://hyperagent.com/api/mcp"
}
}
}Then open Cursor Settings → MCP, find hyperagent, and complete the browser sign-in when it prompts.
Any other client that supports a remote HTTP MCP server with OAuth works the same way: give it the server URL and complete the browser sign-in.
Review and approve access
The consent screen lists the scopes the client requested. Approve them, and the client stores its connection and can reconnect without another manual setup.
Start with one agent
Ask the client to list your agents, choose one, and send a complete first request. Confirm the result comes back before relying on the connection in a longer workflow.
What your client can do
| Tool | What it does |
|---|---|
list_agents | Lists available agents with their ID, name, description, and execution mode. |
create_thread | Starts work on an agent and immediately returns a threadId. |
send_message | Sends a follow-up to an existing thread, immediately when idle or after the active turn. |
get_thread | Reads recent messages and reports running and pending-approval status. |
list_threads | Pages through your threads, newest first. |
create_attachment_upload | Creates a direct file upload and returns the fileId used with a message. |
list_pending_approvals | Lists actions and drafts waiting for your decision, most urgent first. |
get_pending_approval | Reads the full request and disclosure for a pending approval. |
get_approval_draft | Reads a pending draft and the exact write approval would perform. |
resolve_approval | Approves or denies one pending item that supports resolution over MCP. |
MCP doesn't directly manage agents or knowledge
The MCP server doesn't include tools for creating or configuring agents, skills, or memories. An agent with the right permissions can still do that work when you prompt it through MCP.
Ask-first agents can run over MCP
An agent set to Ask first can start through create_thread.
When it needs approval, the run pauses and waits for your decision. A paused
run is not a completed result.
Use list_pending_approvals to find the request. Read its full details
with get_pending_approval, or get_approval_draft for a
draft. Review the proposed action before deciding. When the item has
canResolve: true, use resolve_approval to approve or deny
it. Other requests must be answered in Hyperagent. After the decision, continue
following the thread with get_thread.
Start a run, then poll for the result
The single most important thing to know is that runs don't block your editor. create_thread returns a threadId the instant you call it, and the agent keeps working after the call ends. There is no synchronous "run and give me the answer" call.
To collect the result, poll get_thread and check both isRunning and awaitingApproval. If awaitingApproval is true, handle the pending request even if isRunning is still true. Read the last assistant message as the result only after both flags are false. If the agent asks a question, answer it with send_message and keep following the thread. It's a normal thread on your account, so you can also open it in Hyperagent to watch the full run or continue it there. Send a follow-up with send_message to keep the same thread going.
Manage access
Every client is its own connection, signed in through OAuth. You can see and revoke them all at Settings → MCP access: each connection lists its scopes and when it was last used, and revoking one cuts that client off immediately without touching the others. A connected client acts as you and reaches only what you already can, and it can't create or edit skills, memories, or agent configuration.
Attach a file without loading it into client context
Call create_attachment_upload with the file name, type, and exact size. Hyperagent returns a fileId and short-lived upload URL. Upload the bytes directly, then include the fileId in create_thread or send_message.
curl -T report.pdf -H "If-None-Match: *" "<uploadUrl>"The file moves to storage rather than through the client's model context or the MCP endpoint.
Access and security
Each client completes its own OAuth 2.1 connection and receives only the scopes approved on its consent screen. Hyperagent issues that client a bearer token prefixed hat_. The secret is delivered to the client once and is never shown for you to copy; Settings displays only the connection and token prefix.
| Scope | What it grants |
|---|---|
threads:read | Read your agents, threads, and messages |
threads:write | Create threads and send messages as you |
approvals:read | See pending actions and drafts |
approvals:write | Approve or deny pending items |
The client acts with your existing access
It can reach the same agents and threads you can, including shared resources already available to you. Connecting MCP does not grant new access elsewhere in the account.
Hyperagent supports up to 50 active client connections. Each appears in Settings → MCP access with its scopes, token prefix, and last-used time. Revoke cuts off that client immediately without affecting the others.