Skip to main content
Most MCP setup issues come from the auth header, the transport, or the client cache. Check them in the order below, and restart the client after changing settings.

​
Connection Issues

​
Server Not Found

Check that the MCP server URL is https://mcp.tiro.ooo/mcp.
  • Missing /mcp path suffix
  • Using http:// instead of https://
Check the connection with this command.
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

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

​
INSUFFICIENT_SCOPE errors

If a tool call returns an INSUFFICIENT_SCOPE error, your credential lacks the scope that tool requires. The missing scope is named in the error message (e.g. mcp:note:write).
  • API keys: issue a key with the required scopes at Tiro Platform API Keys.
  • OAuth: reconnect. If the missing scope ends in :write, choose read + write on the consent screen; for read scopes, read only is enough. Clients that support re-authorization will reopen the consent screen automatically based on the error response.

​
Configuration Issues

​
Claude Code Fails to Connect

  1. Verify your config matches the Claude Code 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
  2. Validate JSON syntax — check for missing commas, unmatched brackets, or missing quotes (JSONLint)
  3. Ensure Node.js 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
  • Request timeout? Use get_note(include: ['summary']) instead of get_note_transcript for long meetings

​
Error Reference

Invalid parameters (e.g. date format, blank keyword) are rejected with a standard MCP validation error, not the custom codes above — the tool input schemas are validated with zod.

​
Getting help

Open an issue on GitHub or email support@tiro.ooo.