---
title: "Connect an agent harness"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an agent harness

An **organization agent** is a member of your organization that never signs in.
It acts only through its own [API tokens](https://docs.myspec.dev/mcp/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](https://docs.myspec.dev/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](https://docs.myspec.dev/mcp/remote-server/); the [local server](https://docs.myspec.dev/mcp/local-server/)
  works too (see [Disable or delete the agent](#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](https://docs.myspec.dev/guides/projects/#tasks) 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

1. **Open Agents**

   In [MySpec](https://app.myspec.dev), open the avatar menu and choose
   **Agents**. Only owners and admins see it.
2. **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.
3. **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](https://docs.myspec.dev/guides/teams-and-project-access/#your-organizations-default-project-access),
capped at **Write**. If the default is **No access** or **Read**, give it
**Write** on the project:

1. **Open the Access card**

   Open the project's **Settings** tab and select **Access**, then select
   **Add access**.
2. **Pick the agent**

   Under **Give access to**, choose **Person**, then pick the agent. It is
   listed as "Release bot (Agent)".
3. **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

1. **Open the agent's tokens**

   On the **Agents** page, select **Tokens** next to the agent, then
   **Create token**.
2. **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.
3. **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:

```http
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](https://docs.myspec.dev/mcp/remote-server/#connect-with-an-api-token).

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:

```bash
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:

```bash
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`:

```bash
myspec get_project '{"project_id":"<project-id>"}' | jq '.project | {id, name}'
```

You should see the project:

```json
{ "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](https://docs.myspec.dev/mcp/stream-tokens/) 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](https://docs.myspec.dev/mcp/stream-tokens/#create-a-stream-token) set to
`"self"`:

```bash
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:

```json
{ "id": "<stream-token-id>", "recipient": "self", "expires_at": "…" }
```

[`list_stream_tokens`](https://docs.myspec.dev/mcp/stream-tokens/#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`](https://docs.myspec.dev/mcp/stream-tokens/#event-types) 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](https://docs.myspec.dev/mcp/stream-tokens/#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](https://docs.myspec.dev/mcp/stream-tokens/#create-a-stream-token).

Connect with any WebSocket client, using the subprotocol `v1`:

```bash
npx -y wscat -s v1 -c "$stream_url"
```

The first message confirms what the token covers, with its event types in
alphabetical order:

```json
{ "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](https://docs.myspec.dev/guides/projects/#tasks).
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):

```json
{ "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](#read-the-work-back).
- 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](https://docs.myspec.dev/mcp/stream-tokens/#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`](https://docs.myspec.dev/mcp/tools/#comments) with
  `mentioned_user_id: "me"`: the threads where someone mentioned the agent.
- [`list_tasks`](https://docs.myspec.dev/mcp/tools/#tasks) with `assignee_user_id: "me"`: the tasks
  assigned to the agent.

```bash
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:

```json
{
  "thread_id": "<thread-id>",
  "comments": [{ "comment_id": "<comment-id>", "body": "@release-bot please review this" }]
}
```

```bash
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:

```json
{ "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](https://docs.myspec.dev/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`.

> **The local server keeps a short sign-in**
>
> A [local server](https://docs.myspec.dev/mcp/local-server/) that is already running with the
> agent's token keeps acting as the agent for up to about 15 minutes after a
> disable. Restart it to cut it off at once.

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](#give-it-access-to-a-project). |
| A tool fails with "permission denied" | The agent's role on the project is only **Read**, and the tool needs **Write**. [Give it Write](#give-it-access-to-a-project). |
| **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. |

Source: https://docs.myspec.dev/mcp/agent-harness/index.mdx
