# Agents and scripts

AI assistants connect through our MCP server. Scripts and coding agents use the ct CLI: every command speaks JSON and returns a clear exit code.

## AI assistants (MCP)

CircuitTwin is a remote MCP server at `https://app.circuittwin.ai/mcp`. Add it as a custom connector in Claude (or as a custom MCP server in ChatGPT, where your plan allows one). In Claude Code:

terminal

```
claude mcp add --transport http circuittwin https://app.circuittwin.ai/mcp
```

When you connect, you sign in with your CircuitTwin account and choose a workspace and the access: **Read only**, or **Read, run firmware and generate twins**. The assistant can then list your projects and systems, search and read twins, generate a twin, run firmware or a system, and read the result. No tool deletes or overwrites anything. Generating a new twin uses one generation credit; runs do not. Your role’s permissions still apply.

## JSON everywhere

Add `--json` to any command and it prints one machine-readable document on stdout, with progress and problems on stderr. Exit codes are stable (see the [CLI reference](https://circuittwin.ai/docs/cli)), so a script or an agent can branch on the result without parsing prose. For `ct run`:

terminal

```
ct run --json --board nucleo-f767zi build/app.elf --until READY > run.json
echo $?   # 0 pass, 1 fail, 2 invalid input, 3 platform error, 4 inconclusive
```

## The hosted API: ct cloud

`ct cloud` gives scripts and agents the hosted API with a workspace’s access token: upload documents and firmware, build twins, make and wire boards, submit runs and suites, and read their results. It always prints JSON with structured errors, uses HTTPS (plain HTTP only to a loopback server) and waits for a bounded time.

| Command           | What it does                                                                 |
| ----------------- | ---------------------------------------------------------------------------- |
| ct cloud whoami   | The account, the token’s organization and its live permissions               |
| ct cloud catalog  | Search the shared component and MCU catalog                                  |
| ct cloud source   | Upload datasheets and companion documents                                    |
| ct cloud twin     | Build and read component twins                                               |
| ct cloud mcu      | Import an MCU from uploaded sources                                          |
| ct cloud firmware | Upload or list firmware images                                               |
| ct cloud project  | List and make projects                                                       |
| ct cloud board    | Create boards (one-microcontroller systems), add devices and wire named pins |
| ct cloud run      | Submit and inspect firmware runs                                             |
| ct cloud suite    | Run a test suite on the server (what the CI integrations call)               |
| ct cloud job      | Follow durable jobs: builds, runs and debug sessions                         |
| ct cloud session  | Remote debug sessions                                                        |
| ct cloud api      | Call any JSON endpoint of the public API on the signed-in server             |

terminal

```
export CT_SERVER=https://app.circuittwin.ai
export CT_TOKEN=ctk_...            # or sign in once with ct login
ct cloud whoami
ct cloud catalog --help
```

## Giving a coding agent a token

- Create a dedicated [access token](https://circuittwin.ai/docs/tokens) for the agent with only the scopes it needs (for example `runs` to run firmware, `twins` to build twins), and an expiry.
- Tokens are bound to one workspace and can never manage members or other tokens, whatever the agent asks for.
- Point the agent at `ct --help` and this page. Every subcommand documents itself with `--help`.
- Revoke the token in Settings when you are done; the next command the agent runs fails.