# Configure Thoth from Claude Code or Cursor

> Connect an MCP client to your workspace to inspect setup, preview changes, and approve them in the browser.

Source: https://docs.atensecurity.com/docs/mcp/configure-thoth

Thoth exposes its workspace configuration as an MCP server (streamable HTTP):

| Workspace | Server URL                                                  |
| --------- | ----------------------------------------------------------- |
| Paid      | `https://grid.<tenant>.atensecurity.com/thoth/mcp/<tenant>` |
| Trial     | `https://govapi.trial.atensecurity.com/thoth/mcp/<tenant>`  |

Connect Claude Code or Cursor to it and ask the client what is left to set up,
which agents and tools Thoth has seen, and what a change would do before it
happens.

This is a different server from the [MCP proxy](https://docs.atensecurity.com/docs/mcp/proxy). The proxy
governs other MCP servers' tool calls; this server configures Thoth itself. It
does not call a language model on your behalf: your client's model reads the
results and Thoth only runs the operations.

## Generate the client configuration

```bash
thothctl mcp config --client claude-code --tenant-id <tenant> > .mcp.json
thothctl mcp config --client cursor --tenant-id <tenant> > .cursor/mcp.json
```

For a trial workspace, add `--trial`.

The command prints JSON on stdout and setup notes on stderr. If the file
already lists other servers, merge the `thoth` entry by hand instead of
redirecting over it.

## Choose how the client signs in

|                  | Signed in as you (default)                                    | Scoped machine key                |
| ---------------- | ------------------------------------------------------------- | --------------------------------- |
| Flag             | `--auth oauth`                                                | `--auth api-key`                  |
| Identity         | Your Thoth user, through the browser                          | A control-plane API key           |
| Read and preview | Admins preview; viewers read                                  | Read permission                   |
| Commit           | Returns an approval link; you approve in the browser with MFA | Write permission commits directly |

With `--auth api-key` the configuration references the key by environment
variable (`THOTH_ORG_API_KEY` by default, change it with `--api-key-env`). The
key is never written to the file. Export it before starting the client:

```bash
export THOTH_ORG_API_KEY="$(op read 'op://<vault>/<item>/credential')"
```

Create keys with `thothctl api-keys create --organization --permission read`
for inspection, and add `--permission write` only for automation that should
commit without a person approving each change.

## Approving a change

1. Ask your client for a change, for example "mark `orders.list` as read-only
   for the billing agent".
2. The client calls a preview tool. Thoth returns the effect in plain
   language, the affected agents, a diff and a digest. Nothing has changed yet.
3. When the client calls `commit_preview` while signed in as you, Thoth
   returns an approval link instead of committing.
4. Open the link. The page shows the server's own description of the change,
   not the client's. Approve it; Thoth asks you to sign in again if your MFA is
   not recent.
5. Ask the client to check the operation with `get_operation`.

An approval link works once, only for the user who requested it, only in the
workspace it was created for, and expires after 10 minutes. If the workspace
changed since the preview, the commit is refused and the client needs a new
preview.

## Tools

| Tool                            | Does                                                                |
| ------------------------------- | ------------------------------------------------------------------- |
| `get_setup_status`              | Setup progress and the next step                                    |
| `get_attention`                 | Items that need a person, with reasons                              |
| `list_agents`, `get_agent`      | Agents Thoth has seen and their configuration                       |
| `list_tool_inventory`           | Observed tools; names and descriptions are quoted as untrusted text |
| `list_profiles`                 | Governance profiles you can select                                  |
| `preview_tool_declaration`      | Preview confirming what tools do                                    |
| `preview_profile_selection`     | Preview selecting a profile                                         |
| `commit_preview`                | Commit a preview (approval link or direct, see above)               |
| `get_approval`, `get_operation` | Status of an approval or a committed change                         |
| `explain_decision`              | The recorded explanation of an enforcement decision                 |

Tool names and descriptions in the inventory come from the agents and MCP
servers Thoth observed. Treat them as data. Your client receives them wrapped
and labelled as untrusted, and no tool commits a change without a preview the
server generated.

## Trials

Trial workspaces get the same server. Trials select one profile for every
agent and cannot set profile parameters. There is no hosted assistant in
trials; bring your own client.

## Select your task scope

For user OAuth sessions, a preview first returns a browser scope-selection link.
Open it as the same user and select the exact agent IDs and tool names for this
task. Return the selected scope and `scope_revision` to your client, then request
the preview again. Changing that selection or switching the originating session
organization invalidates open previews. Confirm the complete server-generated
diff in the browser with recent MFA. Machine keys supply structured scope directly.