---
title: "Speak AI MCP server authentication and rate limits"
description: "How to get a Speak AI API key, pass it to the MCP server, exchange it for REST tokens yourself, and read the rate limits and tool error format."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://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](https://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](/mcp) 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:**

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

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

**Step 2, use the token on every subsequent request:**

```bash
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:**

```bash
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"}'
```

| Token | Expiry | How to renew |
|---|---|---|
| Access token | 80 minutes | Refresh endpoint, or re-authenticate |
| Refresh token | 24 hours | Re-authenticate with your API key |

## 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.

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

| Code | Meaning |
|---|---|
| `401` | Invalid or missing API key or access token |
| `403` | Insufficient permissions |
| `404` | Resource not found |
| `429` | Rate limit exceeded |

## Related guides

- [MCP server overview](/mcp)
- [Connect your AI tool](/mcp)
- [Node SDK](/sdk)

Source: https://docs.speakai.co/mcp/authentication/index.mdx