Skip to content

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.

Terminal window
claude mcp add --transport http alethman https://dash.alethman.com/api/mcp \
--header "Authorization: Bearer alm_live_YOUR_KEY"
  • Add --scope user to have Alethman in every project, not only this one.
  • Inside Claude Code, run /mcp to check it is connected and see its tools.
  • To remove it: claude mcp remove alethman.

Claude Desktop reaches a remote server that takes a Bearer key through the mcp-remote bridge, which needs Node.js 18 or later.

  1. Open Settings › Developer › Edit Config. This opens claude_desktop_config.json.

  2. 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"
    }
    }
    }
    }
  3. 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.

In ~/.cursor/mcp.json for every project, or .cursor/mcp.json in one project:

~/.cursor/mcp.json
{
"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).

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.

You can talk to the server without a client, which is the quickest way to tell a key problem from a client problem:

Terminal window
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"}'
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.