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

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 canTools
See your workspaces and appsme, list_workspaces, get_workspace, list_apps, get_app, list_templates
Read an app's code and historylist_files, read_file, get_diff, list_functions, get_function
Read an app's data structure and run SQLlist_tables, describe_table, list_migrations, data_rules, query, list_extensions
Check how an app is doinglogs, advisors, app_analytics
Follow and steer your chats with Ahamo's AIlist_chats, list_turns, get_turn, send_message, approve_plan
Start a new appcreate_app
Propose changesedit_file, write_file, write_function, propose_migration, propose_data_rule, set_variable, upload_file, set_skill, set_knowledge
Publish or download an apppublish, export
Look things up in this documentationsearch_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_message never approves a plan; approve_plan builds 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/mcp

Clients 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:

  1. Sign in to your organisation's Ahamo.
  2. Open Account settings › AI clients.
  3. 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 addressWhat it does
?read_only=falseLets the connection make changes in development. You also tick Let it make changes in development when you sign in
?environment=productionReads production by default (logs, tables, SQL). The connection is then read-only
?app_id= and the app's idLimits 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

  1. In a terminal, add Ahamo:

    claude mcp add --transport http ahamo https://mcp.ahamo.ai/mcp

    To 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"
  2. Start Claude Code, type /mcp, choose ahamo and select Authenticate. Your browser opens Ahamo's sign-in.

  3. After you select Allow, return to the terminal. /mcp shows ahamo as connected.

Choose where Claude Code keeps the server with --scope (or -s):

ScopeWhere Ahamo is available
local (the default)Only you, in the current project
projectEveryone who opens the project, because Claude Code writes it to .mcp.json in the project, which you can commit
userOnly you, in every project

For example, to have Ahamo in every project:

claude mcp add --transport http --scope user ahamo https://mcp.ahamo.ai/mcp

A 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.

  1. Open Customize › Connectors, select + Add and choose Add custom connector.
  2. Enter the name Ahamo and the address https://mcp.ahamo.ai/mcp (or the address with ?read_only=false), then select Continue.
  3. 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.
  4. Sign in to Ahamo in the window that opens and select Allow.
  5. 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

  1. Open ~/.cursor/mcp.json to have Ahamo in every project, or .cursor/mcp.json in one project.

  2. Add Ahamo:

    {
      "mcpServers": {
        "ahamo": {
          "url": "https://mcp.ahamo.ai/mcp"
        }
      }
    }
  3. 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

  1. Create .vscode/mcp.json in your project, or run MCP: Open User Configuration from the Command Palette to have Ahamo in every project.

  2. Add Ahamo. VS Code uses servers, not mcpServers:

    {
      "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"}'
  3. Start the server. On the first connection VS Code opens Ahamo's sign-in in your browser; select Allow.

  4. Use Ahamo's tools from the chat in agent mode.

VS Code's MCP configuration reference (opens in a new tab)

Windsurf (Devin Desktop)

  1. In the Cascade panel, open the … menu and, under MCPs, open the MCP configuration file (~/.config/devin/mcp_config.json on macOS and Linux, %APPDATA%\devin\mcp_config.json on Windows).

  2. Add Ahamo:

    {
      "mcpServers": {
        "ahamo": {
          "serverUrl": "https://mcp.ahamo.ai/mcp"
        }
      }
    }
  3. 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

  1. Add Ahamo to ~/.codex/config.toml:

    [mcp_servers.ahamo]
    url = "https://mcp.ahamo.ai/mcp"
  2. Sign in:

    codex mcp login ahamo

    Your browser opens Ahamo's sign-in; select Allow. codex mcp list shows 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.

  1. Sign in to Ahamo if you aren't already, with the account you build with.
  2. Check the client's name. Unverified app means the client chose its own name, so allow it only if you started this connection yourself.
  3. Under Apps it may use, keep Every App I can open or choose one app.
  4. If the address asked for changes, tick Let it make changes in development, or leave it unticked to read only.
  5. 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 ahamo also 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

FreeProTeamEnterprise
Connect AI clientsYesYesYesYes, as your organisation allows
Service credentials——YesYes, as your organisation allows
LimitValue
Calls120 a minute per person, across all their clients
Sign-in lasts1 hour, renewed for up to 90 days
SQL through queryOne statement, 10 seconds, 500 rows
Reading a file2 MB
Uploading a file10 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/mcp

Use -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.

On this page