Skip to content

Connect an agent harness

Give an external agent harness its own MySpec identity, let it follow the mentions and tasks meant for it, and read that work back over MCP.

Updated View as Markdown

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.md with 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, jq and Node.js 22 or later (for npx).

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-stream

The 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 Enter

Then 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 seq of the last message you handled. To reconnect without missing anything, add ?after=<seq> to the URL.
  • Before a token expires you get a stream.expiring message: 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_comments with mentioned_user_id: "me": the threads where someone mentioned the agent.
  • list_tasks with assignee_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 the myspec helper above prints HTTP 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_token fails 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.error message whose reason is revoked or agent_disabled, then close with code 4001.

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.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close