Authentication

Overview

Tiro MCP Server uses OAuth 2.0 with JWT tokens (HS256 algorithm) to provide secure, scoped access to your meeting notes. Authentication is handled through Google OAuth login.

Authentication MethodCurrently, Tiro supports Google OAuth login only. Support for email/password login and Microsoft OAuth is planned for future releases.

How Authentication Works

Configure Your Client

Add Tiro MCP Server configuration to your client (Claude Code or Claude Desktop)No need to visit Tiro’s website first - the client handles everything.

Browser Opens Automatically

When your client first connects to Tiro MCP Server:

A browser window opens automatically
You’re redirected to Tiro’s OAuth login page

In the browser:

Sign in with your Google account
If you don’t have a Tiro account, one will be created automatically
Complete the OAuth consent flow

Return to Client

After successful authentication:

The browser redirects back to your client
Tiro generates an OAuth 2.0 JWT token with mcp:notes:read scope
Your client is now connected and ready to use

No Manual Token ManagementYou don’t need to manually copy/paste tokens. The OAuth flow handles everything automatically through your browser.

OAuth 2.0 Specification

Tiro MCP Server implements standard OAuth 2.0 with the following specifications:

Discovery Endpoint

GET https://mcp.tiro.ooo/.well-known/oauth-protected-resource

Response:

{
  "resource": "https://mcp.tiro.ooo/mcp",
  "authorization_servers": [
    "https://api.tiro.ooo"
  ],
  "scopes_supported": [
    "mcp:notes:read"
  ],
  "bearer_methods_supported": ["header"]
}

JWT Token Structure

Tiro uses HS256 (HMAC with SHA-256) for JWT signing. Header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload:

{
  "iss": "https://api.tiro.ooo",
  "sub": "user:12345",
  "aud": "https://mcp.tiro.ooo",
  "exp": 1736800000,
  "iat": 1736700000,
  "scope": "mcp:notes:read",
  "client_id": "claude_desktop"
}

Claim	Description
`iss`	Token issuer (Tiro OAuth server)
`sub`	User identifier
`aud`	Intended audience (MCP server)
`exp`	Expiration timestamp (Unix seconds)
`iat`	Issued at timestamp
`scope`	Granted permissions
`client_id`	OAuth client identifier

Supported Scopes

Scope	Permissions	Required For
`mcp:notes:read`	Read meeting notes	All MCP tools

Future Scopes: Additional scopes like mcp:notes:write and mcp:notes:delete are planned for Q2 2025.

Claude Code Setup

Claude Code is Anthropic’s official CLI tool that supports MCP servers with OAuth authentication.

Configuration File Location

Create or edit the MCP configuration file:

mkdir -p ~/.config/claude-code
nano ~/.config/claude-code/mcp_servers.json

Configuration Format

Add Tiro MCP Server to your configuration:

mcp_servers.json

{
  "mcpServers": {
    "tiro": {
      "url": "https://mcp.tiro.ooo/mcp",
      "transport": {
        "type": "streamable-http"
      }
    }
  }
}

OAuth Handles AuthenticationNo need to add Authorization headers or tokens manually. Claude Code will automatically initiate the OAuth flow when it first connects to Tiro.

First Connection

When you first use Tiro MCP Server with Claude Code:

Run any command that uses the MCP server
Claude Code will automatically open your browser
Sign in with your Google account in the browser
Return to Claude Code - authentication is complete!

Test Connection

claude-code "Search my recent Tiro meeting notes"

On first run, this will trigger the OAuth authentication flow.

Claude Desktop Setup

Claude Desktop supports MCP servers with automatic OAuth authentication.

Configuration File Location

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

Configuration Format

Edit Configuration File

Open the configuration file in your text editor:

open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add Tiro MCP Server

Add the following configuration:

claude_desktop_config.json

{
  "mcpServers": {
    "tiro": {
      "url": "https://mcp.tiro.ooo/mcp",
      "transport": {
        "type": "streamable-http"
      }
    }
  }
}

If you already have other MCP servers configured, add the tiro entry inside the existing mcpServers object.

Restart Claude Desktop

Quit Claude Desktop completely (Menu → Quit)
Relaunch Claude Desktop

First Connection - OAuth Flow

When Claude Desktop first connects to Tiro:

Your browser will open automatically
Sign in with your Google account
If you don’t have a Tiro account, it will be created automatically
Complete the OAuth consent
Return to Claude Desktop - you’re connected!

Verify Connection

Ask Claude:

Are you connected to the Tiro MCP server?

Claude should confirm the connection and show available Tiro tools.

