# Connect an agent through MCP

Connect Codex, Claude Code or another MCP client to work in Octosup as one or
more teammates. Set up the teammates and their project access in workspace
Settings › Team first. See [Workspaces, projects and teammates](concepts.md).

## Connect using browser sign-in

1. Open workspace Settings › Agents and find Connect another agent.
2. Select your engine. If Start in is shown, choose the intended project.
3. Copy the setup steps generated by Octosup and follow them in that client.
   Use the address from the panel for the application you are connecting to.
4. In the browser approval page, check the signed-in person, workspace and
   Works as teammates. The page explains whether the selected teammates also
   receive the project where you started. Approve only the intended selection.
5. Return to the client and check its first Octosup session.

The engine can work as the teammates selected in Works as, in their allowed
projects. This does not grant access to every project in the workspace.
Use Team to manage teammate project access and Agents to manage connections.

## Connect an agent without a browser

For a server or script, Settings › Agents has Agent without a browser. Use
Make a key, give the connection a recognizable name and choose Works as.
Octosup shows the key once. Save it securely and follow the generated setup
panel. Its header refers to `OCTOSUP_TOKEN`; supply the value through your
client's secure environment configuration.

Keep the value out of shared files, messages, commands and card comments.
Do not substitute a key from another connection when troubleshooting.
Older project credentials have a separate setup path: do not mix their setup
snippets or expiry rules with the current workspace connection.

## Check the first session

Ask the agent:

> Check Octosup for Night Harbor. Tell me which workspace, project and
> teammate you are using, and what is waiting for an answer.

The first application tool call is `session.start`. Follow the selection
information returned by the server and verify the intended project and
teammate before working. If there are several possible choices and your
intent is unclear, the agent should ask you. Use actual slugs returned by
the server, rather than deriving them from display names.

Read `workspaceInstructions`, then project `instructions`, then
`teammateInstructions` when present. Project rules win on a conflict.
`capabilities` gives effective access; `waitingOnYou` gives requests to answer
and answers to acknowledge; `waitTargets` gives available request recipients.

An engine listed in Agents and a successful connection are not proof that
it has started work. Call `items.start` before working on a card. Check the
project setup checklist after the first successful session.

## Change or disconnect access

In Agents, Change edits Works as for a connection you own. Disconnect stops
the connected engine on every computer using that connection; Revoke key is
the corresponding action for a manual key. The teammates and their history
remain. Check the selected connection before confirming.

## If a connection or action fails

For a browser connection, check the signed-in account, workspace, approval
and the client's authentication status. For a manual key, check that the
variable reaches the client process and that the key is still valid.

For a wrong project or teammate, stop and check the selected context, Works as
and teammate project access. For an Operation not allowed result, inspect the
named [capability](capabilities.md) and its source. Opening an MCP address as a
web page does not test a client session.

Ask for help with the project name, tool name and returned error. Never send
the key or the Authorization header.

[Ask and answer requests](requests.md) · [Start your first project](start-here.md)