MCP Troubleshooting

This guide covers common issues and their solutions when using the Transactional MCP server.

Connection Issues

"MCP server failed to connect"

Symptoms: Claude Desktop/Code shows the MCP server as disconnected or failed.

Solutions:

Check your config file:

For Claude Desktop:
```
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
For Claude Code:
```
cat ~/.claude.json
```
Verify the config has the correct format (see below).
For Claude Desktop (Free tier), ensure mcp-remote is installed:
```
npm install -g mcp-remote
```
Check the MCP server status:
```
transactional mcp status
```
Restart Claude Desktop/Code completely.

Correct Configuration Format

Claude Desktop (using mcp-remote):

{
  "mcpServers": {
    "transactional": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.usetransactional.com"]
    }
  }
}

Claude Code:

{
  "mcpServers": {
    "transactional": {
      "url": "https://mcp.usetransactional.com/mcp"
    }
  }
}

"command" is required error

Cause: You're using the URL-based config format with Claude Desktop's free-tier JSON config, which only supports stdio-based servers.

Solution: Use the mcp-remote wrapper:

# Reinstall with correct format
transactional mcp install --target claude-desktop --force

Or manually use this config:

{
  "mcpServers": {
    "transactional": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.usetransactional.com"]
    }
  }
}

Authentication Issues

Browser doesn't open for authorization

Check if a browser window opened in the background
Copy the authorization URL from the terminal and open it manually
Ensure you're not blocking pop-ups

Authorization loop (keeps asking to authorize)

Clear Claude's cached data
Check if you're logged into the correct Transactional account
Try authorizing in an incognito/private browser window

"Invalid or expired token"

Tokens are automatically refreshed, but if issues persist:

Reinstall the MCP config:
```
transactional mcp install --force
```
Restart Claude and authorize again

OAuth Flow Issues

"401 Unauthorized" when using tools

Cause: Authorization not completed or token expired.

Solution:

Use any Transactional tool to trigger re-authorization
Complete the browser-based login
Try your operation again

"redirect_uri mismatch"

Cause: Dynamic Client Registration issue.

Solution:

Check if you're using the correct MCP server URL
For self-hosted: Ensure your MCP server URL matches the configured callback URLs

PKCE verification failed

Cause: Code verifier mismatch during token exchange.

Solution: This is usually a client issue. Restart Claude and try again.

Platform-Specific Issues

macOS

Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json

Can't find Application Support folder: In Finder, press Cmd+Shift+G and paste the path.

Windows

Config file location: %APPDATA%\Claude\claude_desktop_config.json

Can't find AppData folder: Press Win+R, type %APPDATA%, press Enter.

Linux

Config file location: ~/.config/claude/claude_desktop_config.json

Claude Code Issues

MCP tools not available

Verify config exists:
```
cat ~/.claude.json | jq .
```

Check format matches:

{
  "mcpServers": {
    "transactional": {
      "url": "https://mcp.usetransactional.com/mcp"
    }
  }
}

Start a fresh Claude Code session

Authorization prompt doesn't appear

Check if auth is already cached
Try using a tool that requires authentication
Check browser pop-up settings

Tool-Specific Errors

"Server not found" when sending email

Ensure you have at least one email server configured in your Transactional dashboard.

"Domain not verified"

You can only send from verified domains. Add and verify your domain:

transactional email domains add mail.example.com
# Configure DNS records shown
transactional email domains verify <id>

"Template not found"

The template ID or alias doesn't exist. List available templates:

transactional email templates list

"Organization not found"

You may need to switch organizations:

transactional org list
transactional switch <org-slug>

Network Issues

Behind corporate proxy

Ensure Claude Desktop/Code can access:

mcp.usetransactional.com
api.usetransactional.com
usetransactional.com (for OAuth login)

Firewall blocking connections

Allow outbound HTTPS (port 443) to the above domains.

SSL certificate errors

Check your system time is correct
Update your CA certificates
Check if corporate proxy is intercepting HTTPS

Debugging

Check MCP server directly

# Health check
curl https://mcp.usetransactional.com/health
 
# OAuth metadata
curl https://mcp.usetransactional.com/.well-known/oauth-protected-resource

Test CLI connectivity

transactional mcp status

View CLI config

transactional config show

Reset Everything

If all else fails, reset and start fresh:

# Remove MCP configs
transactional mcp uninstall
 
# Reset CLI config
transactional config reset
 
# Reinstall
transactional mcp install
 
# Restart Claude Desktop/Code

Getting Help

If you're still having issues:

Check the Transactional status page
Review the GitHub issues
Contact support with:
- Your platform (macOS/Windows/Linux)
- CLI version: transactional --version
- Error messages
- Config file contents (don't include any tokens)