Clarify artifacts/configuration plan mismatch and define the composition layer

[lbroudoux]

As of today, there's kind of a "mismatch" in Reshapr concepts regarding how and where we compose capabilities for an MCP Server exposed via Reshapr. I use quotes around mimatch because I am not even it is one, but it needs at least clarification if not
refactoring. I'd like to start the discussion, as shifting things a bit can lead to some consequences in the way we use and define Reshapr API, as well as the way we name the MCP Server/Exposition endpoints.

Let's start with a reminder on how concepts in Reshapr are used today with the following schema:

From bottom to top:

• Service is discovered via a specification import (ex: an OpenAPI spec file). It defines the available operations with input/output interfaces,
• On top of a service, you can attach Artifacts like Prompts, Resources, CustomTools or OutputFilters that bring enriched capabilities to the Service. Today, you can have just one artifact of each kind, and once loaded in Reshapr, those capabilities are always applied. This means that Service + Artifact is actually the default implied layer where the composition of capabilities is defined.
• ConfigurationPlan allows the application of runtime settings to a Service - typically, it's security and backend connection options,
• MCP Server is the concrete result of the exposition of a Configuration Plan on one or many Gateways (via the concept of Gateway Groups which is out of scope here). MCP Servers endpoint names are deduced from the Service coordinates - eg. /mcp/<org_id>/< service_name>/<service_version - or from the exposition ID - eg. /mcp/<id>

This approach is fairly simple but leads to a set of limitations IMHO:

• You can't split Prompts, Resources, CustomTools or OutputFilters on multiple artifact files. Imagine a Service with a dozen operations, this can lead to maintenance issues,
• You can't define/override capabilities for different use-cases or different populations of users. Even if you can deploy multiple configuration plans / MCP Servers connected to different backends and configured with different security options, you'll will have the same output filters or the same custom tool definition on each of them.
• As the MCP Server endpoint names are deduced from the Service coordinates - eg. /mcp/< service_name>/<service_version - you don't really know which configuration plan you're running, and that prevents you from running 2 different configuration plans / MCP Servers on the same Gateway! This is something you must be careful with when deploying the configuration.

The workaround to the above limitations is, in fact, to import multiple times the same OpenAPI spec but with different service names and versions to finally have multiple Services to which you can attach different artifacts, ... This is indeed a diversion of the initial intent of renaming / reversioning that was added to be able to split badly designed OpenAPI (one covering mulitple business domaines for example).

When I mentioned a "mismatch" above, I actually referred to the artifact's position, which by nature is closer to the Service where it should actually be closer to the Configuration Plan as they represent capabilities you might be able to pick and choose from.

As a consequence, I thought of another way of representing things that I submit for discussion. Here is the representation I have at the moment:

The main difference here is that there is no longer the constraint of having only one artifact of each kind: we should be able to attach as many artifacts as we want, depending on our strategy (splitting for maintenance purposes or for use-case separation purposes). As a consequence, the proposition is also to be able to recompose artifacts as needed when establishing a ConfigurationPlan. Plans could hold an includedArtifacts property that allows selecting only the artifacts (and thus capabilities) that will be applied when running a plan through an MCP Server. Reasonably, we could imagine having a default value for includedArtifacts that is set to * so that the existing behaviour will be kept if you don't want/need to cherry-pick capabilities.

The benefits of the new model are that you can now have a single definition of a Service, but yet have it made accessible through different MCP Servers that cover different use-cases (think: different workflows, different populations of users) with different capabilities enabled or disabled, thanks to ConfigurationPlan composition.

As a consequence, and to allow deterministic use of the correct configuration, I think we should adapt or enrich the way we compose MCP Server endpoint names. Moreover, referencing an Exposition from the Service name and version is too fuzzy; we must systematically use the configuration plan name as well.

I propose we adopt the following naming and conventions:

• /mcp/<org_id>/<service_name>/<service_version> can be kept as a convenient and readable endpoint, but it will only allow you to access the latest deployed configuration plan for a Service on a Gateway => you will have no deterministic/reproducible behaviour in case you made several deployments.
• /mcp/<exposition_id> is the deterministic way of accessing a specific deployed Configuration Plan for a service on a Gateway.

