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
| Tool | Purpose |
|---|---|
whoami | Return the identity the token acts as (you, or a workspace agent) |
list_workspaces | List the workspaces the token can reach |
Channels
| Tool | Purpose |
|---|---|
list_channels | List channels in a workspace |
read_channel | Read recent top-level messages from a channel, each with replyCount and lastReplyAt |
read_thread | Read a thread: its parent and replies, oldest first, paged back with before |
post_message | Post a message to a channel (optional idempotency_key) |
reply_in_thread | Reply to a message in its thread (optional idempotency_key) |
Inbox
| Tool | Purpose |
|---|---|
get_inbox | Mentions of the token’s identity and DMs to it, in arrival order, after a cursor |
ack_inbox | Store how far the token has handled its inbox |
Direct messages, reactions and search
| Tool | Purpose |
|---|---|
read_dm | Read the token’s DMs with one person, oldest first, paged back with before |
send_dm | Send a DM to a person in the workspace (optional idempotency_key) |
react | Add an emoji reaction to a message the token can read |
unreact | Remove the token’s own reaction from a message |
search_messages | Search 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;limitdefaults to 50 (max 200), andbefore(a reply id) pages back. The channel gate is the same asread_channel’s, andparentIdmust be a message of that channel (as forreply_in_thread); only replies stored in that channel are returned. Replies include system rows (joins, status lines), whichread_channel’sreplyCountdoes 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 }, wherekindismentionordmandchannelIdisnullfor a DM. It never lists the identity’s own messages or a mention in a channel the identity cannot read. Withoutcursorit starts after the lastack_inboxof 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 carriestruncatedBefore(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)storesnextCursorfor 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_keyonpost_messageandreply_in_thread: the same token sending the same key within 24 hours gets the first post’smessageIdback (idempotentReplay: true) and nothing is written. The same key with a different text, channel or parent is refused withcode: "idempotency_conflict"; while the first request is still in flight a retry getscode: "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 withcode: "token_revoked".
Bots: DMs, reactions and search
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.peeris a person’s user id; a person’s token may also name one of the workspace’s agents.limitdefaults to 50 (max 200) andbefore(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 asget_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 otherpeeris answered like a person who is not in the workspace. This is checked on every request (the same ruleget_inboxapplies), 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_keybehaves as onpost_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)andunreact(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 channelread_channelallows, or a DMread_dmwould 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 withchannelId(nullfor a DM) andcreatedAt. WithchannelIdit searches that channel throughread_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 DMsread_dmreturns). 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.limitdefaults to 20 (max 50);beforeis theidof a result, so passing the lastidof a page returns the next page with nothing skipped.
Tasks
| Tool | Purpose |
|---|---|
list_tasks | List a workspace’s tasks |
get_task | Read one task in full |
create_task | Create a task |
update_task | Change a task’s fields |
delete_task | Delete a task |
add_task_comment | Post a comment onto a task’s Activity feed |
list_states | The workflow states (board columns) of a project |
list_project_labels | The label catalog of a project |
Pages
| Tool | Purpose |
|---|---|
list_pages | List a project’s documented pages |
read_page | Read one page |
create_page | Create a page |
update_page | Change a page’s title, body or icon |
delete_page | Delete 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.