Docs

Connect your agent (MCP)

Point an AI assistant at your workspace over MCP, see the three tools it gets, and connect a headless client with an API key

MCP lets an AI assistant or agent use Amdahl on your behalf. In a desktop or web client you connect once and approve it in your browser, with no key to copy. A headless client — a backend service, a CI job, anything that cannot open a browser — connects with an API key instead, and there is a section for that below.

Building a plain script or backend service with no agent in it? You want the REST API and an API key, not MCP.

The server URL is:

code
https://app.amdahl.ai/mcp

What your agent gets

Amdahl exposes three tools. Each takes an action parameter rather than shipping a separate tool per operation, so your agent's context holds three tool definitions instead of dozens.

Two things follow from that packing, and both bite if you assume otherwise. An action is not always named after its REST operation — chat.start in the catalog is the start_chat action on the agents tool. And the MCP surface is not a complete mirror of the REST surface: a few operations, the bulk evals.export download among them, are REST-only. When an action you expect is missing, reach for the REST API.

Enable human confirmation for tools that write, and be careful when you run Amdahl alongside other MCP servers. A connected agent reads your customer conversations; treat anything it relays from that data as content, not as instructions.

ToolActionsWhat it is for
searchquery, fieldsOne routed door over your conversation warehouse — typed filters, plain-language NL-to-SQL, or meaning-based matching. See Search.
agentsstart_chat, chat_status, respond, cancel_chat, plus the agent library (list_agents, get_agent, create_agent, update_agent, delete_agent) and Routines (list_routines, get_routine, create_routine, update_routine, delete_routine, run_routine_now)The async lane: hand over a multi-step investigation, then poll. See Chat, Agents, Routines.
evalsrun, status, gate, evidence, drafts, improvement, list_runs, list, get, kpi, create, update, delete, validateGrade content against your own customer conversations. See Evals.

Per-operation detail — required scopes, required role, and the exact description your agent sees — is in the tool catalog. The catalog is generated from the same registry the server reads, so it cannot drift from what the tools actually do.

Your agent also gets resources it can read directly by URI (chat://, eval_run://, eval://, agent://, routine://, grader_kind://, search_field://) and a handful of prompts — canned starting points your client lists in its prompt menu, including system/guide_me, the guided walkthrough.

Connect a desktop or web client

Each of these signs in to your workspace over OAuth in the browser. There is no key to copy and nothing to store.

Claude (web and desktop)

  1. Open Settings, then Connectors (claude.ai/customize/connectors).
  2. Click Add custom connector.
  3. Name it Amdahl and set the URL to https://app.amdahl.ai/mcp.
  4. Click Connect, then Configure.
  5. Sign in to Amdahl when prompted, then choose this workspace.

Claude Code

bash
claude mcp add --transport http amdahl https://app.amdahl.ai/mcp

Then run /mcp inside Claude Code and complete the browser sign-in.

Cursor

Add the server to ~/.cursor/mcp.json (every project, just for you) or a project's own .cursor/mcp.json (that project, shared with whoever clones it):

json
{
  "mcpServers": {
    "amdahl": {
      "url": "https://app.amdahl.ai/mcp"
    }
  }
}

Any other client

MCP is an open standard, so any compliant client works. Point it at https://app.amdahl.ai/mcp over streamable HTTP and let it run the OAuth flow. The Amdahl cookbook carries worked setups and example agents.

Connecting from a model platform rather than a desktop client — OpenAI's built-in tools, LangSmith, an agent framework's remote-MCP tool type? Those call server-to-server with an API key instead of OAuth; see OpenAI and tool platforms.

The assistant only ever sees the workspace you choose, and only what your own account can do there.

Connect a headless client

A backend service, a scheduled job, or your own agent runtime cannot complete a browser sign-in. Those authenticate with an API key instead — the same amdhl_... key the REST API uses, sent as a bearer token:

bash
curl -s -X POST "https://app.amdahl.ai/mcp" \
  -H "Authorization: Bearer $AMDAHL_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": { "action": "query", "query": "what do customers say about onboarding?" }
    }
  }'

X-API-Key: $AMDAHL_KEY works identically. Mint the key in the console under Settings, then Developer, keep it server-side, and give it the narrowest permission bundle that covers what the agent needs — see Authentication for the bundles and what each one reaches.

Good to know

  • You are always in control. The agent can only do what your own account is allowed to do in that workspace.
  • A session you are using does not expire. If you are building your own client rather than using a ready-made one, read Reliability and retries — it covers what ends a session and the one retry that recovers from it.
  • New to Amdahl? Sign in at console.amdahl.ai, join your team's workspace or get added by an admin, then come back and connect.

See also