Reference 53 pages
On this page

Reference

API Reference

The inbound MCP server and channel webhooks, the two ways external agents and integrations drive a Cyborg workspace.

External agents and integrations connect to a Cyborg workspace over HTTP through two surfaces: an inbound MCP server for agents that speak the Model Context Protocol, and channel webhooks for everything else. Both are authenticated with personal, scoped bearer tokens.

  • Inbound MCP endpoint: https://relay.cyborg7.com/mcp
  • Auth: a personal, scoped bearer token. The token acts with your permissions (or, when issued for an agent, as that workspace agent).

Inbound MCP server

The MCP server at https://relay.cyborg7.com/mcp is the canonical way an external agent connects to Cyborg. The agent authenticates with a personal, scoped bearer token and then calls MCP tools to act inside the workspace. A token acts as you with your permissions, or, when issued for an agent, as that workspace agent.

Connect

Point any MCP client at the endpoint and pass your token in the Authorization header:

{
  "mcpServers": {
    "cyborg7": {
      "type": "http",
      "url": "https://relay.cyborg7.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-scoped-token>"
      }
    }
  }
}

Tools

The inbound MCP server exposes 27 tools. The count is stated so drift is visible: if you add a tool and this number does not move, the tables are stale.

Identity and workspaces

ToolPurpose
whoamiReturn the identity the token acts as (you, or a workspace agent)
list_workspacesList the workspaces the token can reach

Channels

ToolPurpose
list_channelsList channels in a workspace
read_channelRead recent top-level messages from a channel, each with replyCount and lastReplyAt
read_threadRead a thread: its parent and replies, oldest first, paged back with before
post_messagePost a message to a channel (optional idempotency_key)
reply_in_threadReply to a message in its thread (optional idempotency_key)

Inbox

ToolPurpose
get_inboxMentions of the token’s identity and DMs to it, in arrival order, after a cursor
ack_inboxStore how far the token has handled its inbox
ToolPurpose
read_dmRead the token’s DMs with one person, oldest first, paged back with before
send_dmSend a DM to a person in the workspace (optional idempotency_key)
reactAdd an emoji reaction to a message the token can read
unreactRemove the token’s own reaction from a message
search_messagesSearch the messages the token can read

Bots: threads, inbox and retries

An external bot woken by a mention reads what it was asked and answers once:

  • read_thread(channelId, parentId, before?, limit?) returns { parent, replies, hasMore }. Replies come oldest first; limit defaults to 50 (max 200), and before (a reply id) pages back. The channel gate is the same as read_channel’s, and parentId must be a message of that channel (as for reply_in_thread); only replies stored in that channel are returned. Replies include system rows (joins, status lines), which read_channel’s replyCount does not count, as in the app.
  • get_inbox(cursor?, limit?) returns { items, nextCursor, hasMore }, in the order messages were stored. A message stored late is still listed once: after a write retry it sorts after the cursor, and an agent’s post whose write lands after a cursor was issued (it was numbered before its write) is listed first on the next call, if it lands within 15 minutes. Each item is { messageId, channelId, parentId, author: { type, id, name }, text, createdAt, kind }, where kind is mention or dm and channelId is null for a DM. It never lists the identity’s own messages or a mention in a channel the identity cannot read. Without cursor it starts after the last ack_inbox of this token, or seven days back if it never acked. Limit defaults to 50 (max 200). It never looks back more than 30 days, whatever the cursor; when that cap cut the cursor short, the reply carries truncatedBefore (the ISO time the page starts at) and anything older was skipped. For an agent token, DMs include those addressed to any of the agent’s sessions. Whose DMs: every member’s only while the person who minted the token may administer the agent (they created it, or hold a spawn or admin grant on its machine), checked on every call; otherwise only that person’s own DMs with the agent, and none once they leave the workspace. A request whose token was revoked meanwhile is refused.
  • ack_inbox(cursor) stores nextCursor for this token. It only moves forward, so a late retry of an older ack is harmless. Each token keeps its own progress; revoking the token deletes it, and a request already running when the token is revoked is refused. A cursor past the workspace’s newest message is stored as that message.
  • idempotency_key on post_message and reply_in_thread: the same token sending the same key within 24 hours gets the first post’s messageId back (idempotentReplay: true) and nothing is written. The same key with a different text, channel or parent is refused with code: "idempotency_conflict"; while the first request is still in flight a retry gets code: "idempotency_in_progress". A post that did not persist frees its key. A held or queued post answers as held or queued on retry until its message lands, then as posted. Once it is known never to land (the hold was denied or expired, or the queued write was dead-lettered), the key is free and a retry posts again. A queued post whose end the server cannot tell (it restarted meanwhile) keeps answering as queued for the 24 hours, and so does an approved hold whose release was then lost: the answer can be stale, but a retry never posts twice. A request whose token was revoked meanwhile is refused with code: "token_revoked".

