feat: support upstream MCP proxy profiles without openapi_spec_path

ResolvedProfile.specPath is now string | undefined. Profiles with upstream_mcp
and no openapi_spec_path resolve specPath=undefined instead of throwing
ConfigurationError. MCPServer gains initializeWithoutSpec() and a shared
private initializeProfile(); MCPServerManager branches on specPath != null.
generic-profile.test runner detects upstream proxy profiles and skips spec
loading, calls initializeWithoutSpec, guards beforeEach mockEngine access.
New test profile tests/profiles/upstream-mcp-proxy/ exercises the full path.

Author: David Ruzicka

src/mcp/mcp-server-manager.ts

@@ -68,7 +68,12 @@ export class MCPServerManager {
     const resolved = await this.registry.resolveProfile(profileId);
     const server = new MCPServer(this.logger);
     server.setGlobalFiltering(this.globalFiltering);
-    await server.initialize(resolved.specPath, resolved.profilePath);
+
+    if (resolved.specPath != null) {
+      await server.initialize(resolved.specPath, resolved.profilePath);
+    } else {
+      await server.initializeWithoutSpec(resolved.profilePath);
+    }
     if (this.httpTransport) {
       server.attachHttpTransport(this.httpTransport);
     }

src/mcp/mcp-server.test.ts

@@ -337,6 +337,30 @@ paths:
     });
   });
 
