Troubleshooting

Quick Diagnostic Checklist

Follow this checklist to diagnose issues systematically:

Check Basic Connection

Is the internet connection active?
Can you access https://mcp.tiro.ooo?
Is your MCP client running?

Verify Authentication

Do you have a valid access token?
Has the token expired?
Does the token include mcp:notes:read scope?

Validate Configuration

Is the URL correct: https://mcp.tiro.ooo/mcp?
Is the JSON syntax valid?
Have you restarted the client completely?

Test Functionality

Does Tiro appear in your tools list?
Can you search notes?
Do other tools work?

Connection Issues

Server Not Found

Symptoms:

Connection timeout
“Connection refused” error
“Server not found” message

Common Causes:

Incorrect URL in configuration
Network connectivity issues
MCP client misconfiguration

Solutions:

Verify URL

Ensure your configuration uses the correct URL:

Correct

{
  "url": "https://mcp.tiro.ooo/mcp"
}

Incorrect - Missing /mcp

{
  "url": "https://mcp.tiro.ooo"
}

Incorrect - Wrong protocol

{
  "url": "http://mcp.tiro.ooo/mcp"
}

Test Network Connection

Verify the server is reachable:

curl https://mcp.tiro.ooo/mcp

Expected: 405 Method Not Allowed (this is normal for a GET request)Unexpected: 404 Not Found or connection timeout indicates issues

Review Configuration File

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Validate JSON syntax at JSONLint

Tools Not Appearing

Symptoms:

AI doesn’t recognize Tiro tools
“No tools available” message
Tiro not in tools list

Solutions:

Check Connection Status
- Ask your AI: “List all available MCP servers”
- Verify Tiro appears in the list
Refresh Tools List
- Completely restart your MCP client (not just refresh)
- Reload configuration file
Verify Setup
- Run through the Authentication setup again
- Ensure all configuration steps are complete

Authentication Errors

401 Unauthorized

Common Causes:

Missing access token
Expired token
Malformed token format
Revoked token

Solutions:

Check Token Presence
Check Token Expiration
Re-authenticate

Verify your configuration includes the token:

Claude Code: Check Authorization header in config
Claude Desktop: Restart app to see token prompt

Decode your JWT token to check expiration:

echo "YOUR_TOKEN" | cut -d'.' -f2 | base64 -d | jq '.exp'

Compare with current time:

date +%s

If exp < current time, the token has expired.

403 Forbidden

Cause: Token lacks the mcp:notes:read scope Solution:

Check Current Scope

Decode your token and examine the scope claim:

echo "YOUR_TOKEN" | cut -d'.' -f2 | base64 -d | jq '.scope'

Re-authenticate with Google

Sign in to Tiro with your Google account
OAuth automatically includes mcp:notes:read scope
Restart your MCP client

Invalid Token Format

Symptoms:

“Invalid token format” error
Authentication fails immediately

Common Mistakes:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Solution: Copy the complete token without extra spaces or line breaks

Configuration Issues

Claude Desktop Repeatedly Prompts for Token

Cause:

Configuration file has JSON syntax errors
Token input not being saved properly

Solution:

Validate JSON

Open your configuration file and check for common issues:

Missing or extra commas
Unmatched brackets {} or []
Missing quotes around strings
Use JSONLint to validate

Verify Configuration Structure

Ensure your config follows this structure:

claude_desktop_config.json

{
  "mcpServers": {
    "tiro": {
      "url": "https://mcp.tiro.ooo/mcp",
      "transport": {
        "type": "streamable-http"
      },
      "inputs": [
        {
          "id": "tiro_token",
          "type": "promptString",
          "description": "Tiro OAuth 2.0 Access Token",
          "password": true
        }
      ]
    }
  }
}

Completely Restart Claude Desktop

# Quit completely (Cmd+Q)
killall Claude

# Restart
open -a Claude

Search Issues

No Search Results

Symptoms:

{
  "notes": []
}

Common Causes:

Search filters too restrictive
No matching notes exist
Invalid date format

Solutions:

Relax Search Criteria

Try broader searches:

Too Restrictive

{
  "content": "very specific keyword",
  "createdAt": "2025-11-22T10:00:00Z",
  "personName": "Exact Name"
}

Better Approach

{
  "content": "general keyword"
}

Or search all notes:

{}

Verify Date Format

Ensure dates use ISO 8601 format:

{
  "createdAt": "2025-11-01T00:00:00Z"
}

Generate current date:

date -u +"%Y-%m-%dT%H:%M:%SZ"

Check Note Existence

Verify notes exist in your account:

Visit Tiro Dashboard
Check your meeting notes list
Ensure notes are in “Completed” status

Invalid Date Format Error

Solution: Always use ISO 8601 datetime format with timezone:

{
  "createdAt": "2025-11-22T00:00:00Z"
}