What do you think? Does it make sense? I have the feeling it adds a layer of complexity in the process, but still allows current usage (of redefining multiple services, including all artifacts by default, and using user-friendly endpoint names) to be used. On the other hand, we would now have solutions to handle more complex capabilities composition and reuse scenarios.

I'm looking forward to hearing from you!

[ludovic-pourrat]

Hi @lbroudoux ,

My views on this (sorry if i shortening a bit my answers).

1. A service should only be define once as it represent the backend (logically and physically)
2. The service name shall be provided at configuration and not derived from the title to avoid collisions within a large API ecosystem.
3. User friendly names is a must if you consider the naming as part of the governing and urbanization process
4. Effectively the configurations shall be defined as entities and attachable to any configurations to be reusable across services (the rate limiting is a good example where you might define tiers to be assigned to individual tools).
5. In my view it make sense to have different MCP servers for different uses case pointing to the same backend service

My 2 cents

[yada]

I agree with the direction: Service should remain the stable backend/API definition, while ConfigurationPlan should become the place where runtime exposure is composed.

I would split the concern slightly:

• Keep specification artifacts close to the Service, since they define the backend operations.
• Move selectable capability Artifacts closer to ConfigurationPlan, or introduce a composition layer referenced by ConfigurationPlan.
• Allow multiple Artifacts of the same kind, but only with clear merge/conflict rules, so two files cannot silently define the same prompt, resource, custom tool, or output filter with different meanings.
• Keep the default behavior as “include all Artifacts” for backward compatibility.

For endpoints, I agree that /mcp/<service_name>/<service_version> is friendly but not deterministic once several ConfigurationPlans exist. It should resolve only when unambiguous/default, or be documented as a convenience alias.

The deterministic endpoint should identify the Exposition, because the Exposition is the concrete deployed MCP Server on a Gateway: it binds a ConfigurationPlan to a Gateway/Gateway Group and therefore represents the actual runtime access point. I would prefer a typed form like /mcp/e/<exposition_id>, or the more explicit /mcp/expositions/<exposition_id>, to avoid ambiguity with service-based routes because /mcp/<service_id is already in the current gateway) and make it clear what kind of identifier is being used.

Conceptually, I clearly agree with using the Exposition identity as the stable access path.

[yada]

Hi @lbroudoux ,

My views on this (sorry if i shortening a bit my answers).

1. A service should only be define once as it represent the backend (logically and physically)
2. The service name shall be provided at configuration and not derived from the title to avoid collisions within a large API ecosystem.
   .../...

I think it is better to keep the easy path where names/versions are derived from the spec. The Service name/version can already be overridden for explicit name/version for governed environments. So, your point is already covered IMHO.

[lbroudoux]

Thanks for your comments and inputs. I'll try to address those below:

1. A service should only be define once as it represent the backend (logically and physically)

Agreed on this point, and that's a collateral of my proposition: to not have to artificially redefine/reimport the same Service for the sake of making it available through different use-cases.

2. The service name shall be provided at configuration and not derived from the title to avoid collisions within a large API ecosystem.

I agree with @yada here regarding the easy path where names/versions are derived from the spec. But as said above, you can explicitly set service name and version if you want/need to dissociate service identification from API identification. So this point is covered.

3. User friendly names is a must if you consider the naming as part of the governing and urbanization process

Agree here, and the point then is that /mcp/<exposition_id> (or /mcp/e/<exposition_id> as suggested by @yada). is not really user-friendly ... we can argue that URLs don't have to be user-friendly, as they are technical elements but I also like when they carry some sense or intent ... Maybe one thing we can introduce here is the concept of an optional Exposition name, that would have to be unique throughout an organization? That way we could have URLs like /mcp/{org_id}/{exposition_name} where exposition_name can be either derived from service name/version + configuration plan name or customized by user to carry meaningful information. What do you think?

