Connect a client
You need an API key made under Settings › API keys by an owner or admin, with the scopes you want the assistant to have (Authentication). Below, replace alm_live_YOUR_KEY with it.
Claude Code
Section titled “Claude Code”claude mcp add --transport http alethman https://dash.alethman.com/api/mcp \ --header "Authorization: Bearer alm_live_YOUR_KEY"- Add
--scope userto have Alethman in every project, not only this one. - Inside Claude Code, run
/mcpto check it is connected and see its tools. - To remove it:
claude mcp remove alethman.
Claude Desktop
Section titled “Claude Desktop”Claude Desktop reaches a remote server that takes a Bearer key through the mcp-remote bridge, which needs Node.js 18 or later.
-
Open Settings › Developer › Edit Config. This opens
claude_desktop_config.json. -
Add Alethman under
mcpServers:claude_desktop_config.json {"mcpServers": {"alethman": {"command": "npx","args": ["-y","mcp-remote","https://dash.alethman.com/api/mcp","--header","Authorization:${AUTH_HEADER}"],"env": {"AUTH_HEADER": "Bearer alm_live_YOUR_KEY"}}}} -
Save and restart Claude Desktop. Alethman’s tools appear under the tools icon in a new chat.
The header goes through an environment variable, with no space after Authorization:, because Claude Desktop on Windows does not escape spaces inside args. This form works on every platform.
Cursor
Section titled “Cursor”In ~/.cursor/mcp.json for every project, or .cursor/mcp.json in one project:
{ "mcpServers": { "alethman": { "url": "https://dash.alethman.com/api/mcp", "headers": { "Authorization": "Bearer alm_live_YOUR_KEY" } } }}The MCP section of Cursor’s settings shows it as connected, with eleven tools (fewer if the key lacks some scopes).
Any other client
Section titled “Any other client”Configure it as a Streamable HTTP server:
| Setting | Value |
|---|---|
| URL | https://dash.alethman.com/api/mcp |
| Header | Authorization: Bearer alm_live_YOUR_KEY |
| Transport | Streamable HTTP (POST); no SSE stream is needed |
A client that can only sign in with OAuth and cannot send a custom header cannot use a key directly yet. Where the client can run a local command, use mcp-remote as in the Claude Desktop config above.
Check it with curl
Section titled “Check it with curl”You can talk to the server without a client, which is the quickest way to tell a key problem from a client problem:
curl -s https://dash.alethman.com/api/mcp \ -H "Authorization: Bearer $ALETHMAN_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'curl -s https://dash.alethman.com/api/mcp \ -H "Authorization: Bearer $ALETHMAN_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_stories","arguments":{"order":"risk","limit":5}}}'When it does not connect
Section titled “When it does not connect”| What you see | Likely cause | Fix |
|---|---|---|
| Client says unauthorised, or curl answers 401 | Key mistyped, revoked or expired; or no Bearer before it |
Check the key under Settings › API keys; in Claude Desktop, check AUTH_HEADER starts with Bearer . |
| Connected, but fewer than eleven tools | The key lacks some scopes | Tools appear only for the key’s scopes. Make a key with the ones you want. |
| A tool answers “This key does not carry the … scope” | As above, for that tool | As above. |
| 409, “This workspace has not been set up yet” | The workspace’s setup walkthrough is unfinished | An owner or admin finishes it in the dashboard. |
| 405 | The client opened a GET event stream | The server is POST only and stateless. Choose Streamable HTTP, not the older SSE transport. |
| Claude Desktop shows nothing after restart | Node.js missing, or the JSON does not parse | Run npx -y mcp-remote --help in a terminal; validate the config file. |
| Answers stop for a minute | The key’s 120 requests a minute are used | Wait for the minute; give the assistant its own key. |