AI clients and agents
Connect Claude, Cursor or another AI client to Ahamo
Add Ahamo to Claude Code, Claude, Cursor, VS Code or another MCP client, sign in as you, and build, inspect and publish your apps.
On this page
- When to use it
- What it can and can't do
- Ahamo's address
- If your organisation has its own Ahamo address
- Choose what the connection may do
- Set up your client
- Claude Code
- Claude (claude.ai and the desktop app)
- Cursor
- VS Code
- Windsurf (Devin Desktop)
- Codex CLI
- Another MCP client
- Sign in
- Try it
- Security and permissions
- Plans and limits
- Troubleshooting
Ahamo is an MCP server. Connect the AI assistant you already use, such as Claude Code, Claude, Cursor or VS Code, and it can work on your Ahamo apps from there, to list them, read their code, data structure and logs, start new apps, send messages to an app's chat, and publish. It signs in as you, in your browser, and does only what you could do in Ahamo yourself.
Availability. On by default on ahamo.ai, for every plan. An organisation's own Ahamo starts with it off; its administrator can allow it, allow reading only, or turn it off again under Rules › People's own AI clients. Service credentials for unattended agents need the Team plan or higher.
When to use it
- You work in your own AI tool and want it to know your Ahamo app without copying code or logs across.
- A coding agent should check an app's errors, read its code or propose a change.
- You want to start or steer an app's build from your editor or terminal, and approve it in Ahamo.
For an agent that runs on its own, such as a nightly job, use a service credential instead of signing in.
What it can and can't do
A connected client gets Ahamo's tools. The full list is in AI client tools; in short:
| It can | Tools |
|---|---|
| See your workspaces and apps | me, list_workspaces, get_workspace, list_apps, get_app, list_templates |
| Read an app's code and history | list_files, read_file, get_diff, list_functions, get_function |
| Read an app's data structure and run SQL | list_tables, describe_table, list_migrations, data_rules, query, list_extensions |
| Check how an app is doing | logs, advisors, app_analytics |
| Follow and steer your chats with Ahamo's AI | list_chats, list_turns, get_turn, send_message, approve_plan |
| Start a new app | create_app |
| Propose changes | edit_file, write_file, write_function, propose_migration, propose_data_rule, set_variable, upload_file, set_skill, set_knowledge |
| Publish or download an app | publish, export |
| Look things up in this documentation | search_docs, read_doc |
What it can't do:
- Change production directly. Production is never writable through an AI client. Production changes only when the app is published, with the same security checks and approvals as in Ahamo.
- Skip your review. Every change becomes a pending change in the app's chat, checked like any other.
send_messagenever approves a plan;approve_planbuilds only the plan you were shown. - Read secrets. It sees secret names, never values. When an app needs a secret, the client gives you a link where you enter it in Ahamo yourself.
- Read data the app keeps from AI. Logs, the Files library and SQL follow the app's AI access setting for each environment.
- Go beyond your access. It sees and does only what your role allows, in the apps you chose when you signed in.
What it costs. Reading is free. Tools that start Ahamo's AI spend your workspace's credits exactly like the
chat, such as create_app, send_message, approve_plan, and the change proposals that Ahamo's AI carries out
(edit_file, write_file, write_function, propose_migration, propose_data_rule).
Ahamo's address
On ahamo.ai, add this address to your AI client:
https://mcp.ahamo.ai/mcpClients you connected earlier keep working at the address they were given.
If your organisation has its own Ahamo address
An organisation with its own Ahamo, at its own address, connects AI clients to that address, not to
mcp.ahamo.ai. mcp.ahamo.ai, and any ready-made Ahamo connector in an AI client's directory, sign you in to
ahamo.ai's own organisation, where your organisation's apps are not.
To find your organisation's address:
- Sign in to your organisation's Ahamo.
- Open Account settings › AI clients.
- Select Copy next to Ahamo's address for your AI client.
Use that address wherever this page shows https://mcp.ahamo.ai/mcp, with the same options, and add it as a
custom server or connector rather than from a directory.
There is no API key to paste. The first time the client connects, it opens Ahamo's sign-in in your browser (see Sign in).
Choose what the connection may do
A new connection reads only. Add options to the address to change that:
| Add to the address | What it does |
|---|---|
?read_only=false | Lets the connection make changes in development. You also tick Let it make changes in development when you sign in |
?environment=production | Reads production by default (logs, tables, SQL). The connection is then read-only |
?app_id= and the app's id | Limits the connection to one app, the same as choosing one app when you sign in |
Join two options with &, for example https://mcp.ahamo.ai/mcp?read_only=false&app_id=…. Most people need only
?read_only=false, because a client can still ask for production on each call, and choosing one app at sign-in is easier
than finding its id.
To change what an existing connection may do, connect again with the new address. Remove the client's entry and add it again (see Troubleshooting).
Set up your client
Pick your client. Each setup ends with the sign-in in your browser.
Claude Code
-
In a terminal, add Ahamo:
claude mcp add --transport http ahamo https://mcp.ahamo.ai/mcpTo let it make changes in development, quote the address, because of the
?:claude mcp add --transport http ahamo "https://mcp.ahamo.ai/mcp?read_only=false" -
Start Claude Code, type
/mcp, choose ahamo and select Authenticate. Your browser opens Ahamo's sign-in. -
After you select Allow, return to the terminal.
/mcpshows ahamo as connected.
Choose where Claude Code keeps the server with --scope (or -s):
| Scope | Where Ahamo is available |
|---|---|
local (the default) | Only you, in the current project |
project | Everyone who opens the project, because Claude Code writes it to .mcp.json in the project, which you can commit |
user | Only you, in every project |
For example, to have Ahamo in every project:
claude mcp add --transport http --scope user ahamo https://mcp.ahamo.ai/mcpA project .mcp.json holds only the address; each person signs in as themselves:
{
"mcpServers": {
"ahamo": {
"type": "http",
"url": "https://mcp.ahamo.ai/mcp"
}
}
}In Claude Code, claude mcp list shows whether ahamo is connected or needs sign-in, claude mcp get ahamo shows
its details, and claude mcp remove ahamo removes it with its sign-in. If you added Ahamo as a connector on claude.ai
and sign in to Claude Code with the same account, Claude Code may already list it.
Claude Code's guide to MCP (opens in a new tab)
Claude (claude.ai and the desktop app)
Claude adds Ahamo as a custom connector. It then works on claude.ai, in the desktop app and in the mobile apps.
- Open Customize › Connectors, select + Add and choose Add custom connector.
- Enter the name
Ahamoand the addresshttps://mcp.ahamo.ai/mcp(or the address with?read_only=false), then select Continue. - Keep the detected sign-in settings, select Continue, choose Sign in now and select Add. Leave the OAuth client fields empty, because Ahamo registers the client itself.
- Sign in to Ahamo in the window that opens and select Allow.
- In a chat, select + › Connectors and turn on Ahamo.
On a Team or Enterprise plan of Claude, an owner adds the connector once under Organization settings › Connectors › Add › Custom › Web. Each member then finds it under Customize › Connectors and selects Connect to sign in to Ahamo as themselves. Free Claude accounts can add one custom connector.
Claude's guide to custom connectors (opens in a new tab)
Cursor
-
Open
~/.cursor/mcp.jsonto have Ahamo in every project, or.cursor/mcp.jsonin one project. -
Add Ahamo:
{ "mcpServers": { "ahamo": { "url": "https://mcp.ahamo.ai/mcp" } } } -
Save the file. Cursor finds that Ahamo needs sign-in and opens Ahamo's sign-in in your browser; select Allow. No client id or secret is needed.
Cursor's guide to MCP (opens in a new tab)
VS Code
-
Create
.vscode/mcp.jsonin your project, or run MCP: Open User Configuration from the Command Palette to have Ahamo in every project. -
Add Ahamo. VS Code uses
servers, notmcpServers:{ "servers": { "ahamo": { "type": "http", "url": "https://mcp.ahamo.ai/mcp" } } }Or add it to your user configuration from a terminal:
code --add-mcp '{"name":"ahamo","type":"http","url":"https://mcp.ahamo.ai/mcp"}' -
Start the server. On the first connection VS Code opens Ahamo's sign-in in your browser; select Allow.
-
Use Ahamo's tools from the chat in agent mode.
VS Code's MCP configuration reference (opens in a new tab)
Windsurf (Devin Desktop)
-
In the Cascade panel, open the … menu and, under MCPs, open the MCP configuration file (
~/.config/devin/mcp_config.jsonon macOS and Linux,%APPDATA%\devin\mcp_config.jsonon Windows). -
Add Ahamo:
{ "mcpServers": { "ahamo": { "serverUrl": "https://mcp.ahamo.ai/mcp" } } } -
Save the file, turn Ahamo on in the MCPs section, and sign in to Ahamo when asked.
Devin Desktop's guide to MCP (opens in a new tab)
Codex CLI
-
Add Ahamo to
~/.codex/config.toml:[mcp_servers.ahamo] url = "https://mcp.ahamo.ai/mcp" -
Sign in:
codex mcp login ahamoYour browser opens Ahamo's sign-in; select Allow.
codex mcp listshows the server.
Codex's guide to MCP (opens in a new tab)
Another MCP client
Any client that supports remote MCP servers over HTTP (often called "Streamable HTTP") and OAuth sign-in works. Give it the address and leave client id, secret and headers empty, because the client finds Ahamo's sign-in from the address, registers itself and opens the sign-in in your browser. A client that can only start local programs, and cannot reach a remote address, cannot connect.
Sign in
When the client connects for the first time, your browser opens a page headed … wants to use Ahamo as you.
- Sign in to Ahamo if you aren't already, with the account you build with.
- Check the client's name. Unverified app means the client chose its own name, so allow it only if you started this connection yourself.
- Under Apps it may use, keep Every App I can open or choose one app.
- If the address asked for changes, tick Let it make changes in development, or leave it unticked to read only.
- Select Allow. The browser returns you to the client.
The client then lists Ahamo's tools. Ask it "Who am I in Ahamo?" and it answers with your name, your workspaces, and whether the connection reads only.
The sign-in renews itself for up to 90 days; after that the client asks you to sign in again.
Try it
Ask in your own words. The client picks the tools; the ones it is likely to use are shown after each prompt.
List your apps.
List my apps in the Marketing workspace.
list_workspaces, list_apps
Create an app.
Create an app in my Marketing workspace that lets my team book meeting rooms, with a weekly calendar and an email to the organiser. Show me the plan before it builds.
create_app starts the app and Ahamo's AI plans it; get_turn shows the plan. Reply "Build it" and the client
calls approve_plan. You can also open the app in Ahamo and choose Build this plan on the plan yourself.
Import a repository.
Import https://github.com/acme/room-booking (opens in a new tab) into Ahamo and answer its questions with me.
create_app with the repository, then get_turn and send_message for each question Ahamo's AI asks.
See what changed.
What changed in my room booking app since it was last published?
get_app for when it was last published, get_diff for the saved versions since then, and list_migrations for
what the next publish changes in the live database.
Find errors.
Show the recent errors in my room booking app's production logs and explain the most frequent one.
logs in production. Production logs need the app's AI access setting to allow production reads.
Query the data.
How many bookings were made this week? Query the development database.
list_tables, then query. Development is the default; production is read-only, and only while the app's AI
access setting allows it.
Change something.
In my room booking app, show the time in 24-hour format on the bookings page.
send_message to the app's chat, or edit_file for a small, exact change. Either way the change is a pending
change you can review in Ahamo.
Publish.
Publish my room booking app.
publish runs the same security checks as Ahamo's Publish. When your workspace requires approval, the client
answers that approval was requested, and someone who may approve does it in Ahamo. Nothing is published until then.
Ask about Ahamo.
How do I connect a custom domain to an Ahamo app?
search_docs and read_doc read this documentation.
Security and permissions
- It acts as you. Every call runs with your account, your role and your workspaces, under the same checks as in Ahamo. A connection limited to one app never reaches another.
- Production stays safe. Production data is never writable through an AI client; production changes only through publish, with its checks and approvals.
- Organisation rules come first. An organisation administrator chooses under Rules › People's own AI clients whether clients may Read and make changes in development, Read only, or are Off. Turning them off ends every connection at once.
- Each app decides about its data. Someone who manages an app chooses under Settings › AI access whether AI may read its development and production data.
- Disconnect any time. Account settings › AI clients lists every client you connected, with whether it
reads only, its app and when it was last used. Select Disconnect to end it at once. In Claude Code,
claude mcp remove ahamoalso removes the stored sign-in. - Connections end with your sign-in. Resetting your password or being signed out everywhere ends every AI client connection; sign in again from the client.
- Everything is recorded. Every call, including refused ones, is in your organisation's audit log.
- Results are data. Ahamo tells clients to treat what tools return as data from your account, never as instructions. Still, connect only clients you trust.
Plans and limits
| Free | Pro | Team | Enterprise | |
|---|---|---|---|---|
| Connect AI clients | Yes | Yes | Yes | Yes, as your organisation allows |
| Service credentials | — | — | Yes | Yes, as your organisation allows |
| Limit | Value |
|---|---|
| Calls | 120 a minute per person, across all their clients |
| Sign-in lasts | 1 hour, renewed for up to 90 days |
SQL through query | One statement, 10 seconds, 500 rows |
| Reading a file | 2 MB |
| Uploading a file | 10 MB, two at a time |
Troubleshooting
Claude Code says "MCP server ahamo already exists in local config". You added Ahamo before. Remove it and add it again:
claude mcp remove ahamo -s local
claude mcp add --transport http ahamo https://mcp.ahamo.ai/mcpUse -s user or -s project instead of -s local if you added it there.
The client asks you to sign in again and again. Remove Ahamo from the client and add it again, which clears its stored sign-in, then sign in once more. In the browser, make sure you sign in to the Ahamo account you build with; for an organisation's own Ahamo, use its own address, not ahamo.ai's.
You changed the address of an existing connection and the client finds no sign-in. Claude Code keeps using the
old address for a server of the same name until it restarts. After claude mcp remove ahamo and adding the new
address, quit and restart Claude Code, then /mcp › ahamo › Authenticate. Otherwise it signs in at the old
address and the reconnect finds no sign-in.
Old connections are still listed. Each sign-in is its own connection. Under Account settings › AI clients, select Disconnect on the ones you no longer use.
Calls fail with "unauthorized" (401) after a password reset or a sign-out everywhere. Those end every AI client
connection. Sign in again, in Claude Code with /mcp › ahamo › Authenticate.
"This connection is read-only…". Add ?read_only=false to the address, connect again, and tick Let it make
changes in development when you sign in. If the sign-in page says Your organisation lets AI clients read
only, ask your administrator.
"Production is read-only for AI clients…". By design. Make the change in development and publish.
"Your organisation turned off AI clients." An organisation administrator can turn them on under Rules › People's own AI clients.
The client works in the wrong workspace. Name the workspace in your prompt, or ask "List my workspaces" first. A connection limited to one app sees only that app's workspace, so connect again and choose Every App I can open.
"This connection is limited to another App." You chose one app when you signed in. Connect again and choose the app you need, or Every App I can open.
The app's data or logs are refused. The app doesn't let AI read that environment's data. Someone who manages the app can change it under Settings › AI access.
"Too many calls". Your clients together made more than 120 calls a minute. Wait a minute.