4. Effectively, the configurations shall be defined as entities and attachable to any configurations to be reusable across services (the rate limiting is a good example where you might define tiers to be assigned to individual tools).

I think that's a different need here that we don't address at the moment, but that would be interesting to dig further... We could have some elements of ConfigurationPlan - like for example, OAuth2 configuration or Header propagation rules - defined as reusable assets and thus attached to and shared by multiple configuration plans. Is it what you have in mind, @ludovic-pourrat?

5. In my view it make sense to have different MCP servers for different use cases pointing to the same backend service

Totally agree and already possible. It's just that, as of today, you may need to redefine multiple times the same Services; where as with the new proposition you'll define Service once and then recompose Configuration plans with different artifacts/capabilities. So I think that in both cases, it's already covered.

Move selectable capability Artifacts closer to ConfigurationPlan, or introduce a composition layer referenced by ConfigurationPlan.

I'm afraid that introducing an additional capabilities composition layer makes things too complex. One thing we could have, though - but it's more a UX concern I think - is to be able to create a new ConfigurationPlan by duplicating an existing one. So if artifact composition has already been done once and we just want to change the security of the backend connection option, it would be easier to duplicate a base configuration plan and adjust options. What do you think @yada? It's also a way to (temporarily) work around your concern of reusable policy assets for Configuration @ludovic-pourrat. What do you think?

Allow multiple Artifacts of the same kind, but only with clear merge/conflict rules, so two files cannot silently define the same prompt, resource, custom tool, or output filter with different meanings.

Yes, that part came to my mind lately... One thing that sounds easily doable here is to extract the capabilities names (tools, resources, prompts, filters) during import of the artifact and to forbid the selection of artifacts defining capabilities of the same name for the same kind (prompts, resources, tools, filters). This is not a perfect way to avoid business and semantic duplication, but it allows at least to detect some naming conflicts that would make the execution fail. Any better idea?

[yada]

Regarding "introducing an additional capabilities composition layer", I agree it could add complexity, as ideally we all want to achieve the objective while keeping it as simple as possible... on the other hand, how can we "duplicate a base configuration plan" from the CLI, or how are we planning to introduce this?

Yes, that part came to my mind lately... One thing that sounds easily doable here is to extract the capabilities names (tools, resources, prompts, filters) during import of the artifact and to forbid the selection of artifacts defining capabilities of the same name for the same kind (prompts, resources, tools, filters). This is not a perfect way to avoid business and semantic duplication, but it allows at least to detect some naming conflicts that would make the execution fail. Any better idea?

On this one, maybe we can reject and say, you must fix the issue(s) and list them? As this is not supposed to happen, or maybe I have missed some points/cases?

I think we are all on the same page regarding the other points.

[lbroudoux]

on the other hand, how can we "duplicate a base configuration plan" from the CLI, or how are we planning to introduce this?

Yes, it could be a new CLI command or within the Web UI. When working in GitOps mode with the operator, then it will be just copy/pasting a YAML file 😉

maybe we can reject and say, you must fix the issue(s) and list them

Yes, that's the point. If we previously extracted the capabilities names, then we can look for duplicates and return error message explaining the conflicts to fix.

Also, what do you think about this below proposition:

Maybe one thing we can introduce here is the concept of an optional Exposition name, that would have to be unique throughout an organization? That way we could have URLs like /mcp/{org_id}/{exposition_name} where exposition_name can be either derived from service name/version + configuration plan name or customized by user to carry meaningful information.

[yada]

Yep, CLI copy/paste and UI should work.
+1 for explaining the conflicts to fix and asking to retry.

Regarding /mcp/{org_id}/{exposition_name} will it replace /mcp/<exposition_id> or do the same and "just" introduce a more friendly URL for the same purpose?

[lbroudoux]

Yep, CLI copy/paste and UI should work. +1 for explaining the conflicts to fix and asking to retry.

Regarding /mcp/{org_id}/{exposition_name} will it replace /mcp/<exposition_id> or do the same and "just" introduce a more friendly URL for the same purpose?

It would be just an alternative for a more friendly URL.