Set up your AI
Tell your assistant
to read this page.
This page is written twice over: so a person can follow it top to bottom, and so an assistant that is handed the address can follow it on that person's behalf. There is a plain-text copy of it at for-your-ai.md for the second reader.
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 you run yourself; the setup is one page of the docs.
- One app you want it to reach: Gmail, Slack, Google Drive, Notion, HubSpot, Jira, or any other app atmon carries.
You create your account on this site and the console mints your key. Everything else below is configuration you paste into the assistant you already use.
The assistants this page covers
Find yours before you read any further. Every one of them takes the same address; what differs is where you put it.
- 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 is how atmon knows which project is calling and what that caller is allowed to do. There are two roles, and they exist so that one cannot cover for the other.
- An agent key lets your assistant do work. This is the one that goes in the blocks below.
- An approver key lets a person release the things that stopped and waited. It is never the key your 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, at creation, and never stored.
The console is on this site, and the same console ships with the copy of atmon you run, so the flow is the same one wherever you sign in. Stuck anywhere in it? Reach the team.
Three places a key must never go: into a chat message, into a file your assistant can read, or into a repository. It goes in your client's configuration, which is where the blocks below put it.
For developers running their own instance
Keys are minted on the command line and never over the wire, so there is no bootstrap credential to leak. The plaintext is shown once, at creation, and is never stored or logged.
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, which is how you can tell at a glance that you grabbed the right kind of thing.
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 your own machine. The hosted address at api.atmon.ai is coming up for beta users. When your account is on it, the host is the only part of every block on this page that changes, and the rest stays exactly as it is written here.
The one-line way
One command reads which assistants you have installed and writes the configuration into each of them.
npx add-mcp http://127.0.0.1:8080/mcp
Claude Code
One command. 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"
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 will show you a warning about connecting servers you trust before it finishes. That warning is a good one, and the safety page answers it directly.
Cursor
Cursor takes the address in its own configuration file, with no transport field. The block is in the developer tab below.
VS Code with Copilot
One command, or the file in the developer tab. 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\"}"
Windsurf
Windsurf calls the field serverUrl rather than url, which is the single most common reason a copied block does nothing there. The right one is in the developer tab.
Codex CLI
codex mcp add automaton --url http://127.0.0.1:8080/mcp
ChatGPT connectors
ChatGPT adds a connector by address, in its own settings, the way Claude Desktop does. It has to be able to reach the address, so a copy running only on your own machine is not one it can see. This is the client that waits for the hosted address.
Any other client
If your client speaks the same protocol, 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 to configure, and no other endpoint to find.
For developers: the configuration file for each client
Four different shapes are in play and three of the four differ by exactly one field name, so these are worth copying rather than typing.
Claude Code, in .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. That one missing field is the most common failure on this page.
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, 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.
{
"mcpServers": {
"automaton": {
"serverUrl": "http://127.0.0.1:8080/mcp",
"headers": { "Authorization": "Bearer amk_your_key_here" }
}
}
}
Codex CLI, in config.toml. TOML rather than JSON, and the key is read from an environment variable.
[mcp_servers.automaton] url = "http://127.0.0.1:8080/mcp" bearer_token_env_var = "AUTOMATON_KEY"
Step 3. Give your assistant the manual
The atmon agent skill is a short instruction file your assistant reads before it acts. An assistant that has read it asks for the right thing the first time and stops guessing at names.
- What to ask for, and in what order.
- What to do when an account is not connected.
- How to read a refusal, and why something waiting on a person must never be retried.
- The five things never to do.
It is written to the open Agent Skills format, so the same file works in Claude Code, Cursor, VS Code and the other clients that adopted it. It is published on this site, so npx skills add atmon.ai installs it, and you can read the file first at atmon.ai/skill/SKILL.md.
One boundary worth knowing before you install it anywhere. 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 on this page have full network access and can do both.
The docs carry the current install instructions per client.
Check it worked
The only thing you have to type here is ordinary English. Ask your assistant these three questions, in this order.
- What atmon tools do you have? A correct answer names a small fixed set of things it can ask for, not a list of your apps. The set does not grow when the list of apps does.
- Which of my accounts are connected? A correct answer is a short list, or an honest none yet with a link to connect one. A wrong answer is a made-up list.
- 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. That is the rehearsal, and it is the habit worth teaching your assistant on day one.
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. Add it, or delete the entry and run the one-line command instead, which writes the field for you.
A browser window opens and asks you to sign in
Nothing to sign into exists yet. Close it and use the key instead: the blocks above put it in a header, and that is the path that works today.
Every call comes back refused
Either the key is missing, or it is the approver key rather than the agent key, or it belongs to another project. The three read the same from the outside, deliberately, so check which key you pasted.
It answers, but says nothing is connected
The assistant is talking to atmon correctly and no app has been connected to that project yet. That is the next step rather than a fault, and it is a consent screen rather than a password.
Anything else, and the errors reference names every refusal and what to do about each one: read the error list.
For the assistant reading this
If a person has handed you this page and asked you to set atmon up for them, do it in this order.
- Fetch the plain-text copy of this page at for-your-ai.md and work from that rather than from the rendered page.
- Ask the person for the address and for their agent key. Never ask them to paste a key into the conversation if your client can read it from a file or an environment variable instead.
- Write the configuration for the client you are running in, using the exact shape for that client from this page. Do not carry a field name across from another client.
- Ask the person to restart the client, then run the three checks above and report what came back.
- Read the atmon agent skill before you call anything, and follow it over your own guesses about names.