Default resource indicator based on server URL

Author: eleftherias

cmd/thv/app/run.go

@@ -22,6 +22,7 @@ import (
 	"github.com/stacklok/toolhive/pkg/networking"
 	"github.com/stacklok/toolhive/pkg/process"
 	"github.com/stacklok/toolhive/pkg/runner"
+	"github.com/stacklok/toolhive/pkg/validation"
 	"github.com/stacklok/toolhive/pkg/workloads"
 )
 
@@ -461,6 +462,16 @@ func validateRunFlags(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
+	// Validate --remote-auth-resource flag (RFC 8707)
+	if resourceFlag := cmd.Flags().Lookup("remote-auth-resource"); resourceFlag != nil && resourceFlag.Changed {
+		resource := resourceFlag.Value.String()
+		if resource != "" {
+			if err := validation.ValidateResourceURI(resource); err != nil {
+				return fmt.Errorf("invalid --remote-auth-resource: %w", err)
+			}
+		}
+	}
+
 	// Validate --from-config flag usage
 	fromConfigFlag := cmd.Flags().Lookup("from-config")
 	if fromConfigFlag != nil && fromConfigFlag.Value.String() != "" {

cmd/thv/app/run_flags.go

@@ -681,7 +681,13 @@ func getRemoteAuthFromRemoteServerMetadata(
 	authCfg.Issuer = firstNonEmpty(f.RemoteAuthIssuer, oc.Issuer)
 	authCfg.AuthorizeURL = firstNonEmpty(f.RemoteAuthAuthorizeURL, oc.AuthorizeURL)
 	authCfg.TokenURL = firstNonEmpty(f.RemoteAuthTokenURL, oc.TokenURL)
-	authCfg.Resource = firstNonEmpty(f.RemoteAuthResource, oc.Resource)
+
+	resourceIndicator := firstNonEmpty(f.RemoteAuthResource, oc.Resource)
+	if resourceIndicator != "" {
+		authCfg.Resource = resourceIndicator
+	} else {
+		authCfg.Resource = remote.DefaultResourceIndicator(remoteServerMetadata.URL)
+	}
 
 	// OAuthParams: REPLACE metadata when CLI provides any key/value.
 	if len(runFlags.OAuthParams) > 0 {
@@ -716,6 +722,12 @@ func getRemoteAuthFromRunFlags(runFlags *RunFlags) (*remote.Config, error) {
 		}
 	}
 
+	// Derive the resource parameter (RFC 8707)
+	resource := runFlags.RemoteAuthFlags.RemoteAuthResource
+	if resource == "" && runFlags.ResourceURL != "" {
+		resource = remote.DefaultResourceIndicator(runFlags.RemoteURL)
+	}
+
 	return &remote.Config{
 		ClientID:     runFlags.RemoteAuthFlags.RemoteAuthClientID,
 		ClientSecret: clientSecret,
@@ -726,7 +738,7 @@ func getRemoteAuthFromRunFlags(runFlags *RunFlags) (*remote.Config, error) {
 		Issuer:       runFlags.RemoteAuthFlags.RemoteAuthIssuer,
 		AuthorizeURL: runFlags.RemoteAuthFlags.RemoteAuthAuthorizeURL,
 		TokenURL:     runFlags.RemoteAuthFlags.RemoteAuthTokenURL,
-		Resource:     runFlags.RemoteAuthFlags.RemoteAuthResource,
+		Resource:     resource,
 		OAuthParams:  runFlags.OAuthParams,
 	}, nil
 }

docs/remote-mcp-authentication.md

@@ -150,6 +150,60 @@ When no client credentials are provided ([`pkg/auth/oauth/dynamic_registration.g
 4. **Store Credentials**: Use returned client_id (and client_secret if provided)
 5. **Proceed with OAuth Flow**: Using registered credentials
 
+## Resource Parameter (RFC 8707) Implementation
+
+ToolHive implements the OAuth 2.0 Resource Indicators (RFC 8707) as required by the MCP specification:
+
+**Location**: [`pkg/auth/remote/handler.go:52-69`](../pkg/auth/remote/handler.go#L52)
+
+### Automatic Defaulting
+When no explicit `--remote-auth-resource` flag is provided, ToolHive automatically:
+1. Defaults the resource parameter to the remote server URL (the canonical URI of the MCP server)
+2. Validates the URI format according to MCP specification requirements
+3. Normalizes the URI (lowercase scheme/host, strips fragments, preserves trailing slashes)
+4. If the resource parameter cannot be derived, then it will not be sent
+
+### Validation Rules
+The resource parameter must conform to MCP canonical URI requirements:
+- **Must** include a scheme (http/https)
+- **Must** include a host
+- **Must not** contain fragments (#)
+
+When the resource parameter is **defaulted** from the remote URL:
+- Scheme and host are normalized to lowercase
+- Fragments are stripped (not allowed in resource indicators per spec)
+- Trailing slashes are preserved (we cannot determine semantic significance)
+
+When the resource parameter is **explicitly provided** by the user:
+- Value is validated but **not modified**
+- Returns an error if the value is invalid
+- User must provide a properly formatted canonical URI
+
+### Examples
+```bash
+# Automatic resource parameter (defaults and normalizes to remote URL)
+thv run https://MCP.Example.COM/api#section
+# Resource defaults to: https://mcp.example.com/api (normalized, fragment stripped)
+
+# Explicit resource parameter (not modified, must be valid)
+thv run https://mcp.example.com/api \
+  --remote-auth-resource https://mcp.example.com
+
+# Invalid explicit resource parameter with fragment (returns error)
+thv run https://mcp.example.com/api \
+  --remote-auth-resource https://mcp.example.com#fragment
+# Error: invalid resource parameter: resource URI must not contain fragments
+
+# Invalid explicit resource parameter without scheme (returns error)
+thv run https://mcp.example.com/api \
+  --remote-auth-resource mcp.example.com
+# Error: invalid resource parameter: resource URI must include a scheme
+```
+
+The validated and normalized resource parameter is sent in both:
+- Authorization requests (as `resource` query parameter)
+- Token exchange requests (as `resource` parameter)
+
 ## Security Features
 
 ### HTTPS Enforcement
@@ -277,17 +331,18 @@ The `oauth_config` section supports:
 | OAuth 2.1 PKCE | ✅ Compliant | Enabled by default |
 | WWW-Authenticate Parsing | ✅ Compliant | Supports Bearer with realm/resource_metadata |
 | Multiple Auth Servers | ✅ Compliant | Iterates and validates all servers |
-| Resource Parameter (RFC 8707) | ⚠️ Partial | Infrastructure ready, not yet sent in requests |
+| Resource Parameter (RFC 8707) | ✅ Compliant | Automatically defaults to remote server URL, validated and normalized |
 | Token Audience Validation | ⚠️ Partial | Server-side validation support ready |
 
+
+
 ## Future Enhancements
 
 While ToolHive is highly compliant with the current MCP specification, potential improvements include:
 
-1. **Resource Parameter**: Add explicit `resource` parameter to OAuth requests (infrastructure exists)
-2. **Token Audience Validation**: Enhanced client-side validation of token audience claims
-3. **Refresh Token Rotation**: Implement automatic refresh token rotation for long-lived sessions
-4. **Client Credential Caching**: Persist dynamically registered clients across sessions
+1. **Token Audience Validation**: Enhanced client-side validation of token audience claims
+2. **Refresh Token Rotation**: Implement automatic refresh token rotation for long-lived sessions
+3. **Client Credential Caching**: Persist dynamically registered clients across sessions
 
 ## Conclusion
 

pkg/api/v1/workload_service.go

@@ -102,6 +102,13 @@ func (s *WorkloadService) BuildFullRunConfig(ctx context.Context, req *createReq
 		}
 	}
 
+	// Validate user-provided resource indicator (RFC 8707)
+	if req.OAuthConfig.Resource != "" {
+		if err := validation.ValidateResourceURI(req.OAuthConfig.Resource); err != nil {
+			return nil, fmt.Errorf("%w: invalid resource parameter: %v", retriever.ErrInvalidRunConfig, err)
+		}
+	}
+
 	// Default group if not specified
 	groupName := req.Group
 	if groupName == "" {
@@ -152,6 +159,15 @@ func (s *WorkloadService) BuildFullRunConfig(ctx context.Context, req *createReq
 
 		if remoteServerMetadata, ok := serverMetadata.(*registry.RemoteServerMetadata); ok {
 			if remoteServerMetadata.OAuthConfig != nil {
+				// Default resource: user-provided > registry metadata > derived from remote URL
+				resource := req.OAuthConfig.Resource
+				if resource == "" {
+					resource = remoteServerMetadata.OAuthConfig.Resource
+				}
+				if resource == "" && remoteServerMetadata.URL != "" {
+					resource = remote.DefaultResourceIndicator(remoteServerMetadata.URL)
+				}
+
 				remoteAuthConfig = &remote.Config{
 					ClientID:     req.OAuthConfig.ClientID,
 					Scopes:       remoteServerMetadata.OAuthConfig.Scopes,
@@ -160,7 +176,7 @@ func (s *WorkloadService) BuildFullRunConfig(ctx context.Context, req *createReq
 					AuthorizeURL: remoteServerMetadata.OAuthConfig.AuthorizeURL,
 					TokenURL:     remoteServerMetadata.OAuthConfig.TokenURL,
 					UsePKCE:      remoteServerMetadata.OAuthConfig.UsePKCE,
-					Resource:     remoteServerMetadata.OAuthConfig.Resource,
+					Resource:     resource,
 					OAuthParams:  remoteServerMetadata.OAuthConfig.OAuthParams,
 					Headers:      remoteServerMetadata.Headers,
 					EnvVars:      remoteServerMetadata.EnvVars,
@@ -255,6 +271,12 @@ func createRequestToRemoteAuthConfig(
 	req *createRequest,
 ) *remote.Config {
 
+	// Default resource: user-provided > derived from remote URL
+	resource := req.OAuthConfig.Resource
+	if resource == "" && req.URL != "" {
+		resource = remote.DefaultResourceIndicator(req.URL)
+	}
+
 	// Create RemoteAuthConfig
 	remoteAuthConfig := &remote.Config{
 		ClientID:     req.OAuthConfig.ClientID,
@@ -263,6 +285,7 @@ func createRequestToRemoteAuthConfig(
 		AuthorizeURL: req.OAuthConfig.AuthorizeURL,
 		TokenURL:     req.OAuthConfig.TokenURL,
 		UsePKCE:      req.OAuthConfig.UsePKCE,
+		Resource:     resource,
 		OAuthParams:  req.OAuthConfig.OAuthParams,
 		CallbackPort: req.OAuthConfig.CallbackPort,
 		SkipBrowser:  req.OAuthConfig.SkipBrowser,

pkg/api/v1/workloads_types_test.go

@@ -161,6 +161,7 @@ func TestRunConfigToCreateRequest(t *testing.T) {
 				ClientSecret: "oauth-client-secret,target=oauth_secret",
 				Scopes:       []string{"read", "write"},
 				UsePKCE:      true,
+				Resource:     "https://mcp.example.com",
 				OAuthParams:  map[string]string{"custom": "param"},
 				CallbackPort: 8081,
 			},
@@ -176,6 +177,7 @@ func TestRunConfigToCreateRequest(t *testing.T) {
 		assert.Equal(t, "test-client", result.OAuthConfig.ClientID)
 		assert.Equal(t, []string{"read", "write"}, result.OAuthConfig.Scopes)
 		assert.True(t, result.OAuthConfig.UsePKCE)
+		assert.Equal(t, "https://mcp.example.com", result.OAuthConfig.Resource)
 		assert.Equal(t, map[string]string{"custom": "param"}, result.OAuthConfig.OAuthParams)
 		assert.Equal(t, 8081, result.OAuthConfig.CallbackPort)
 

pkg/auth/remote/config.go

@@ -3,9 +3,13 @@ package remote
 import (
 	"encoding/json"
 	"fmt"
+	"net/url"
+	"strings"
 	"time"
 
+	"github.com/stacklok/toolhive/pkg/logger"
 	"github.com/stacklok/toolhive/pkg/registry"
+	"github.com/stacklok/toolhive/pkg/validation"
 )
 
 // Config holds authentication configuration for remote MCP servers.
@@ -98,3 +102,50 @@ func (r *Config) UnmarshalJSON(data []byte) error {
 
 // DefaultCallbackPort is the default port for the OAuth callback server
 const DefaultCallbackPort = 8666
+
+// DefaultResourceIndicator derives the resource indicator (RFC 8707) from the remote server URL.
+// This function should only be called when the user has not explicitly provided a resource indicator.
+// If the resource indicator cannot be derived, it returns an empty string.
+func DefaultResourceIndicator(remoteServerURL string) string {
+	// Normalize the remote server URL
+	normalized, err := normalizeResourceURI(remoteServerURL)
+	if err != nil {
+		// Normalization failed - log warning and leave resource empty
+		logger.Warnf("Failed to normalize resource indicator from remote server URL %s: %v", remoteServerURL, err)
+		return ""
+	}
+
+	// Validate the normalized result
+	if err := validation.ValidateResourceURI(normalized); err != nil {
+		// Validation failed - log warning and leave resource empty
+		logger.Warnf("Normalized resource indicator is invalid %s: %v", normalized, err)
+		return ""
+	}
+
+	return normalized
+}
+
+// normalizeResourceURI normalizes a resource URI to conform to MCP specification requirements.
+// This function performs the following normalizations:
+// - Lowercase scheme and host
+// - Strip fragments
+func normalizeResourceURI(resourceURI string) (string, error) {
+	if resourceURI == "" {
+		return "", fmt.Errorf("resource URI cannot be empty")
+	}
+
+	// Parse the URI
+	parsed, err := url.Parse(resourceURI)
+	if err != nil {
+		return "", fmt.Errorf("invalid resource URI: %w", err)
+	}
+
+	// Normalize: lowercase scheme and host
+	parsed.Scheme = strings.ToLower(parsed.Scheme)
+	parsed.Host = strings.ToLower(parsed.Host)
+
+	// Strip fragment if present (fragments are not allowed in resource indicators)
+	parsed.Fragment = ""
+
+	return parsed.String(), nil
+}

pkg/auth/remote/config_test.go

@@ -0,0 +1,60 @@
+package remote
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/stacklok/toolhive/pkg/logger"
+)
+
+func TestDeriveResourceIndicator(t *testing.T) {
+	t.Parallel()
+	logger.Initialize()
+
+	tests := []struct {
+		name             string
+		remoteServerURL  string
+		expectedResource string
+	}{
+		{
+			name:             "valid remote URL - derive and normalize",
+			remoteServerURL:  "https://MCP.Example.COM/api#fragment",
+			expectedResource: "https://mcp.example.com/api",
+		},
+		{
+			name:             "remote URL with trailing slash - preserve it",
+			remoteServerURL:  "https://mcp.example.com/api/",
+			expectedResource: "https://mcp.example.com/api/",
+		},
+		{
+			name:             "remote URL with port - preserve port",
+			remoteServerURL:  "https://mcp.example.com:8443/api",
+			expectedResource: "https://mcp.example.com:8443/api",
+		},
+		{
+			name:             "empty remote URL - return empty",
+			remoteServerURL:  "",
+			expectedResource: "",
+		},
+		{
+			name:             "invalid remote URL - return empty",
+			remoteServerURL:  "ht!tp://invalid",
+			expectedResource: "",
+		},
+		{
+			name:             "derived resource with query params - preserve them",
+			remoteServerURL:  "https://mcp.example.com/api?token=abc123",
+			expectedResource: "https://mcp.example.com/api?token=abc123",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := DefaultResourceIndicator(tt.remoteServerURL)
+			assert.Equal(t, tt.expectedResource, got)
+		})
+	}
+}

pkg/validation/validation.go

@@ -3,6 +3,7 @@ package validation
 
 import (
 	"fmt"
+	"net/url"
 	"regexp"
 	"strings"
 
@@ -86,3 +87,40 @@ func ValidateHTTPHeaderValue(value string) error {
 
 	return nil
 }
+
+// ValidateResourceURI validates that a resource URI conforms to MCP specification requirements
+// for canonical URIs (RFC 8707).
+// This is used for user-provided values that should not be normalized.
+//
+// According to MCP spec, a valid canonical URI must:
+// - Include a scheme (http/https)
+// - Include a host
+// - Not contain fragments
+func ValidateResourceURI(resourceURI string) error {
+	if resourceURI == "" {
+		return fmt.Errorf("resource URI cannot be empty")
+	}
+
+	// Parse the URI
+	parsed, err := url.Parse(resourceURI)
+	if err != nil {
+		return fmt.Errorf("invalid resource URI: %w", err)
+	}
+
+	// Must have a scheme
+	if parsed.Scheme == "" {
+		return fmt.Errorf("resource URI must include a scheme (e.g., https://): %s", resourceURI)
+	}
+
+	// Must have a host
+	if parsed.Host == "" {
+		return fmt.Errorf("resource URI must include a host: %s", resourceURI)
+	}
+
+	// Must not contain fragments
+	if parsed.Fragment != "" {
+		return fmt.Errorf("resource URI must not contain fragments (#): %s", resourceURI)
+	}
+
+	return nil
+}