Skip to content

Authentication & Authorization Details

This page explains how the H3 MCP Server keeps your data secure and how to connect your applications.

The Horizon3.ai-hosted MCP Server, uses OAuth 2.1 to ensure secure access to your data. Secure access means:

  • Secure login - Uses your existing Portal account credentials
  • No password sharing - Applications never see your login details
  • Industry standard security - Uses the same OAuth protocol as major platforms
  • Session-based access - Once authenticated, you can use the server until your session expires

How to Connect

In VS Code

When setting up the Horizon3.ai MCP Server in VS Code:

  1. Add the server URL - Configure VS Code with the Horizon3.ai MCP Server production URL as explained in Horizon3.ai-Hosted MCP Server Setup
  2. Start the connection - Click to start using the MCP server
  3. Authorize the connection - VS Code will ask if you want to connect to the OAuth server
  4. Login via browser - Your browser opens and takes you to the Portal login page
  5. Complete authentication - Log in with your Portal credentials (or skip if already logged in)
  6. Return to VS Code - The browser redirects back to VS Code automatically
  7. Start using the server - You're now connected and can access MCP server features

What happens during login

  • If you're already logged into Portal, the browser redirects back to VS Code immediately
  • If you need to log in, you'll use your regular Portal login preference
  • The authentication happens in your browser, so VS Code never sees your credentials
  • Once complete, VS Code receives secure access credentials to use the MCP server

Technical Details

The H3 MCP Server uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) and JWT (JSON Web Tokens) for secure authentication. This ensures:

  • No insecure client secrets - VS Code doesn't need to store sensitive credentials
  • Protection against attacks - PKCE prevents authorization code interception
  • Secure token format - JWT tokens provide cryptographically signed access credentials
  • Standards compliance - Uses current security best practices
  • Cross-platform compatibility - Works consistently across different operating systems

Redirect URI requirements

The Horizon3.ai MCP Server accepts callback URLs that use localhost or 127.0.0.1 with any port (for example, http://127.0.0.1:33418 or http://localhost:3000). If your MCP client uses a different callback URL, you may see an error about the redirect URI not being whitelisted - contact support to have your specific URI added to the whitelist.

Security Features

How your data stays protected

  • Browser-based authentication - Login happens in your secure browser environment
  • No stored passwords - Your credentials are never saved in VS Code or other applications
  • Encrypted connections - All communication between applications and the server is encrypted
  • Session management - Access automatically expires after a period of inactivity

Token-Based security

Instead of passwords, the system uses secure access tokens:

  • Automatic management - VS Code handles tokens in the background
  • Time-limited - Tokens expire after 1 hour for security
  • Unique per session - Each connection gets its own secure token
  • Revocable - Access can be revoked if needed

Manage Your Connection

Session duration

  • Sessions remain active while you're using VS Code
  • Inactive sessions expire automatically for security
  • You'll need to reconnect if your session expires

Disconnecting

  • Close VS Code to end your MCP server session
  • Your authentication will expire automatically
  • No manual logout required

Security Best Practices

For your protection

  • Use trusted networks - Avoid public WiFi for initial setup when possible
  • Keep Portal credentials secure - Use strong passwords and enable two-factor authentication if available
  • Close VS Code when done - Especially on shared computers
  • Monitor activity - Be aware of when and where you're connecting to the MCP server

Get Help

If you encounter authentication issues:

  1. Restart your client - Close and reopen your MCP client (VS Code, Claude Code, etc.)
  2. Check network access - Ensure you can reach portal.horizon3ai.com, oauth-proxy.horizon3ai.com, and mcp.horizon3ai.com
  3. Verify callback URL - Make sure your client uses localhost or 127.0.0.1 for OAuth redirects
  4. Clear browser cache - Sometimes helps with redirect issues
  5. Contact support - If problems persist, reach out with specific error messages

The authentication process is designed to be simple and secure. Once set up, you shouldn't need to think about it - your client will handle the connection automatically.