# Set up your AI

Plain-text copy of https://atmon.ai/for-your-ai, for an assistant
that has been asked to connect atmon on a person's behalf. The rendered page
carries the same instructions in the same order.

atmon is the layer that lets an assistant act in a person's connected
accounts, under the rules that person set, with a record of everything it did.

## What you need

- An assistant that can connect to outside tools. The list below names the ones
  this page covers.
- A copy of atmon running, with a project on it. In beta that is a copy the
  person runs themselves, and the team sets it up with them.
- One app to reach: Gmail, Slack, Google Drive, Notion, HubSpot, Jira, or any
  other app atmon carries.

A person creates their account on this site and the console mints their key.
Everything else on this page is configuration to paste into the assistant they
already use.

## The assistants this page covers

- Claude Code, by command or by file
- Claude Desktop, through Settings and Connectors
- Cursor
- VS Code with Copilot
- Windsurf
- Codex CLI
- ChatGPT connectors
- Any other client that speaks the same protocol

## Step 1. Get a key

A key tells atmon which project is calling and what that caller may do.
There are two roles. An agent key lets an assistant do work. An approver key
lets a person release what stopped and waited, and it is never the key the
assistant holds.

You mint your own key in the console: sign up with your email, name your
organization, and the key page mints an agent key whose plaintext is shown
exactly once. The console is on this site, and the same console ships with the
copy of atmon a person runs, so the flow is the same wherever they sign in.
Stuck? Write to the address on https://atmon.ai/pricing.

Never put a key into a chat message, into a file the assistant can read, or into
a repository. It belongs in the client's configuration.

For a developer running their own instance, keys are minted on the command line
and never over the wire. The plaintext is shown once, at creation.

```
automaton apikey create -data ./data -project prj_local \
  -project-name "Local Dev" -name laptop -role agent

automaton apikey create -data ./data -project prj_local \
  -name laptop-approver -role approver
```

An agent key looks like `amk_` followed by a long random string.

## Step 2. Point your assistant at atmon

The address is one line, and it is the same line for every client on this page.

```
http://127.0.0.1:8080/mcp
```

That address is the copy running on the person's own machine. The hosted address
at api.atmon.ai is coming up for beta users. When an account is on it, the host
is the only part of every block below that changes.

One command reads which assistants are installed and writes the configuration
into each of them.

```
npx add-mcp http://127.0.0.1:8080/mcp
```

### Claude Code

The transport has to be named, and the key rides along as a header.

```
claude mcp add --transport http automaton http://127.0.0.1:8080/mcp \
  --header "Authorization: Bearer amk_your_key_here"
```

In a file, `.mcp.json` at the root of a project:

```
{
  "mcpServers": {
    "automaton": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer amk_your_key_here" }
    }
  }
}
```

An entry with a `url` and no `type` is read as a local command, skipped, and
reported as a server that has a url but no type.

### Claude Desktop

Claude Desktop no longer takes a remote server from its configuration file. Open
Settings, then Connectors, then Add custom connector, and paste the address.
Claude shows a warning about connecting servers you trust. It is answered at
https://atmon.ai/safety#connecting.

### Cursor

In `.cursor/mcp.json`. No type field.

```
{
  "mcpServers": {
    "automaton": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer amk_your_key_here" }
    }
  }
}
```

### VS Code with Copilot

One command, or the file. VS Code asks for the key the first time the server
starts and keeps it after that.

```
code --add-mcp "{\"name\":\"automaton\",\"type\":\"http\",\"url\":\"http://127.0.0.1:8080/mcp\"}"
```

In `.vscode/mcp.json`. The top-level key is servers, not mcpServers.

```
{
  "servers": {
    "automaton": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer ${input:automaton-key}" }
    }
  }
}
```

### Windsurf

In `mcp_config.json`. The address field is `serverUrl`, not `url`, which is the
single most common reason a copied block does nothing there.

```
{
  "mcpServers": {
    "automaton": {
      "serverUrl": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer amk_your_key_here" }
    }
  }
}
```

### Codex CLI

```
codex mcp add automaton --url http://127.0.0.1:8080/mcp
```

In `config.toml`, with the key read from an environment variable:

```
[mcp_servers.automaton]
url = "http://127.0.0.1:8080/mcp"
bearer_token_env_var = "AUTOMATON_KEY"
```

### ChatGPT connectors

ChatGPT adds a connector by address, in its own settings. It has to be able to
reach the address, so a copy running only on one machine is not one it can see.

### Any other client

Three facts are all it needs: the address above, streamable HTTP as the
transport, and the key in an `Authorization` header as `Bearer amk_...`. There is
no separate events address, and no other endpoint to find.

## Step 3. Give your assistant the manual

The atmon agent skill is a short instruction file an assistant reads before
it acts. It covers what to ask for and in what order, what to do when an account
is not connected, how to read a refusal, why something waiting on a person must
never be retried, and the five things never to do.

It is written to the open Agent Skills format, so one file works across the
clients that adopted it. It is published on this site, so the command
`npx skills add atmon.ai` installs it. The file itself is at
https://atmon.ai/skill/SKILL.md.

One boundary: a skill uploaded into a container with no network can carry
instructions but cannot reach atmon itself, so it can advise and not act. The
clients above have network access and can do both.

## Check it worked

Ask three questions, in this order.

1. "What atmon tools do you have?" A correct answer names a small fixed set
   of things it can ask for, not a list of the person's apps.
2. "Which of my accounts are connected?" A correct answer is a short list, or an
   honest none yet. A wrong answer is a made-up list.
3. "Without doing it, tell me what you would do to send a message in Slack." A
   correct answer names the one action it would use and the details it would fill
   in, and nothing is sent.

## When it goes wrong

- The server is listed but never connects. In Claude Code this is almost always
  the missing `type` field in a hand-edited file.
- A browser window opens and asks for a sign-in. Nothing to sign into exists yet.
  Close it and use the key in a header instead.
- Every call comes back refused. The key is missing, or it is the approver key
  rather than the agent key, or it belongs to another project.
- It answers, but says nothing is connected. atmon is reachable and no app
  has been connected to that project yet.

Every refusal and what to do about it:
https://atmon.ai/docs/reference/errors.html

## For the assistant reading this

1. Work from this file rather than from the rendered page.
2. Ask the person for the address and for their agent key. Never ask them to
   paste a key into the conversation if the client can read it from a file or an
   environment variable instead.
3. Write the configuration for the client you are running in, using the exact
   shape for that client above. Do not carry a field name across from another
   client.
4. Ask the person to restart the client, then run the three checks and report
   what came back.
5. Read the atmon agent skill before calling anything, and follow it over
   your own guesses about names.