> ## Documentation Index > Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Common issues and solutions for Tiro MCP Server Most MCP setup issues fall into three buckets: the auth header, the transport, and the client cache. Work through these in order — restart the client between steps so it actually re-reads the config. ## Connection Issues ### Server Not Found Verify the MCP server URL is correct: `https://mcp.tiro.ooo/mcp` Common mistakes: * Missing `/mcp` path suffix * Using `http://` instead of `https://` Test connectivity: ```bash theme={"system"} curl https://mcp.tiro.ooo/mcp ``` Expected response: `405 Method Not Allowed` (this is normal for a GET request). ### Tools Not Appearing 1. Completely restart your MCP client (not just a window refresh) 2. Ask your AI: "List all available MCP servers" — verify Tiro appears 3. If still missing, re-run the [client setup](/en/developers/mcp/setup) ## Authentication Errors ### API Key Issues **Invalid API Key Format** API Keys must follow the `{id}.{secret}` format (two parts separated by a dot). Common mistakes: * Copying only part of the key (missing the portion before or after the dot) * Extra whitespace or newline characters in the key * Using a placeholder value instead of a real key ```bash theme={"system"} # Correct format TIRO_API_KEY=abc123.xyz789secretvalue # Wrong — missing the dot separator TIRO_API_KEY=abc123xyz789secretvalue ``` **Expired or Revoked Key** API Keys can expire or be revoked from the Tiro Dashboard. If you receive a `401 UNAUTHORIZED` error with an API key you previously used: 1. Go to [Tiro Platform API Keys](https://platform.tiro.ooo/dashboard/api-keys) 2. Verify the key is still active — generate a new one if needed 3. Update your MCP client configuration with the new key ### 401 Unauthorized / 403 Forbidden **With API Key:** Verify your key is valid, not expired, and has the required scopes for the tool you are calling. See the [Setup page](/en/developers/mcp/setup) for the full scopes table. **With OAuth:** Restart your MCP client to trigger a fresh OAuth flow. * **Claude Code**: Restart the CLI session * **Claude Desktop**: Fully quit and relaunch the app * **Cursor**: Restart the editor or reload the MCP extension * **VS Code**: Restart the editor or reload the MCP extension OAuth automatically issues a new token with the correct scopes. Tokens are valid for **180 days**. ## Configuration Issues ### Claude Code Fails to Connect 1. Verify your config matches the [Claude Code setup](/en/developers/mcp/setup) 2. Restart the CLI session 3. If using OAuth and the browser window doesn't open, check your default browser settings 4. If using an API Key, ensure the key value has no trailing whitespace ### Claude Desktop Fails to Connect 1. Verify your config matches the [Claude Desktop setup](/en/developers/mcp/setup) 2. Validate JSON syntax — check for missing commas, unmatched brackets, or missing quotes ([JSONLint](https://jsonlint.com/)) 3. Ensure [Node.js](https://nodejs.org/) is installed (`npx` must work in your terminal) 4. Fully quit and restart Claude Desktop (Cmd+Q on macOS, not just close window) ### Cursor Fails to Connect 1. Verify your MCP server configuration in Cursor settings 2. Ensure the server URL is `https://mcp.tiro.ooo/mcp` 3. If using an API Key, confirm it is set correctly in the config (no extra quotes or whitespace) 4. Restart Cursor completely and check the MCP panel for connection status ### VS Code Fails to Connect 1. Verify your MCP extension configuration (e.g., Continue settings or Copilot MCP config) 2. Ensure the server URL is `https://mcp.tiro.ooo/mcp` 3. If using an API Key, confirm it is set in the correct config field 4. Reload the VS Code window (`Cmd+Shift+P` → "Reload Window") and check extension logs for errors ## Search & Data Issues * **No results?** Try broader search criteria — use a single general keyword in `content`, or widen the `createdAt` date range * **Date format error?** Use ISO 8601 with timezone: `2025-11-22T00:00:00Z` (date-only formats are not accepted) * **Recent notes missing?** Notes may take up to 15 minutes to appear due to caching. Verify the note is "Completed" in [Tiro Dashboard](https://tiro.ooo) * **Request timeout?** Use `get_note(include: ['summary'])` instead of `get_note_transcript` for long meetings ## Error Reference | Code | HTTP | Description | Solution | | ----------------------- | ---- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | `UNAUTHORIZED` | 401 | No valid authentication | Check API key or restart client to re-authenticate via OAuth | | `TOKEN_EXPIRED` | 401 | Token past expiration | Generate a new API key or restart client to re-authenticate via OAuth | | `FORBIDDEN` | 403 | Missing required scope | Check API key scopes or restart client to re-authenticate via OAuth | | `INSUFFICIENT_SCOPE` | 403 | The authenticated key/token lacks the required scope for this tool | Check the scopes table in the [Setup page](/en/developers/mcp/setup) and use a key with the correct scopes | | `MISSING_PARAMETERS` | 400 | Required params missing | Check parameter requirements | | `INVALID_NOTE_ID` | 400 | Invalid note ID | Use positive integer | | `INVALID_DATE_FORMAT` | 400 | Wrong date format | Use ISO 8601 datetime | | `NOTE_NOT_FOUND` | 404 | Note doesn't exist | Verify note ID | | `INTERNAL_SERVER_ERROR` | 500 | Server error | Retry or contact support | | `REQUEST_TIMEOUT` | 504 | Request timed out | Use summary or retry | ## Getting help Open an issue on [GitHub](https://github.com/plato-corp/tiro-mcp-server/issues) or email [support@tiro.ooo](mailto:support@tiro.ooo).