Speak AI MCP server authentication and rate limits

You need a Speak AI API key for any setup that isn’t OAuth. Create one at app.speakai.co/developers/apikeys.

How do you get a Speak AI API key?

Speak AI API keys are created and managed at app.speakai.co/developers/apikeys. Use the same key for OAuth’s manual alternative, Bearer token setups, stdio mode’s SPEAK_API_KEY environment variable, and the CLI.

How is the API key passed to the MCP server?

The MCP server accepts the key two ways: automatically, when a client connects with OAuth 2.1 and Dynamic Client Registration, or directly, as a Bearer token in the Authorization header.

• OAuth one-click: paste https://api.speakai.co/v1/mcp into your client, click Allow on the consent popup. No key handling required.
• Bearer token: send Authorization: Bearer <your-speak-api-key> on requests to https://api.speakai.co/v1/mcp, or set SPEAK_API_KEY as an environment variable for stdio mode and the CLI.

See Connect your AI tool for the exact steps and config per client.

How does REST authentication work if you call the API directly?

The MCP server and CLI manage tokens automatically. Calling the REST API directly means exchanging your API key for an access token yourself, in three steps.

Step 1, get an access token:

curl -X POST https://api.speakai.co/v1/auth/accessToken \
  -H "Content-Type: application/json" \
  -H "x-speakai-key: YOUR_API_KEY"

{
  "data": {
    "email": "you@example.com",
    "accessToken": "eyJhbG...",
    "refreshToken": "eyJhbG..."
  }
}

Step 2, use the token on every subsequent request:

curl https://api.speakai.co/v1/media \
  -H "x-speakai-key: YOUR_API_KEY" \
  -H "x-access-token: ACCESS_TOKEN_FROM_STEP_1"

Step 3, refresh before the access token expires:

curl -X POST https://api.speakai.co/v1/auth/refreshToken \
  -H "Content-Type: application/json" \
  -H "x-speakai-key: YOUR_API_KEY" \
  -H "x-access-token: CURRENT_ACCESS_TOKEN" \
  -d '{"refreshToken": "REFRESH_TOKEN_FROM_STEP_1"}'

What are the rate limits?

Speak AI enforces 5 requests per 30 seconds on both authentication endpoints, /v1/auth/accessToken and /v1/auth/refreshToken.

For everything else, the MCP client automatically retries on 429 with exponential backoff. If you’re calling the REST API directly, implement exponential backoff yourself and respect the Retry-After header.

What does an error look like?

Every Speak AI MCP tool error follows the same structure, so an agent can parse it without special-casing each tool.

{
  "content": [{ "type": "text", "text": "Error: HTTP 401: Invalid API key" }],
  "isError": true
}

Related guides

• MCP server overview
• Connect your AI tool
• Node SDK