OAuth Browser FlowThe browser opens automatically when authentication is needed. You don’t need to manually manage tokens or credentials.

Token Management

Token Expiration

Tokens expire based on your OAuth settings (typically 30 days for dashboard-generated tokens). Check Token Expiration:

# Decode JWT payload (requires jq)
echo "YOUR_TOKEN" | cut -d'.' -f2 | base64 -d | jq '.'

Look for the exp field (Unix timestamp in seconds).

Renew Expired Token

When your token expires, your MCP client will automatically trigger the OAuth flow again:

Your browser will open automatically
Sign in with your Google account
A new token is generated automatically
Return to your client - reconnected!

No manual token management needed. The OAuth flow handles everything.

Security Best Practices

OAuth Handles Security Automatically

With OAuth authentication:

Tokens are managed automatically by your client
No manual token storage or rotation needed
Tokens expire automatically and refresh via OAuth
Your Google credentials are never shared with the client

Use HTTPS Only

All communication with Tiro MCP Server uses HTTPS
OAuth redirects use secure HTTPS endpoints
TLS 1.2 or higher is required

Principle of Least Privilege

Tiro automatically grants only mcp:notes:read scope
Additional scopes will be added in future releases
Review OAuth consent screen carefully before approving

Protect Your Google Account

Since authentication uses Google OAuth:

Enable 2-factor authentication on your Google account
Use a strong, unique password
Monitor your Google account security settings
Sign out of Tiro if you suspect unauthorized access

Troubleshooting

401 Unauthorized Error

Symptoms:

“Authentication required” message
“Invalid or expired token” error
Connection fails with authentication error

Solutions:

Re-authenticate via Browser

Close and restart your MCP client
The OAuth flow will trigger automatically
Sign in with your Google account in the browser
Return to your client

Clear Browser Cookies

If re-authentication fails:

Clear cookies for tiro.ooo in your browser
Try the OAuth flow again

Verify Google Account

Ensure you’re signing in with the correct Google account that has access to Tiro meeting notes.

Check Network Connection

Ensure your internet connection is stable
Verify you can access https://mcp.tiro.ooo in your browser
Check if any firewall or proxy is blocking OAuth redirects

403 Forbidden Error

Symptoms:

“Insufficient scope” message
Access denied to specific tools

Solution: The token doesn’t have the required mcp:notes:read scope. Generate a new token with the correct scope selected.

Configuration Not Loading

Symptoms:

Tiro MCP server not appearing in client
Connection fails silently

Solutions:

Validate JSON syntax using JSONLint
Check file location - ensure config file is in the correct directory
Restart client completely - not just refresh, but full quit and relaunch
Check file permissions - ensure the config file is readable

Next Steps

Now that authentication is configured:

Explore Tools

Learn about the four available MCP tools

Troubleshooting Guide

Solutions for common issues

Getting Started

Fundamentals

Webhooks

Voice File

Template Based Documents

API Reference

MCP Server

External Viewers

Overview

How Authentication Works

OAuth 2.0 Specification

Discovery Endpoint

JWT Token Structure

Supported Scopes

Claude Code Setup

Configuration File Location

Configuration Format

First Connection

Test Connection

Claude Desktop Setup

Configuration File Location

Configuration Format

Token Management

Token Expiration

Renew Expired Token

Security Best Practices

Troubleshooting

401 Unauthorized Error

403 Forbidden Error

Configuration Not Loading

Next Steps

Explore Tools

Troubleshooting Guide

Getting Started

Fundamentals

Webhooks

Voice File

Template Based Documents

API Reference

MCP Server

External Viewers

​Overview

​How Authentication Works

​OAuth 2.0 Specification

​Discovery Endpoint

​JWT Token Structure

​Supported Scopes

​Claude Code Setup

​Configuration File Location

​Configuration Format

​First Connection

​Test Connection

​Claude Desktop Setup

​Configuration File Location

​Configuration Format

​Token Management

​Token Expiration

​Renew Expired Token

​Security Best Practices

​Troubleshooting

​401 Unauthorized Error

​403 Forbidden Error

​Configuration Not Loading

​Next Steps

Explore Tools

Troubleshooting Guide

Overview

How Authentication Works

OAuth 2.0 Specification

Discovery Endpoint

JWT Token Structure

Supported Scopes

Claude Code Setup

Configuration File Location

Configuration Format

First Connection

Test Connection

Claude Desktop Setup

Configuration File Location

Configuration Format

Token Management

Token Expiration

Renew Expired Token

Security Best Practices

Troubleshooting

401 Unauthorized Error

403 Forbidden Error

Configuration Not Loading

Next Steps