OpenAI and tool platforms
Add Amdahl as a remote MCP tool in OpenAI's built-in tools, LangSmith, or any platform that hosts models and calls MCP servers for them
Model platforms — the OpenAI Playground and Responses API, LangSmith, agent frameworks with a "remote MCP server" tool type — call Amdahl server-to-server on your behalf. There is no browser in that loop, so the OAuth flow desktop clients use does not apply: these platforms authenticate with an Amdahl API key sent as a bearer token.
Every setup below is the same three facts in that platform's syntax:
| Fact | Value |
|---|---|
| Server URL | https://app.amdahl.ai/mcp |
| Transport | Streamable HTTP |
| Auth | Authorization: Bearer $AMDAHL_KEY (an amdhl_... API key) |
Create the key with amdahl keys create --name "OpenAI" --preset agent and
approve it in the console (see Command line (CLI)),
or in the console under Settings, then Developer, then Create key. It is
shown once. Store it in the platform's secret manager, never in a shared prompt
or a config you would paste into a ticket.
The platform's model calls Amdahl with this key on every run, from their
infrastructure. Give it the narrowest access that covers the job: Read only (--preset read-only) for a model that should only query, Customer agent (--preset agent) when it should also start chats, evaluate or rewrite drafts, or write.
Give it an expiry date too, so a forgotten key stops working on its own. See
Authentication for what each bundle reaches.
OpenAI built-in tools
In the OpenAI Playground, add a tool, choose OpenAI built-in, then MCP,
and fill in the config. The same JSON block works in the Responses API's
tools array:
{
"type": "mcp",
"server_label": "amdahl",
"server_url": "https://app.amdahl.ai/mcp",
"authorization": "$AMDAHL_KEY"
}The authorization value reaches Amdahl as an Authorization: Bearer header,
which is exactly how an amdhl_... key authenticates — paste the bare key,
with no Bearer prefix of your own.
Two knobs worth setting:
- Secrets. In the Playground, reference a workspace secret instead of
pasting the key inline:
"authorization": "{{AMDAHL_KEY}}"(create the secret under Manage Secrets). In API calls, interpolate it from your own environment. - Tool scoping. Amdahl exposes one tool per operation, each named for what it
does (see Connect your agent for the full
list). A
get_orlist_tool only reads and changes nothing. A tool that starts a job or makes a change may need approval. If the platform supports an allowed-tools list,["search_customers"]alone gives the model fast read-only lookups and starts a research job withroute: "research"; addget_researchto read the job's cited answer,optimize_messageto write or evaluate outbound messages, andoptimize_promptandget_prompt_runto evaluate or improve a prompt. A job starts on one tool and is read on itsget_tool, so allow both.
OpenAI's MCP tool also takes a require_approval setting. search_customers with a
read-only key is safe to run unattended; keep approval on for optimize_message
and optimize_prompt when the key can write.
Tool hints
tools/list returns each tool with a display title and all four MCP
annotations set explicitly, so a platform that reads them can decide which
calls need approval without a list of its own. annotations.title repeats the
same title for a client that reads it there. The table of every tool's title
and hints is in Connect your agent.
Each hint describes one operation. A tool is marked destructive when it removes
or overwrites something stored (an update_, delete_ or disconnect_ tool,
or reconnect_connection), or when it stops work in progress
(cancel_research). The hints are advice for the
client; the key's scopes and the user's role still decide what each call may do.
LangSmith and other platforms
Any platform with a remote MCP tool type takes the same three facts. In
LangSmith's Playground, add a tool, choose MCP, and fill in the server URL
and an authorization (or headers) field the same way; reference the key
through the platform's secret syntax where one exists.
Where the platform asks for raw headers instead of an authorization field, either form works identically. These headers are for server-to-server use only; a desktop client (Claude, Cursor, Codex) signs in over OAuth with the URL alone and needs no header:
Authorization: Bearer $AMDAHL_KEYX-API-Key: $AMDAHL_KEYThe workspace the key was minted in is the workspace the model sees — nothing else.
Good to know
-
Rate limit. Production counts calls per credential and per minute by cost: 300 reads, 30 expensive calls (optimize, evaluation, prompt run, research start), 60 other writes, and 600 protocol messages. A platform fanning out many parallel tool calls can hit one; the response is a plain HTTP 429, and spacing calls out resolves it. See Rate limits.
-
Request size. Tool-call bodies over 1 MB are rejected.
-
Sessions. MCP sessions expire after 2 hours idle. A stateless caller that reuses an old session id gets a JSON-RPC
-32000error: reinitialize and replay once, never retry in a loop. Details in Reliability and retries. -
Check the setup. Have the model call the
get_setup_statustool, which takes no arguments. It names the workspace the key acts in, the role of the person who created it, and whether drafts can be optimized, with the reason when they cannot. See Check your setup. -
Verify it works. Ask the model something only your workspace can answer ("what do customers say about onboarding?") — a generic web answer means the tool is not being called; a quote-backed answer means it is.
-
Add the docs server as a second tool. These platforms are tools-only — the model cannot follow a documentation link you put in a prompt. Attaching
https://docs.amdahl.ai/mcpalongside the one above lets it read the docs itself. Same shape, minus the auth block, because that server is public:json{ "type": "mcp", "server_label": "amdahl_docs", "server_url": "https://docs.amdahl.ai/mcp", "require_approval": "never" }
See also
- Read the docs over MCP — the public documentation server these platforms can attach without a key.
- Connect your agent (MCP) — desktop clients (Claude, Cursor), every tool in detail, and the headless curl.
- Authentication — key bundles and what each one reaches.
- Tool catalog — every operation, its scopes, and its required role.