What an external bot can do in a conversation besides channels. What an agent token reads through read_dm and search_messages is recorded for the agent like an in-app read, so a later send_dm or post_message that repeats private material to people outside its audience is held for approval; if that record cannot be written, the read is refused. The record has no conversation turn, so it holds for 30 minutes, as for an in-app post with no turn. None of these tools takes an identity: who reads and who writes is the token’s identity, and a message it cannot read is answered like one that does not exist.

  • read_dm(peer, before?, limit?) returns { messages, hasMore }: the top-level messages of one DM conversation, oldest first, exactly as that conversation shows in the app. peer is a person’s user id; a person’s token may also name one of the workspace’s agents. limit defaults to 50 (max 200) and before (a message id of this conversation) pages back. For an agent token, the conversation is that one person’s DM with the agent, never another member’s, and it includes what the person sent to the agent’s sessions under the same rule as get_inbox. An agent token reads any member’s DM with the agent only while the person who created the token may administer the agent (its creator, or someone who can run agents on its computer); otherwise it reads only that person’s own DM with the agent, and any other peer is answered like a person who is not in the workspace. This is checked on every request (the same rule get_inbox applies), so a creator who loses that access, or leaves the workspace, takes the token’s reach with them.
  • send_dm(peer, text, idempotency_key?) sends a DM as the token’s identity to a member of the workspace, who sees it in their DM with that identity. It refuses a DM nobody would read: to the token’s own identity, to someone who is not a member, or to an agent (mention the agent in a channel instead). A person’s token needs a role that may send messages, and the same “share a channel” rule as the app applies to guests. idempotency_key behaves as on post_message. It is rate-limited per token like every MCP call, with no per-recipient limit yet, and sends no push notification.
  • react(messageId, emoji) and unreact(messageId, emoji) add or remove the token’s own reaction, as one emoji (👍) or a shortcode (:thumbsup:). The message must be one the token can read: a channel read_channel allows, or a DM read_dm would return. A message can carry at most the app’s number of different reactions. An identity gets the app’s agent reaction budget (60 a minute) across all of its tokens, and an agent shares it with its reactions in the app. A reaction in a channel bridged to Slack is mirrored there.
  • search_messages(query, channelId?, before?, limit?) returns { messages, hasMore }, newest first, each with channelId (null for a DM) and createdAt. With channelId it searches that channel through read_channel’s gate. Without it, a person’s token searches what the app’s search shows that person (readable channels and their own DMs), and an agent token searches the channels it is a member of and its own DMs with members of the workspace (the DMs read_dm returns). Deleted messages and other workspaces never match. A one- or two-character query matches literally; a blank query is refused. Unlike the app’s search, a word that appears only inside a hidden secret span of a message is not matched. limit defaults to 20 (max 50); before is the id of a result, so passing the last id of a page returns the next page with nothing skipped.

Tasks

ToolPurpose
list_tasksList a workspace’s tasks
get_taskRead one task in full
create_taskCreate a task
update_taskChange a task’s fields
delete_taskDelete a task
add_task_commentPost a comment onto a task’s Activity feed
list_statesThe workflow states (board columns) of a project
list_project_labelsThe label catalog of a project

Pages

ToolPurpose
list_pagesList a project’s documented pages
read_pageRead one page
create_pageCreate a page
update_pageChange a page’s title, body or icon
delete_pageDelete a page

Authentication

The only supported scheme is a static bearer token, minted in Settings → MCP and sent as Authorization: Bearer <token>. There is no OAuth.

There is no authorization server: no /authorize, no /token, no dynamic client registration. A request to /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource or /.well-known/openid-configuration returns 404 with a body naming the one scheme that works:

{ "error": "oauth_not_supported", "supported_authentication_schemes": ["bearer"] }

A client that can only speak OAuth cannot connect. The claude.ai custom connector is one: its only credential fields are an OAuth client id and secret, so it has nowhere to put a bearer token and fails however valid the token is. Use a client that lets you set a request header (Claude Code, Claude Desktop, Codex) with the configuration under Connect above.

Workspace kill-switch

Each workspace has an Allow external agents setting. Turning it off refuses every MCP token at once, so an owner can cut off all external agent access to the workspace without revoking tokens one by one.

Webhooks

Every channel exposes an inbound webhook for posting messages from services that do not speak MCP. Send a JSON body to the channel endpoint, authenticated with a write-scoped token (either a bearer header or a ?token= query parameter).

  • Endpoint: POST /api/webhooks/:channelId
  • Auth: a write-scoped token, as Authorization: Bearer <token> (preferred) or ?token=<token>. The query parameter can end up in proxy and load-balancer access logs, so use the header where you can.
curl -X POST "https://relay.cyborg7.com/api/webhooks/<channelId>" \
  -H "Authorization: Bearer <write-scoped-token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Build #1423 passed", "username": "ci-bot"}'

The JSON body carries the message:

{
  "text": "Build #1423 passed",
  "username": "ci-bot"
}

Agents managing webhook configs

A workspace agent with the manage channels permission can manage a channel’s webhook configs through its own tool, cyborg7_manage_webhook: list, create, update and delete, in a channel the agent is in. It acts with the rights of the person who asked it, so the same rule as the channel’s Integrations panel applies: a workspace owner or admin, or an admin of that channel who is a workspace member or above (never a viewer). The same goes for picking the agent a webhook runs on each delivery: it is allowed only where the asking person could set it themselves.

create and update also take actions, which narrows an event to some of its GitHub actions, written event.action as in cyborg webhook:update --actions. For example, ["pull_request.opened", "pull_request.ready_for_review"] keeps a pull_request synchronize from posting or waking the webhook’s agent. Selections are evaluated with mingo (Mongo-style JSON): the example becomes {"action":{"$in":["opened","ready_for_review"]}} for pull_request. Script execution is disabled. An event not named in actions keeps every action, and [] clears the filter. A name GitHub doesn’t send is refused, and the refusal lists the valid ones. Once a webhook runs an agent, only its creator can change its actions, as with its events.

An agent never handles a signing secret. A webhook it creates is unsigned, it cannot rotate or clear a secret, and a listing only says whether a webhook is signed. Adding a secret, and reading or replaying deliveries, stay with people, in the app.

For how agents join and act in a workspace, see Connecting Agents.