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

# Authentication

> How to authenticate with the MemContext API and MCP server.

## API key authentication

All public API requests require an API key sent in the `X-API-Key` header:

```bash theme={null}
curl https://api.memcontext.in/api/memories/search?query=... \
  -H "X-API-Key: mc_your_key"
```

Create API keys from the [MemContext dashboard](https://app.memcontext.in) under **Settings > API Keys**. Each key is bound to one workspace selected at creation, and API-key requests cannot override that workspace. Keys are prefixed with `mc_` and shown only once at creation - store them securely.

## MCP server authentication

The hosted MCP server at `https://mcp.memcontext.in/mcp` accepts the API key via HTTP headers. Both `MEMCONTEXT-API-KEY` and `X-API-Key` are supported:

```json theme={null}
{
  "mcpServers": {
    "memcontext": {
      "url": "https://mcp.memcontext.in/mcp",
      "headers": {
        "MEMCONTEXT-API-KEY": "mc_your_key"
      }
    }
  }
}
```

See [MCP Setup](/guides/mcp-setup) for configs specific to Claude Code, Cursor, OpenCode, and Codex CLI.

## Claude.ai / Claude Desktop connector authentication

For Claude.ai and Claude Desktop custom connectors, MemContext uses OAuth instead of manual API-key entry.

1. Open **Settings → Connectors** in Claude.
2. Add a custom connector with `https://mcp.memcontext.in/mcp`.
3. Click **Connect**.
4. Sign in to MemContext and approve the requested scopes.

This path is intended for everyday Claude usage. API-key headers and config files are only needed for coding-agent setups such as Claude Code, Cursor, OpenCode, and Codex CLI.

## Rate limits

MemContext rate-limits requests per endpoint using fixed 1-minute windows. Authenticated memory endpoint limits scale with the workspace plan:

| Plan     | Save memory | Search memories | Submit feedback |
| -------- | ----------- | --------------- | --------------- |
| Free     | 30/min      | 60/min          | 30/min          |
| Hobby    | 100/min     | 200/min         | 60/min          |
| Pro      | 300/min     | 600/min         | 120/min         |
| Ultimate | 1,000/min   | 2,000/min       | 300/min         |

API traffic may also be protected by a global abuse backstop of 3,000 requests per minute.

Rate-limited responses include headers to help you manage request timing:

| Header                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Remaining requests in the current window       |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets          |

When the limit is exceeded, the API returns `429 Too Many Requests`.

## Error responses

All errors follow a consistent JSON format:

```json theme={null}
{
  "error": "Human-readable error message",
  "code": "HTTP_429",
  "requestId": "abc123xyz456"
}
```

| Field       | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `error`     | What went wrong                                                                   |
| `code`      | Machine-readable error code (e.g. `HTTP_401`, `HTTP_404`, `INTERNAL_ERROR`)       |
| `requestId` | Unique request ID, also returned in the `X-Request-Id` response header            |
| `errorId`   | Unique error reference for support (only on server errors, format `ERR_XXXXXXXX`) |

Common error codes:

| Code             | Status | Meaning                                |
| ---------------- | ------ | -------------------------------------- |
| `HTTP_401`       | 401    | Missing or invalid API key             |
| `HTTP_403`       | 403    | Memory limit exceeded for current plan |
| `HTTP_404`       | 404    | Memory not found                       |
| `HTTP_429`       | 429    | Rate limit exceeded                    |
| `INTERNAL_ERROR` | 500    | Unexpected server error                |

## Request limits

| Constraint                  | Value             |
| --------------------------- | ----------------- |
| Max request body size       | 50 KB             |
| Max memory content length   | 10,000 characters |
| Max search query length     | 1,000 characters  |
| Max feedback context length | 1,000 characters  |

## Best practices

* Create a separate API key per integration or environment
* Keep API keys server-side - never expose them in client-side code
* Rotate keys immediately if you suspect exposure
* Use `scope` as the hard isolation boundary when one API key serves multiple app users or tenants
* Use `project` only as a secondary grouping/filter inside that scope