An organization agent is a member of your organization that never signs in. It acts only through its own API tokens. People can @mention it in comments and assign it tasks, like anyone else.
An agent harness is the program that runs such an agent outside MySpec, for example clawbot or grokbot. This guide connects one: the harness gets the agent’s token, follows the mentions and tasks meant for the agent as they happen, and reads that work back with the MCP tools.
Every step is a command or a click, with the answer you should see.
What an agent can and cannot do
- It works through either MCP server with an API token, with the same tools as a person’s token. This guide uses the remote server; the local server works too (see Disable or delete the agent for the one difference).
- Its role on a project is Write at most: an Admin role from a grant, a team or the organization default acts as Write.
- It cannot manage the organization, its members, teams or project access.
- It gets no email, and it cannot sign in to the web app.
- In the web app, comments it writes show as MySpec AI, like any comment written through MCP.
Before you start
- You need the Owner or Admin role in the organization.
- Pick the project the agent will work on, and copy its id. It is in the
project’s address:
https://app.myspec.dev/projects/<project-id>. - To see both kinds of message on the stream, the project needs at least one
spec file (to comment on) and a
tasks.mdwith checkbox tasks (to assign), and the task board must be on for your organization. Without the task board, mentions still work, but the task steps fail with “the task board is turned off in this MySpec environment”. - The commands below use
curl,jqand Node.js 22 or later (fornpx).
Create the agent
Open Agents
In MySpec, open the avatar menu and choose Agents. Only owners and admins see it.
Name it
Under Create an agent, fill in a Name, for example “Release bot”,
and a Username, for example release-bot. The username is how people
@mention the agent. It has up to 32 lowercase letters, digits, _ or -,
and no person or agent in the organization can already have it.
Create it
Select Create agent. You see Agent Release bot created., and the agent appears in the list.
Give it access to a project
An agent starts with your organization’s default project access, capped at Write. If the default is No access or Read, give it Write on the project:
Open the Access card
Open the project’s Settings tab and select Access, then select Add access.
Pick the agent
Under Give access to, choose Person, then pick the agent. It is listed as “Release bot (Agent)”.
Add it
Keep the Write role and select Add. You see Access updated, and the agent shows with an Agent badge.
Create its API token
Open the agent's tokens
On the Agents page, select Tokens next to the agent, then Create token.
Fill in the details
- Token name: for example “harness”.
- Access: Read and write, so the agent can reply to comments and update tasks. Read only is enough to only follow and read.
- Expires after: 30, 90, 180 or 365 days.
An agent can have up to 25 active tokens.
Copy the token
Select Create token. The token, which starts with msp_pat_, is shown
once. Select Copy, store it in the harness’s secret store, then
select I have stored it.
- Treat a token like a password. Never commit it to a repository, paste it into a chat or put it in a URL.
- Give each machine or pipeline its own token, so you can revoke one without breaking the others.
- Prefer Read only unless the agent needs to change things.
- Choose the shortest expiry that works for you, and revoke tokens you no longer use.
Connect the harness
The harness sends the agent’s token as a bearer token to the remote MCP server, on every request:
POST /mcp HTTP/1.1
Host: mcp.myspec.dev
Authorization: Bearer msp_pat_…
Content-Type: application/json
Accept: application/json, text/event-streamThe server exchanges the token for a short-lived access token and acts as the agent. The harness never handles that access token. Each MCP client has its own way to set the header; see Remote MCP server.
Check the connection by hand. Set the token in your shell first, so it does not end up in your shell history in later commands:
read -rs myspec_token # paste the msp_pat_… token, then press EnterThen define a small helper for the rest of this guide. It calls one MCP tool,
prints the HTTP status if it is not 200, prints a tool’s error message if the
tool failed, and otherwise prints the tool’s JSON result:
myspec() {
local reply status
reply=$(curl -s -w '\n%{http_code}' https://mcp.myspec.dev/mcp \
-H "Authorization: Bearer $myspec_token" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"$1\",\"arguments\":$2}}")
status=${reply##*$'\n'}
reply=${reply%$'\n'*}
if [ "$status" != 200 ]; then echo "HTTP $status" >&2; return 1; fi
if jq -e '.error' <<<"$reply" >/dev/null; then jq -r '.error.message' <<<"$reply" >&2; return 1; fi
if jq -e '.result.isError' <<<"$reply" >/dev/null; then jq -r '.result.content[0].text' <<<"$reply" >&2; return 1; fi
jq -r '.result.content[0].text' <<<"$reply"
}Read the project as the agent, with get_project:
myspec get_project '{"project_id":"<project-id>"}' | jq '.project | {id, name}'You should see the project:
{ "id": "<project-id>", "name": "…" }HTTP 401 means the token is wrong. A “not found” message means the agent has
no access to the project yet; a “permission denied” message means its role there
is only Read.
Follow the agent’s work live
A stream token lets the harness react the moment someone
mentions the agent or assigns it a task, instead of polling. Create one with
create_stream_token and its
recipient argument set to
"self":
stream=$(myspec create_stream_token '{"resource_id":"<project-id>","event_types":["spec_file_comment.created","spec_file_comment.updated","task.updated","project.deleted"],"recipient":"self","ttl_seconds":3600,"label":"harness"}') \
&& echo "$stream" | jq '{id, recipient, expires_at}' \
&& stream_url=$(jq -r '.url' <<<"$stream")The result names the filter:
{ "id": "<stream-token-id>", "recipient": "self", "expires_at": "…" }list_stream_tokens shows
recipient: "self" on this token too.
With recipient: "self", the token delivers only the events that name the
agent: a new comment, or an edit, that mentions it, and a
task.updated that assigns it a task. The
project.deleted event arrives because it is among the four types above; the
stream ends on a project delete either way. See
Only the events that name you
for the full rule.
The result’s url is everything a client needs to connect, so keep it in the
variable: never print it, log it or commit it. See
Stream tokens.
Connect with any WebSocket client, using the subprotocol v1:
npx -y wscat -s v1 -c "$stream_url"The first message confirms what the token covers, with its event types in alphabetical order:
{ "v": 1, "type": "stream.ready", "at": "…", "resource": { "type": "project", "id": "<project-id>" }, "token_id": "<stream-token-id>", "event_types": ["project.deleted", "spec_file_comment.created", "spec_file_comment.updated", "task.updated"], "expires_at": "…" }Now, in the web app, select a passage of a spec file in the project and start a
new comment that mentions the agent: “@release-bot please review this”. Then
assign the agent a task on the project’s task board.
Also mention someone else in another comment, and assign a task to yourself:
those do not arrive. The agent’s two arrive as one message each (… marks
fields left out here):
{ "v": 1, "seq": 1, "type": "spec_file_comment.created", "at": "…", "resource": { "type": "project", "id": "<project-id>" }, "data": { "thread_id": "<thread-id>", "comment_id": "<comment-id>", … } }
{ "v": 1, "seq": 2, "type": "task.updated", "at": "…", "resource": { "type": "project", "id": "<project-id>" }, "data": { "task_ids": ["<task-id>"], … } }- Messages never carry the comment’s text or who it mentions. Read the work back with the tools in the next section.
- Keep the
seqof the last message you handled. To reconnect without missing anything, add?after=<seq>to the URL. - Before a token expires you get a
stream.expiringmessage: create a new token then. - Close codes and what to do about each are in Handle closed connections.
Read the work back
A stream event says what happened, not the content. To act on it, the harness
reads the work with two MCP tools, passing me for the agent:
list_project_commentswithmentioned_user_id: "me": the threads where someone mentioned the agent.list_taskswithassignee_user_id: "me": the tasks assigned to the agent.
myspec list_project_comments '{"project_id":"<project-id>","mentioned_user_id":"me"}' \
| jq '.threads[] | {thread_id, comments: [.comments[] | {comment_id, body}]}'You should see the thread you started, and not the one that mentions someone else:
{
"thread_id": "<thread-id>",
"comments": [{ "comment_id": "<comment-id>", "body": "@release-bot please review this" }]
}myspec list_tasks '{"project_id":"<project-id>","assignee_user_id":"me"}' \
| jq '.tasks[] | {task_id, title, assignee_user_id}'You should see the task you assigned, and only that one:
{ "task_id": "<task-id>", "title": "…", "assignee_user_id": "<agent-user-id>" }The harness can then reply with reply_spec_file_comment_thread and move the
task with set_task_status. See MCP tools for every argument and
field.
Disable or delete the agent
On the Agents page, an owner or admin can Disable an agent, and later Re-enable it, or Delete it. The agent then stops working within about a minute, or longer if MySpec is briefly unable to apply the change. These happen in no fixed order:
- The remote server refuses its tokens. Every call fails with
401, so themyspechelper above printsHTTP 401. Disabling keeps the tokens: when you re-enable the agent, they work again. To stop a token for good, for example one that may have leaked, revoke it on the agent’s page. - New stream tokens are refused.
create_stream_tokenfails with a permission error. - Its streams stop. Its stream tokens are revoked and the events kept for
them are deleted. Open connections, and new ones, get a
stream.errormessage whose reason isrevokedoragent_disabled, then close with code4001.
Deleting an agent cannot be undone. Its comments, tasks and mentions stay.
Troubleshooting
| What you see | Meaning |
|---|---|
| No Agents entry in the avatar menu | Only organization owners and admins manage agents. |
HTTP 401 from the myspec helper |
The token is unknown, revoked or expired, or the agent is disabled or deleted. |
| A write fails with a read-only error | The token is Read only. Create a Read and write token. |
| A tool fails with “not found” | The agent has no access to the project. Give it access. |
| A tool fails with “permission denied” | The agent’s role on the project is only Read, and the tool needs Write. Give it Write. |
| This agent is disabled: it cannot get or refresh tokens. Re-enable it first., and no Create token button | The agent is disabled. Select Re-enable: its tokens work again. |
| “…the agent has reached its limit of 25 active tokens (revoke one first)” | The agent already has 25 active tokens. Revoke one it no longer uses, then create the new one. |
The stream closes with 4001 and reason revoked or agent_disabled |
The agent was disabled or deleted, or someone revoked the stream token. |
| Nothing arrives on the stream | Check the token was created with recipient: "self" and the event types you need, and that the mention uses the agent’s username. |
| “the task board is turned off in this MySpec environment” | The task board is not on for your organization. Mentions still work; the task steps do not. |