Connect an agent
Consoles supports two different connections, and they do different things. Set up one, the other, or both.
Choose a connection#
| Connection | Use it when you want | It does |
|---|---|---|
| Workbook MCP | An agent to read or work in a specific workbook. | Gives the agent only the workbook and permissions you approve. |
| Session capture | A record of work performed in a local Codex or Claude Code session. | Receives supported events emitted by that agent. |
The two stay separate: MCP access does not capture an agent's local tools or chat, and capture does not create a workbook, rerun local commands, or start Consoles compute.
Give an agent MCP access to a workbook#
- Open the workbook and select Connect agent in the header. You can also open Workbook settings → Agents → Connect agent.
- Choose This workbook unless the agent needs to create or manage workbooks across your account. The All workbooks choice includes management capability when you approve it.
- Copy the server URL and the setup commands shown in the panel.
- For Codex, the current panel provides these steps:
codex mcp add consoles --url https://consoles.ai/api/compute/mcp --oauth-client-registration dcr --oauth-resource https://consoles.ai/api/compute/mcp
codex mcp login consoles --scopes workspace:read,workspace:write,workspace:execute,recordings:read
- Complete the Consoles approval screen. Select the workbook you chose in the panel and approve only the permissions the agent needs.
- Return to the agent. Its workbook changes appear in Consoles as they happen.
Use the commands copied from the panel, because the displayed server URL reflects the Consoles instance you are using. The current panel includes Codex instructions; for another MCP client, use that client's own supported setup flow with the copied server URL.
What each permission allows
Workbook read access permits inspection, write access permits files and cells, and execution access permits runs and starting or stopping compute. Starting CPU or GPU compute may incur charges. Recordings read access is granted separately and is required to inspect captured session evidence or link it to a workbook, as described in Sessions.
The panel lists connected agents and lets you disconnect them.
Capture sessions through hooks#
Session capture records supported events from the agent you already use locally. The connector currently supports:
- Codex
- Claude Code
To set it up:
- Open Sessions and select Connect agent.
- Select Codex or Claude Code, choose the project folder, and download the capture configuration.
- Run the setup command shown in Consoles for that project.
- In Codex, open /hooks and trust the new hooks. In Claude Code, restart the project session to load the connector.
- Start a normal task. Its session appears in Sessions when the agent emits supported events.
The connector queues events locally and forwards them to your Consoles account. It adds no prompt text and makes no model calls. A capture credential can upload supported events, but it does not grant workbook read access or permission to execute compute.
Verify capture with a real event#
Run an ordinary, non-sensitive tool action from the connected agent. Then open Sessions and confirm that the expected agent, project, action, and result appear. A configuration download, a workbook you created yourself, or an MCP request does not prove hook capture.
Coverage depends on what the agent emits, so a session can be genuine and still be incomplete. Sessions describes what is captured, what is not, and how to link a session to a workbook.
Related#
- Sessions for what captured evidence contains and how links work.
- Workbooks for what an agent can read and change through MCP.
- Troubleshooting if a session does not appear or an agent can see more than expected.