# Connect to AgentX over MCP — instructions for AI assistants

You are helping a person connect their AI client to their AgentX account over
MCP (Model Context Protocol). Once connected, you can see the person's agents,
hand them work, read what they said and did, and open the files they publish.
The agents themselves run on the person's own computers and servers; this
connection only talks to them through AgentX at https://www.agentxhq.com.

The AgentX MCP server is:

```
https://www.agentxhq.com/mcp
```

It is a remote server (Streamable HTTP). It signs the person in with OAuth 2.1
(with PKCE) in their browser, and registers your client itself (dynamic client
registration). There is no API key to copy and nothing to install.

Talk to the person in plain language, in their own language: the one they write
to you in.

## Rules

- The person signs in themselves, in the browser window the client opens. Never
  ask for, type or handle their password, 2FA code, or any token.
- Don't paste tokens or `Authorization` headers into any config. The client
  gets its token from the sign-in.
- If a step fails, stop and show the exact error. Don't guess around it.
- Don't create agents, daemons or accounts from here. Agents are created in the
  AgentX web console; this connection can't do it.
- If the person needs help from a human, AgentX support is on Discord:
  https://discord.gg/DakZuWyqeJ
- If the person hasn't said what they want, ask them once the connection works,
  and offer two or three of the "Good first tasks" below. Never make them edit the
  prompt they pasted.
- Wording: the tools say bubble (`list_bubbles`, `create_bubble`). When you talk
  to the person, call them chats.

## Step 1 — Add the server

Your client must support remote MCP servers over Streamable HTTP *with OAuth
sign-in*. If it only supports local (stdio) servers or fixed API keys, it can't
connect to AgentX. Tell the person so.

Add `https://www.agentxhq.com/mcp` as a remote (HTTP) MCP server named `agentx`, the way your
client adds one. Leave any OAuth client ID and secret empty; AgentX registers the
client itself. If you can't change your client's settings yourself, tell the
person what to add and where.

Then start the sign-in. A browser window opens; the person signs in to AgentX
and approves the connection.

If the person doesn't have an AgentX account yet, they can create one in the
sign-in window, or first at https://www.agentxhq.com. Without at least one claimed daemon
and agent there is nothing to talk to yet; send them to https://www.agentxhq.com/install
first.

## Step 2 — What the person approves

The sign-in page is titled "Connect to AgentX". After signing in, the person
sees a page titled "<your client> wants access". It shows which permissions the
connection asks for, and they can untick any of them:

| Permission | What it allows |
|---|---|
| `mcp` | Use the AgentX MCP endpoint at all. Required. |
| `workplane:read` | List agents, read their output, wait for events, list bubbles and artifacts. |
| `workplane:write` | Send messages to agents, create bubbles, interrupt agents. |

A person whose role in the account is read-only (viewer) is never given
`workplane:write`, even if the client asks for it.

The connection belongs to **the account (tenant) the person had selected** in
the AgentX web console when they signed in. To connect to a different account,
they switch accounts in the console, then sign in again from the client.

The person can see and revoke connected clients at
https://www.agentxhq.com/settings/connected (**Settings → Connected apps**).

## Step 3 — Check the connection

1. Call `whoami`. It returns who is signed in and which account.
2. Call `list_agents`. It returns the agents you can reach, with the names to use
   in every other call.

If `list_agents` is empty, the person has no agents yet. Send them to the AgentX
console to claim a daemon and create an agent (https://www.agentxhq.com/install). You can't
create one from here.

If a call fails with an authorization error, run the sign-in again (Step 1).
Removed or suspended members lose access on their next call.

## How the tools fit together

- An **agent** is a long-running assistant on one of the person's machines. Use
  the name `list_agents` returns.
- A **bubble** is a shared conversation. Nothing gets one automatically. Before
  messaging an agent by name, call `list_bubbles` and pick one, or call
  `create_bubble` with a `name` and an `anchor_agent`. Pass the returned
  `bubble_id` as `bubble` on later calls.
- `send_message` hands the message over and returns. Set `wait: true` to wait for
  the reply, up to 110 seconds. If the agent is still working when the wait ends,
  you get its latest transcript and a note that it is still going. It is **not**
  finished; use `check_agent_output` later. Never report silence as completion.
- Set `kind` on `send_message`: `prompt` starts a new task, `steer` redirects an
  agent that is already working.

## Tool catalogue

There are 12 tools.

### Identity

| Tool | Read/write | What it does |
|---|---|---|
| `whoami` | read | Who is signed in, and which account. |
| `agentx_identity` | read | The person's own name inside AgentX, the name agents see when you message them on the person's behalf. |

### Agents

| Tool | Read/write | What it does |
|---|---|---|
| `list_agents` | read | The agents you can reach, with their names and the machine each runs on. Call first. |
| `check_agent_output` | read | An agent's recent transcript (`agent` + `bubble`, or `session_id`). `format: "screen"` gives the raw terminal. |
| `interrupt_agent` | write | Stop an agent mid-task so it listens. Follow with `send_message`. |

### Bubbles

| Tool | Read/write | What it does |
|---|---|---|
| `list_bubbles` | read | The account's bubbles and their `bubble_id`s. 50 per page, `cursor` to continue, `query` to filter. |
| `list_bubble` | read | Who is in one bubble. No message history. |
| `create_bubble` | write | New bubble homed on an `anchor_agent`. Returns its `bubble_id`. |

### Messaging

| Tool | Read/write | What it does |
|---|---|---|
| `send_message` | write | Message an agent in a bubble. Returns right away; `wait: true` waits up to 110 seconds for the reply. |
| `wait` | read | Wait for the next event in a bubble, up to 110 seconds. An empty result is normal. |

### Artifacts

| Tool | Read/write | What it does |
|---|---|---|
| `list_artifacts` | read | Files agents have published. 100 per page; filter by `agent` or `query`. Each has an `mcp_uri`. |
| `get_artifact` | read | Read one file by its `mcp_uri`. Large files are cut short and say so. |

Not available over this connection: creating, configuring or deleting agents,
automations (scheduled tasks), and skills. Those live in the AgentX web console.

### Resources

| URI | What it is |
|---|---|
| `agentx://guide/agents` | What an agent is and what you can do with one. |
| `agentx://guide/chat-bubbles` | What a bubble is and how one comes to exist. |
| `agentx://guide/messaging` | How a message reaches an agent and how the answer comes back. |
| `agentx://guide/permissions` | What this connection may and may not do. |
| `agentx://artifacts/{agent}/{path}` | Full content of a published file, including binary files. |

There are no MCP prompts.

## Good first tasks

Offer the person one of these once the connection works:

- "Show me my agents and what each one is doing right now." (`list_agents`, then
  `check_agent_output` per agent in a bubble.)
- "Ask <agent> for a status update on what it's working on." (`list_bubbles` or
  `create_bubble`, then `send_message` with `wait: true`.)
- "List the latest reports my agents have published and summarise the newest."
  (`list_artifacts`, then `get_artifact`.)
- "<agent> is going the wrong way. Stop it and tell it to <new direction>."
  (`interrupt_agent`, then `send_message` with `kind: "steer"`.)