Date-only formats like 2025-11-22 are not accepted. You must include time and timezone.

Performance Issues

Slow Response Times

Symptoms:

Requests take 5+ seconds
Timeout errors
Laggy responses

Solutions:

Use Progressive Disclosure

Instead of loading full transcripts immediately:Benefits:

Initial results in ~1 second
Load full content only when needed
Save up to 80% of time and tokens

Prefer Summaries FirstTry get_note_summary before get_note_transcript. Summaries are faster (~2 seconds vs ~5 seconds) and often contain enough information.

Request Timeouts

Causes:

Very long meeting transcripts (2+ hours)
Server load
Network latency

Solutions:

Use summary instead of transcript
Retry after a short delay
Avoid peak hours if possible
Contact support if timeouts persist

Data Issues

Recently Created Notes Not Appearing

Possible Reasons:

Processing Not Complete

Check note status in Tiro Dashboard:

“Processing” → Wait for completion
“Completed” → Available for MCP queries

Cache Delay

Tiro MCP Server uses a 15-minute cache. New notes may take up to 15 minutes to appear in search results.Workaround: Access directly if you have the note ID using get_note_transcript or get_note_summary.

Permission Issues

Verify the note belongs to your account:

Check user ID from an auth_status call
Confirm note ownership in Tiro Dashboard

Error Reference

HTTP Status Codes

Status	Meaning	Common Causes
401	Unauthorized	Missing, expired, or invalid token
403	Forbidden	Insufficient scope permissions
400	Bad Request	Invalid parameters or format
404	Not Found	Note doesn’t exist or no access
500	Server Error	Internal server issue (retry)
504	Gateway Timeout	Request took too long (use summary)

Error Codes

Code	HTTP	Description	Solution
`UNAUTHORIZED`	401	No valid authentication	Generate new token
`TOKEN_EXPIRED`	401	Token past expiration	Renew token
`INVALID_TOKEN_FORMAT`	401	Malformed token	Check token format
`FORBIDDEN`	403	Missing required scope	Add `mcp:notes:read` scope
`MISSING_PARAMETERS`	400	Required params missing	Add required parameters
`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

If you’ve tried the above solutions and still have issues:

GitHub Issues

Report bugs or request features

Email Support

Contact: [email protected] Response time: 24 hours

Information to Include

When requesting support, please provide:

Error Information

Complete error message
Error code (if shown)
Timestamp when error occurred
Steps to reproduce

System Information

MCP client (Claude Desktop, Claude Code, etc.)
Operating system and version
Token expiration time (from decoded JWT)

Configuration

Configuration file contents (redact your token!)
Whether tools appear in your client
Result of auth_status call (if possible)

Next Steps

Authentication Guide

Review OAuth 2.0 setup steps

Available Tools

Learn about MCP tools usage

Email Support

Getting Started

Fundamentals

Webhooks

Voice File

Template Based Documents

API Reference

MCP Server

External Viewers

Quick Diagnostic Checklist

Connection Issues

Server Not Found

Tools Not Appearing

Authentication Errors

401 Unauthorized

403 Forbidden

Invalid Token Format

Configuration Issues

Claude Desktop Repeatedly Prompts for Token

Search Issues

No Search Results

Invalid Date Format Error

Performance Issues

Slow Response Times

Use Progressive Disclosure

Request Timeouts

Data Issues

Recently Created Notes Not Appearing

Error Reference

HTTP Status Codes

Error Codes

Getting Help

GitHub Issues

Information to Include

Next Steps

Authentication Guide

Available Tools

Getting Started

Fundamentals

Webhooks

Voice File

Template Based Documents

API Reference

MCP Server

External Viewers

​Quick Diagnostic Checklist

​Connection Issues

​Server Not Found

​Tools Not Appearing

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Invalid Token Format

​Configuration Issues

​Claude Desktop Repeatedly Prompts for Token

​Search Issues

​No Search Results

​Invalid Date Format Error

​Performance Issues

​Slow Response Times

Use Progressive Disclosure

​Request Timeouts

​Data Issues

​Recently Created Notes Not Appearing

​Error Reference

​HTTP Status Codes

​Error Codes

​Getting Help

GitHub Issues

Email Support

​Information to Include

​Next Steps

Authentication Guide

Available Tools

Quick Diagnostic Checklist

Connection Issues

Server Not Found

Tools Not Appearing

Authentication Errors

401 Unauthorized

403 Forbidden

Invalid Token Format

Configuration Issues

Claude Desktop Repeatedly Prompts for Token

Search Issues

No Search Results

Invalid Date Format Error

Performance Issues

Slow Response Times

Request Timeouts

Data Issues

Recently Created Notes Not Appearing

Error Reference

HTTP Status Codes

Error Codes

Getting Help

Information to Include

Next Steps