+  describe('initializeWithoutSpec', () => {
+    it('initializes successfully with upstream_mcp proxy profile', async () => {
+      const profilePath = path.join(os.tmpdir(), `proxy-profile-${Date.now()}-${Math.random()}.json`);
+
+      const profile = {
+        profile_name: 'proxy-profile',
+        description: 'Pure upstream proxy',
+        tools: [],
+        upstream_mcp: [{
+          name: 'example',
+          transport: { type: 'http-streamable', url: 'https://example.com/mcp' },
+        }],
+      };
+
+      await fs.writeFile(profilePath, JSON.stringify(profile));
+      try {
+        await expect(server.initializeWithoutSpec(profilePath)).resolves.toBeUndefined();
+        expect(server['profile']!.tools).toHaveLength(0);
+      } finally {
+        await fs.unlink(profilePath);
+      }
+    });
+  });
+
   describe('runStdio', () => {
     it('should connect MCP server via StdioServerTransport', async () => {
       const logger = {

src/mcp/mcp-server.ts

@@ -504,11 +504,16 @@ export class MCPServer {
   }
 
   async initialize(specPath: string, profilePath?: string): Promise<void> {
-    // Load OpenAPI spec
     await this.parser.load(specPath);
     this.logger.info('Loaded OpenAPI spec', { specPath });
+    await this.initializeProfile(profilePath);
+  }
+
+  async initializeWithoutSpec(profilePath: string): Promise<void> {
+    await this.initializeProfile(profilePath);
+  }
 
-    // Load or create MCP profile
+  private async initializeProfile(profilePath?: string): Promise<void> {
     this.appsModel = undefined;
     this.appsFetchCache.clear();
     if (profilePath) {
@@ -526,34 +531,26 @@ export class MCPServer {
         profile: this.profile.profile_name,
         toolCount: this.profile.tools.length,
       });
-      
-      // Check if we should warn about long names
       this.checkToolNameLengths();
     }
 
     this.applyGlobalToolFiltering();
 
-    // Re-create logger with auth config for token redaction
     const authConfigs = this.getAuthConfigs();
     if (authConfigs.length > 0) {
-      // Use first auth config for logger (primary)
       this.logger = this.createLoggerWithAuth(authConfigs[0]);
       this.logger.info('Logger re-configured with auth token redaction', {
         authMethods: authConfigs.length,
       });
     }
 
-    // Setup HTTP client with interceptors
-    // For stdio transport, create client with env token
-    // For HTTP transport, clients are created per-session with user's token
     const baseUrl = this.getBaseUrl();
     const envAuthConfig = this.getEnvBackedAuthConfig();
     const primaryRuntimeAuthConfig = authConfigs.find(config => config.type !== 'oauth');
     const envVarName = envAuthConfig?.value_from_env;
     const envToken = envVarName ? process.env[envVarName] : undefined;
 
     if ((envAuthConfig && envToken) || authConfigs.length === 0 || primaryRuntimeAuthConfig?.type === 'session-cookie') {
-      // Token available in env (stdio) or no auth required - create global client
       const httpClient = this.httpClientFactory.createGlobalClient({
         profile: this.profile,
         baseUrl,
@@ -562,10 +559,9 @@ export class MCPServer {
       });
       this.compositeExecutor = new CompositeExecutor(this.parser, httpClient, this.profile.parameter_aliases);
     } else {
-      // No env token or no auth - will use per-session clients (HTTP transport)
       this.compositeExecutor = new CompositeExecutor(this.parser, undefined, this.profile.parameter_aliases);
     }
-    
+
     this.logger.info('MCP server initialized', {
       baseUrl,
       toolCount: this.profile.tools.length,

src/profile/profile-resolver.test.ts

@@ -74,6 +74,22 @@ describe('profile-resolver', () => {
     await expect(resolveProfileById('missing', profilesDir)).rejects.toThrow('openapi_spec_path');
   });
 
+  it('returns specPath=undefined for upstream_mcp proxy profile with no openapi_spec_path', async () => {
+    const root = await createTempDir();
+    const profilesDir = path.join(root, 'profiles');
+    const profilePath = path.join(profilesDir, 'proxy.json');
+
+    await writeJson(profilePath, {
+      profile_name: 'proxy-profile',
+      profile_id: 'proxy',
+      tools: [],
+      upstream_mcp: [{ server_url: 'https://example.com/mcp' }],
+    });
+
+    const resolved = await resolveProfileById('proxy', profilesDir);
+    expect(resolved.specPath).toBeUndefined();
+  });
+
   it('extracts env vars and auth methods for profile index', async () => {
     const root = await createTempDir();
     const profilesDir = path.join(root, 'profiles');

src/profile/profile-resolver.ts

@@ -17,7 +17,7 @@ export interface ResolvedProfile {
   profileName: string;
   profileAliases?: string[];
   profilePath: string;
-  specPath: string;
+  specPath: string | undefined;
 }
 
 export interface ListedProfile {
@@ -81,6 +81,7 @@ interface ProfileIndexEntry {
   aliases: string[];
   profilePath: string;
   specPathRaw?: string;
+  hasUpstreamMcp: boolean;
 }
 
 const DEFAULT_PROFILES_DIR = 'profiles';
@@ -379,13 +380,21 @@ function normalizeSpecPath(value?: string): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
-function resolveSpecPath(profilePath: string, specPathRaw?: string, overrideSpecPath?: string): string {
+function resolveSpecPath(
+  profilePath: string,
+  specPathRaw?: string,
+  overrideSpecPath?: string,
+  isUpstreamMcpProxy = false,
+): string | undefined {
   const trimmed = normalizeSpecPath(specPathRaw);
   if (!trimmed) {
     const override = normalizeSpecPath(overrideSpecPath);
     if (override) {
       return override;
     }
+    if (isUpstreamMcpProxy) {
+      return undefined;
+    }
     throw new ConfigurationError('Profile is missing openapi_spec_path', { profilePath });
   }
   if (isHttpUrl(trimmed)) {
@@ -425,6 +434,7 @@ async function loadProfileIndexEntry(profilePath: string): Promise<ProfileIndexE
     aliases,
     profilePath,
     specPathRaw: typeof profile.openapi_spec_path === 'string' ? profile.openapi_spec_path : undefined,
+    hasUpstreamMcp: Array.isArray(profile.upstream_mcp) && (profile.upstream_mcp as unknown[]).length > 0,
   };
 }
 
@@ -536,7 +546,7 @@ export async function resolveProfileById(
   }
 
   const match = matches[0];
-  const specPath = resolveSpecPath(match.profilePath, match.specPathRaw, options?.specPathOverride);
+  const specPath = resolveSpecPath(match.profilePath, match.specPathRaw, options?.specPathOverride, match.hasUpstreamMcp);
 
   return {
     profileId: match.profileId,
@@ -594,7 +604,7 @@ export async function resolveProfileFromPath(
     throw new ConfigurationError('Profile file does not look like a valid profile', { profilePath: resolvedPath });
   }
 
-  const specPath = resolveSpecPath(resolvedPath, entry.specPathRaw, options?.specPathOverride);
+  const specPath = resolveSpecPath(resolvedPath, entry.specPathRaw, options?.specPathOverride, entry.hasUpstreamMcp);
 
   return {
     profileId: entry.profileId,

src/testing/generic-profile.test.ts

@@ -240,23 +240,34 @@ testFiles.forEach(testFile => {
       const profileLoader = new ProfileLoader();
       profile = await profileLoader.load(fullProfilePath);
       validateTestAgainstProfile(testDef, profile);
-      const fullSpecPath = resolveOpenApiSpecPath(testDir, files, profile);
 
-      parser = new OpenAPIParser();
-      await parser.load(fullSpecPath);
+      const isUpstreamProxy =
+        Array.isArray(profile.upstream_mcp) &&
+        (profile.upstream_mcp as unknown[]).length > 0 &&
+        !profile.openapi_spec_path;
 
-      const baseUrl = `https://mock-api-${profileName.replace(/[^a-zA-Z0-9-]/g, '-')}.com`;
-      mockEngine = new DynamicMockEngine(parser, baseUrl);
-      mockEngine.start();
+      server = new MCPServer();
 
-      process.env.MCP4_API_TOKEN = 'test-token';
-      process.env.MCP4_API_BASE_URL = baseUrl;
-      originalAllowPrivateNetwork = process.env.MCP4_SSRF_ALLOW_PRIVATE_NETWORK;
-      process.env.MCP4_SSRF_ALLOW_PRIVATE_NETWORK = 'true';
-      configureProfileEnv(profile, baseUrl);
+      if (isUpstreamProxy) {
+        await server.initializeWithoutSpec(fullProfilePath);
+      } else {
+        const fullSpecPath = resolveOpenApiSpecPath(testDir, files, profile);
 
-      server = new MCPServer();
-      await server.initialize(fullSpecPath, fullProfilePath);
+        parser = new OpenAPIParser();
+        await parser.load(fullSpecPath);
+
+        const baseUrl = `https://mock-api-${profileName.replace(/[^a-zA-Z0-9-]/g, '-')}.com`;
+        mockEngine = new DynamicMockEngine(parser, baseUrl);
+        mockEngine.start();
+
+        process.env.MCP4_API_TOKEN = 'test-token';
+        process.env.MCP4_API_BASE_URL = baseUrl;
+        originalAllowPrivateNetwork = process.env.MCP4_SSRF_ALLOW_PRIVATE_NETWORK;
+        process.env.MCP4_SSRF_ALLOW_PRIVATE_NETWORK = 'true';
+        configureProfileEnv(profile, baseUrl);
+
+        await server.initialize(fullSpecPath, fullProfilePath);
+      }
     }, 30000);
 
     afterAll(() => {
@@ -269,6 +280,7 @@ testFiles.forEach(testFile => {
     });
 
     beforeEach(() => {
+      if (!mockEngine) return;
       mockEngine.reset();
       if (testDef.global_mocks) {
         const context = { ...testDef.variables };
@@ -277,6 +289,10 @@ testFiles.forEach(testFile => {
       }
     });
 
+    it('server initializes successfully', () => {
+      expect(server['profile']).toBeDefined();
+    });
+
     testDef.scenarios.forEach(scenario => {
       it(scenario.name, async () => {
         // Prepare context

tests/profiles/upstream-mcp-proxy/profile.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "../../profile-schema.json",
+  "profile_name": "upstream-mcp-proxy",
+  "profile_id": "upstream-mcp-proxy",
+  "description": "Generic test profile for pure upstream MCP proxy — no local OpenAPI tools",
+  "tools": [],
+  "upstream_mcp": [
+    {
+      "name": "test-upstream",
+      "transport": {
+        "type": "http-streamable",
+        "url": "https://upstream.example.com/mcp"
+      }
+    }
+  ]
+}

tests/profiles/upstream-mcp-proxy/profile.test.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../../../src/testing/test-schema.ts",
+  "profile_name": "upstream-mcp-proxy",
+  "scenarios": [],
+  "coverage": {
+    "require_all_actions": false,
+    "skip_actions": {}
+  }
+}