Authentication Guide

The MCP server supports three authentication methods, each optimized for different use cases.

Authentication Methods

OAuth 2.1 (Claude Desktop)

OAuth 2.1 with PKCE is the primary authentication method for Claude Desktop and browser-based MCP clients.

How It Works

1. Client connects to /mcp without authentication
2. Server returns 401 with OAuth discovery URL
3. Client fetches /.well-known/oauth-protected-resource metadata
4. Client initiates PKCE authorization flow
5. User authenticates via browser
6. Client exchanges code for tokens
7. Subsequent requests include Authorization: Bearer <token>

Discovery Endpoints

GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-authorization-server

Protected Resource Metadata (/.well-known/oauth-protected-resource):

{
  "resource": "https://mcp.us-east-1.hiyve.tech",
  "authorization_servers": ["https://mcp.us-east-1.hiyve.tech"],
  "scopes_supported": [
    "mcp:data:read",
    "mcp:search:execute",
    "mcp:ai:query"
  ]
}

Authorization Server Metadata (/.well-known/oauth-authorization-server):

{
  "issuer": "https://mcp.us-east-1.hiyve.tech",
  "authorization_endpoint": "https://mcp.us-east-1.hiyve.tech/oauth/authorize",
  "token_endpoint": "https://mcp.us-east-1.hiyve.tech/oauth/token",
  "registration_endpoint": "https://mcp.us-east-1.hiyve.tech/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "scopes_supported": ["mcp:data:read", "mcp:search:execute", "mcp:ai:query"]
}

OAuth Endpoints

Authorization Request

GET /oauth/authorize?
  client_id=<client_id>&
  redirect_uri=<redirect_uri>&
  response_type=code&
  code_challenge=<base64url_sha256>&
  code_challenge_method=S256&
  state=<random_state>&
  scope=mcp:data:read%20mcp:search:execute

Required Parameters:

• client_id - OAuth client identifier
• redirect_uri - Where to send the authorization code
• response_type - Must be code
• code_challenge - PKCE challenge (base64url-encoded SHA256)
• code_challenge_method - Must be S256

Optional Parameters:

• state - Client state (echoed back to prevent CSRF)
• scope - Space-separated scopes

Token Exchange

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=<authorization_code>&
redirect_uri=<redirect_uri>&
code_verifier=<original_code_verifier>&
client_id=<client_id>

Response:

{
  "access_token": "<jwt_token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<refresh_token>",
  "scope": "mcp:data:read mcp:search:execute"
}

Token Refresh

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=<refresh_token>&
client_id=<client_id>

Claude Desktop Configuration

Claude Desktop handles OAuth automatically. Just configure the server URL:

{
  "mcpServers": {
    "hiyve": {
      "url": "https://mcp.us-east-1.hiyve.tech/mcp",
      "transport": "streamable-http"
    }
  }
}

On first connection, Claude Desktop will open a browser window for authentication.

MCP Token (External API Access)

MCP tokens are 64-character hex strings for programmatic API access outside of Claude Desktop.

Token Format

Authorization: Bearer <64-character-hex-token>

or

X-API-Key: <64-character-hex-token>

Example Request

curl -X POST https://mcp.us-east-1.hiyve.tech/mcp \
  -H "Authorization: Bearer abc123...def456" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Generating MCP Tokens

MCP tokens are generated through your Hiyve account settings or via the admin API. Each token is associated with:

• A user account (createdBy)
• An organization (brandOrgId)
• Optional permission scopes

Token Validation

The server validates MCP tokens by checking:

1. Token exists in the database
2. Token has not expired
3. Token has not been revoked
4. Token matches the 64-character hex format

Email + API Key (Internal)

For internal services and logged-in users, provide both headers:

x-user-email: user@example.com
X-API-Key: <organization-api-key>

Example Request

curl -X POST https://mcp.us-east-1.hiyve.tech/mcp \
  -H "x-user-email: user@example.com" \
  -H "X-API-Key: org_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

How It Works

1. Server looks up user by email
2. Validates that the user's stored API key matches the header
3. Returns auth context including user ID, organization, and permissions

401 Response Format

When authentication fails, the server returns a 401 status with OAuth discovery information:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.us-east-1.hiyve.tech/.well-known/oauth-protected-resource"
Content-Type: application/json

{
  "error": "Authentication required",
  "code": "AUTHENTICATION_REQUIRED",
  "resource_metadata": "https://mcp.us-east-1.hiyve.tech/.well-known/oauth-protected-resource"
}

The WWW-Authenticate header follows the MCP specification, pointing clients to the OAuth discovery endpoint.

Authentication Priority

When multiple authentication methods are present, the server evaluates them in order:

1. OAuth Token - If a Bearer token is present, try OAuth validation first
2. MCP Token - If OAuth fails, try MCP token validation (64-char hex)
3. Email + API Key - Fall back to header-based authentication

This allows OAuth tokens and MCP tokens to coexist seamlessly.

Security Considerations

PKCE (Proof Key for Code Exchange)

OAuth 2.1 requires PKCE to prevent authorization code interception attacks:

• Only S256 challenge method is supported (SHA256 hash)
• plain method is not supported

Token Expiration

Secure Headers

Always use HTTPS in production. The server expects:

• Authorization: Bearer <token> for OAuth/MCP tokens
• Headers are case-insensitive (x-user-email or X-User-Email)

Troubleshooting

"Invalid or expired MCP token"

• Verify the token is exactly 64 hexadecimal characters
• Check that the token has not been revoked
• Ensure you're using the correct endpoint URL

"User not found"

• The email address is not registered
• The API key doesn't match the user's organization

"Invalid authorization code"

• Authorization codes expire after 10 minutes
• Each code can only be used once
• The redirect_uri must match exactly

OAuth flow not completing

1. Check that the client is registered with POST /oauth/register
2. Verify the redirect_uri is registered for the client
3. Ensure PKCE parameters are correctly generated