MCP Server

Connect ChatGPT, Claude Desktop, and other AI applications to your Gmail through inbox.dog's MCP (Model Context Protocol) server.

What is MCP?

MCP (Model Context Protocol) is an open protocol that allows AI applications to securely connect to external tools and data sources. inbox.dog exposes all its email management tools via MCP, letting you interact with Gmail directly from ChatGPT, Claude Desktop, or any MCP-compatible client.

Architecture

ChatGPT/Claude → OAuth 2.0 Auth → MCP Server (inbox.dog)
                                        ↓
                              Better Auth Token Validation
                                        ↓
                              Internal Worker Communication
                                        ↓
                                Gmail API Integration

Quick Start

Connecting from ChatGPT

  1. Open ChatGPT settings
  2. Navigate to "Connections" → "Add connection"
  3. Select "Custom MCP server"
  4. Enter server URL: https://inbox.dog/mcp
  5. Complete OAuth authentication flow
  6. Start using inbox.dog tools in ChatGPT

Example usage:

  • "Show me my unread emails"
  • "Send an email to john@example.com with subject 'Meeting' and message 'Let's meet tomorrow'"
  • "Archive all emails from last week"

Connecting from Claude Desktop

  1. Open Claude Desktop settings
  2. Edit your MCP configuration file
  3. Add inbox.dog server:
{
  "mcpServers": {
    "inbox-dog": {
      "url": "https://inbox.dog/mcp",
      "transport": "sse"
    }
  }
}
  1. Restart Claude Desktop
  2. Authenticate when prompted
  3. Access Gmail tools from Claude

Available Tools

All inbox.dog tools are available via MCP:

Email Management

  • sendEmail - Compose and send new emails

    • Parameters: to, subject, message

  • reply - Reply to specific email threads

    • Parameters: message, subject (optional)

  • searchEmails - Search Gmail with filters

    • Parameters: query, maxResults

  • archive - Archive messages

    • Parameters: emailId (optional in agent context)

  • label - Apply Gmail labels

    • Parameters: labels (array), emailId (optional)

  • star - Star or unstar messages

    • Parameters: emailId (optional)

Additional Tools

  • forward - Forward emails
  • markAsRead - Mark emails as read
  • snooze - Snooze emails for later
  • delete - Delete emails
  • createDraft - Create draft replies
  • getThread - Get full conversation thread
  • searchDocuments - Search agent documents
  • webhook - Trigger webhooks
  • Plus all custom agent-specific tools

Authentication

inbox.dog's MCP server uses OAuth 2.0 Bearer token authentication:

  1. Initial Connection: When you first connect, you'll be redirected to Google OAuth
  2. Token Storage: OAuth access tokens are stored in the oauthAccessToken table
  3. Token Validation: Each request validates Bearer tokens against stored tokens
  4. Session Management: Each MCP request creates an isolated execution context
  5. Token Expiration: Tokens are checked for expiration on each request

Security Features

  • Token Encryption: All Gmail tokens encrypted at rest using XChaCha20-Poly1305
  • HTTPS Only: All connections require encrypted transport
  • Scope Isolation: Minimal required Gmail permissions
  • Session Isolation: Each request runs in isolated context
  • Audit Logging: All tool executions logged to LiveLog system

Endpoints

Endpoint Description
/mcp Main MCP JSON-RPC endpoint (ChatGPT)
/mcp/sse Server-Sent Events endpoint (streaming)
/.well-known/oauth-authorization-server OAuth discovery endpoint

Protocol Details

  • Protocol Version: 2024-11-05
  • Server Name: inbox-dog-mcp
  • Server Version: 1.0.0
  • Transport: HTTP POST (JSON-RPC) or SSE
  • Authentication: Bearer token (OAuth 2.0)

Rate Limits

  • 100 requests/minute per IP address
  • Standard Better Auth rate limits apply
  • Rate limit headers included in responses

Use Cases

Email Management from ChatGPT

Use ChatGPT as your email assistant:

You: "Show me emails from last week about 'project proposal'"
ChatGPT: [Uses searchEmails tool]
ChatGPT: "Found 5 emails. Here's a summary..."

You: "Reply to the most recent one saying I'll review it tomorrow"
ChatGPT: [Uses reply tool]
ChatGPT: "Replied successfully."

Claude Desktop Integration

Access Gmail directly from Claude Desktop:

You: "Archive all emails older than 30 days"
Claude: [Uses searchEmails + archive tools]
Claude: "Archived 47 emails."

Custom Workflows

Combine inbox.dog agents with external AI:

  1. Configure agent in inbox.dog dashboard
  2. Connect via MCP from ChatGPT/Claude
  3. Use agent's custom tools from external AI
  4. Build complex multi-step workflows

Troubleshooting

401 Unauthorized

  • Check OAuth token expiration in oauthAccessToken table
  • Re-authenticate via MCP client settings
  • Verify account has active Google OAuth connection
  • Ensure Bearer token is included in Authorization header

Tool Not Found

  • Ensure tool name matches exactly (case-sensitive)
  • Check tool is available in your inbox.dog account
  • Verify agent configuration includes the tool
  • Use tools/list method to see available tools

Connection Failed

  • Verify server URL: https://inbox.dog/mcp
  • Check HTTPS is enabled (required)
  • Ensure firewall allows outbound HTTPS connections
  • For SSE transport, use /mcp/sse endpoint

Rate Limit Errors

  • Wait 60 seconds before retrying
  • Reduce request frequency
  • Check rate limit headers in response

No Gmail Account Found

  • Ensure you've connected your Gmail account in inbox.dog dashboard
  • Verify OAuth connection is active
  • Check that Gmail account exists for authenticated user

Advanced Configuration

Custom MCP Clients

You can connect any MCP-compatible client to inbox.dog:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'my-client',
  version: '1.0.0'
});

await client.connect({
  transport: new SSESocketTransport('https://inbox.dog/mcp/sse')
});

// List available tools
const tools = await client.listTools();
console.log(tools);

// Call a tool
const result = await client.callTool({
  name: 'sendEmail',
  arguments: {
    to: 'test@example.com',
    subject: 'Test',
    message: 'Hello from MCP!'
  }
});

Next Steps