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

# Limits & errors

> Rate limits, credits, size limits, protocol details and error responses for the Evermuse MCP server.

## Rate limits

| Scope | Limit |
| - | - |
| MCP requests per OAuth access token | 1,000 per hour |
| MCP requests per API key | 1,000 per hour |
| Dynamic Client Registration | 10 per hour per IP address |
| Authorization code exchange | 20 per hour per client and IP address |
| Token refresh | 60 per hour per client |
| All requests from one IP address | 2,000 per minute |

When a limit is reached, the server responds with HTTP `429` and a body that says how long to wait:

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests",
  "retry_after": 1200
}
```

`retry_after` is in seconds. Requests authenticated with an API key return `{"error": "Rate limit exceeded",
"retryAfter": 1200, "remaining": 0}` instead, and the per-IP limit returns `{"msg": "…", "retryAfterSeconds": 30, …}`.
Wait the indicated time before retrying.

## Credits

Evermuse MCP access is included with your Evermuse workspace and is metered in **Evermuse Credits**:

* Each **successful** tool call uses **1 credit**.
* `find_skills` and `read_skills` are free.
* Calls that fail aren't charged.
* Sources you add with `add_source` also use credits when Evermuse processes them, the same as uploads in the app.
  Re-submitting a meeting or communication that already exists isn't processed again.

New workspaces include free credits so you can try Evermuse. Workspaces on a paid plan keep working past their included
credits and are billed for additional usage under their plan. Your workspace's credit usage is shown in the Evermuse
app.

If a workspace without an active plan runs out of credits, tools return this error (skills tools keep working):

```text theme={null}
Error: MCP access is paused: this workspace has no Evermuse Credits remaining and no active plan.
```

## Size limits

| Limit | Value |
| - | - |
| Request body | 75 MB (to allow base64-encoded files) |
| File upload through `add_source` | About 50 MB before base64 encoding |
| Transcript or message text per `add_source` call | 4 MB |
| Results per page, search-shaped tools (with guidance) | About 30,000 characters of items, plus guidance |
| Results per page, search-shaped tools (without guidance) | About 80,000 characters |
| `read_source` page | Up to 500 segments or about 60,000 characters |
| Items per `add_signals` or `update_signals` call | 100 |

When a page is trimmed to fit, the result reports `next_offset`. Call the tool again with `offset` set to that value to
continue.

## Protocol details

| Property | Value |
| - | - |
| Endpoint | `POST https://api.evermuse.com/api/mcp` |
| Transport | Streamable HTTP, stateless. Each request is independent, and responses are JSON (no SSE stream). |
| Protocol versions | `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07` |
| Required headers | `Content-Type: application/json` and `Accept: application/json, text/event-stream` |
| Sessions | None. The server doesn't issue an `Mcp-Session-Id`, and each request is independent. |
| Server features | Tools and prompts. Resources (MCP Apps UI) only for early-access tools. |
| Not supported | `GET` (SSE streams) and `DELETE` (session termination) return `405`. Server-initiated requests such as sampling and elicitation aren't used. |

## HTTP errors

| Status | When | Body |
| - | - | - |
| `400` | Malformed JSON-RPC, or an unsupported `MCP-Protocol-Version`. | JSON-RPC error |
| `401` | No credentials. Includes `WWW-Authenticate: Bearer resource_metadata="…"`. | `{"error":"Unauthorized","error_description":"Authentication required. …"}` |
| `401` | Invalid, expired or revoked access token, or the user no longer belongs to the workspace. | `{"error":"invalid_token","error_description":"Access token expired"}` (or a similar description) |
| `401` | Missing or invalid API key. | `{"error":"Invalid API key"}` |
| `403` | API key without MCP permissions. | `{"error":"API key does not have mcp permissions"}` |
| `405` | `GET` or `DELETE` on the MCP endpoint. | JSON-RPC error `-32000` |
| `406` | `Accept` header missing `application/json` or `text/event-stream`. | JSON-RPC error |
| `413` | Request body larger than 75 MB. | Error response |
| `415` | `Content-Type` isn't `application/json`. | JSON-RPC error |
| `429` | Rate limit exceeded. | See [Rate limits](#rate-limits) |
| `500` | Unexpected server error. | JSON-RPC error `-32603` |

On a `401` with `invalid_token`, clients should refresh the access token and retry once. If the refresh fails, sign in
again.

## Tool errors

Problems with a specific tool call are returned as a normal MCP result with `isError: true` and a message the agent can
act on, rather than an HTTP error. Common examples:

| Message | Meaning and fix |
| - | - |
| `product_id is required. Call get_products …` | The tool needs a product. Call `get_products` and pass a `product_id`. |
| `Product not found: "…" is not a product in this workspace. …` | The id is wrong or belongs to another workspace. |
| `Project not found or access denied` | The `project_id` isn't a project in this workspace. |
| `Source not found or access denied` | The source id is wrong or outside your workspace. |
| `This source has no content yet (still processing?)` | The source was added recently. Try again later. |
| `… does not exist or you are not allowed to access it` | `view_item` couldn't find the item. Check `item_id` and `item_type`. |
| `Tool "…" is not available on this connection.` | The tool needs a scope the connection doesn't have, such as `mcp:write` for signal writes. Reconnect to grant it. |
| `Tool "…" is not available for this workspace.` | The workspace stores its data locally (Evermuse Desktop). See [Troubleshooting](/mcp/troubleshooting#local-storage-workspaces). |
| `MCP access is paused: …` | The workspace is out of credits. See [Credits](#credits). |
| `Unknown signal type "…"` | `add_signals` received a type that isn't active in your workspace. |

Removed or renamed tools return a message explaining the change, naming a replacement where one exists. For example, `see_updated_roadmap` points to
`get_opportunities`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.