Skip to main content

Troubleshooting MCP & CLI

Fix common issues with the Speak AI MCP server and CLI: wrong env var name, endpoint confusion, authentication errors, Node.js version, and connection problems.

Written by Speak Ai

Troubleshooting MCP & CLI

Most MCP and CLI issues come from one of four causes: wrong environment variable name, wrong endpoint URL, invalid or expired API key, or a Node.js version issue. Start here.

Quick checklist

  1. API key valid? Check at app.speakai.co/developers. Regenerate if needed.

  2. Correct env var name? The required variable is SPEAK_API_KEY — not SPEAKAI_API_KEY. Some older guides show the wrong name.

  3. Correct MCP endpoint? Use https://api.speakai.co/v1/mcp for HTTP transport (Claude Desktop, Cursor, VS Code). Use https://mcp.speakai.co/mcp for one-click integrations (Claude.ai, ChatGPT).

  4. Node.js 18+? Run node --version. If below 18, update Node.js first.

Claude Desktop: "MCP server failed to start"

  • Check claude_desktop_config.json for valid JSON — no trailing commas

  • Confirm SPEAK_API_KEY is in the "env" block, not as a shell variable

  • Test the package manually: npx -y @speakai/mcp-server in your terminal

  • Try pinning a version: "args": ["-y", "@speakai/mcp-server@latest"]

Claude.ai / ChatGPT: "Authorization failed"

  • Re-copy your API key fresh from the dashboard and re-enter it in the integration settings

  • Check there are no spaces before or after the key

CLI: "command not found: speakai-mcp"

  • Reinstall: npm install -g @speakai/mcp-server

  • Verify npm global bin is in your PATH: npm bin -g

Tools not appearing in Claude / ChatGPT

  • Disconnect and reconnect the integration in your client's settings

  • Verify the MCP URL is correct and reachable

  • Try the Claude Code CLI as an alternative: claude mcp add --transport http speakai https://api.speakai.co/v1/mcp --header "Authorization: Bearer $SPEAK_API_KEY"

"Unauthorized" after it was working

Access tokens refresh automatically — you don't need to regenerate your API key for normal token expiry. If you see persistent auth errors, regenerate your key at app.speakai.co/developers and update your config.

Upload succeeded but transcript is empty

Processing takes 1–5 minutes after upload. If get_transcript returns empty, check the file's status first with get_media_status — it should show complete before the transcript is available. If status is still processing, wait and retry. If status shows failed, try re-transcribing with reanalyze_media and specify the correct language if the audio is not in English.


​

Still stuck? Chat with us below or email [email protected].

Related Articles
Setting Up the Speak AI MCP Server
Getting Started with Claude
Getting Started with Cursor, VS Code & Windsurf
Using the Speak AI CLI
Did this answer your question?