Add RFC 0004: MCP Registry

[jonburdo]

Adds a design for an MCP registry in MLflow, aligned with the upstream MCP registry specification.

mlflow issue: mlflow/mlflow#22625

authored by: @jonburdo @dkuc @mprahl

[Copilot]

Pull request overview

This PR adds RFC 0004 proposing an MLflow-native “MCP Registry” design aligned with the upstream Model Context Protocol registry spec, including a proposed data model, API surface, and a reference database migration.

Changes:

• Adds an RFC document describing entities, lifecycle, schema, store interfaces, REST API, SDK, CLI, UI, and trace linking.
• Adds a reference Alembic migration that creates the proposed MCP registry tables and index.

Reviewed changes

Copilot reviewed 2 out of 4 changed files in this pull request and generated 2 comments.

File	Description
rfcs/0004-mcp-registry/0004-mcp-registry.md	Full design RFC for the MCP Registry feature (schema, APIs, SDK/CLI, UI, trace linking, adoption plan).
rfcs/0004-mcp-registry/alembic-migration.py	Reference Alembic migration implementing the proposed schema (tables for servers, versions, tags, aliases).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[B-Step62]

It is a bit unclear to me when users should create a new version. Usually the actual server implementationis managed on github, and if it is distributed as a public package, it has a package version. Also if the server is hosted somewhere, the runtime has deployment version. Does the version defined in MLflow strictly ties to any of these, or adding a new semantic versioning on top of them?

[mprahl]

The stored version is the canonical server_json["version"] provided by the publisher, not an additional MLflow specific version. Deployment or runtime revisions belong in mutable runtime_metadata. Users register a new version when the canonical server definition changes, and update runtime_metadata when only the deployment of that server definition changes.`

[B-Step62]

While the separation of registry and runtime makes sense from system perspective, the actual use case always requires some sort of runtime, which can influence the design of the registry data model.

1. Local (e.g. install local mcp server to coding agent)
2. MLflow MCP Gateway
3. Other hosted services

Did you assume one or multiple of these runtime options as a downstream use case?

[mprahl]

The design intentionally assumes multiple downstream runtime models and aims to be runtime-agnostic. In other words, the same registry entry should be usable by local agent installs, an MLflow MCP Gateway, or other hosted runtimes. Optional deployment-association fields such as runtime_metadata and is_deployed support deployment discovery within an organization, while remaining intentionally unopinionated about runtime-specific details.

[B-Step62]

Is there any potential benefit of supporting bi-directional linking (i.e. search traces that uses a particular mcp server version)? If yes, we can use EntityAssociationTable rather than trace tags.

[mprahl]

Yes, I think that's a good idea!

[B-Step62]

How end-users should connect to the server? One option is not go through the registry at all and simply let them specify to the downstream runtime URL. However, this option does not resolve usage control and tracing problem. To achieve that, end users should access MCP servers using MLflow's name and version. However, it is more like discovery problem (like DNS) or a gateway layer, so the current pure registry scope might not be sufficient for addressing some of these problems.

[mprahl]

Good point. This RFC is intended to cover the registry/discovery layer, not a gateway/proxy layer, so it does not by itself solve end-user connectivity or enforce usage control for arbitrary direct access.

The RFC's expectation is that MLflow-aware clients/runtimes resolve an MCP server via MLflow by name + version (or alias), then use deployment-specific information from runtime_metadata and server_json to connect. Trace linking follows the same assumption: it works when resolution happens through MLflow or when the runtime/server explicitly links {name, version} back to MLflow. A consumer can obviously bypass MLflow though.

The RFC should make that boundary clearer and better connect it to the future gateway integration story. I also think we should document a small set of recommended runtime_metadata conventions, such as endpoint_url, without making the field prescriptive. If/when the MLflow AI Gateway expands to be an MCP Gateway, it could reuse these runtime_metadata fields to steer users to the gateway to link trace data.

[B-Step62]

Can we list unique values of using MLflow registry over the Github's public registry? It appears to be basically a private registry (analogy of private pypi/npm index), with a few extra features such as lifecycle labeling and usage tracking, is my understanding correct?

[mprahl]

The MLflow MCP Registry is not trying to replace the upstream/public registry, but to provide an MLflow-native governed registry for enterprise use cases.

Relative to a public GitHub-hosted registry, the main added value here is:

1. workspace-scoped governance and permissions within MLflow
2. lifecycle state management for versions (active / deprecated / deleted)
3. stable aliases for resolution (for example, production)
4. association of governed MCP definitions with deployment-specific metadata via runtime_metadata
5. MLflow-native trace linking / observability when clients or runtimes resolve MCP servers through MLflow-aware flows
6. future integration with other MLflow components such as the AI Gateway

So I would describe it more as a governed enterprise registry that reuses the upstream MCP metadata model, while adding MLflow-specific management and integration capabilities.

I'll update the RFC with this distinction.

[TomeHirata]

I agree that the workspace and permission management are missing in the official mcp registry (btw the official registry supports lifecycle management and versioning).
For alias, can we describe the use cases where alias is useful, since usually only the latest version can be available, and it's not clear how users use different MCP server versions based on the stage (dev, stg, prd).
For tracing, users should be able to track the MCP server info on traces as long as tracing is enabled for the client. What challenge do users have when tracing their agent's mcp usage without using MLflow MCP registry?

[mprahl]

I addressed this in the last commit I pushed. Please take a look!

[HumairAK]

This is intended to complement, not replace, the public GitHub-hosted MCP registry.

I think this can be a great point of confusion, since on the surface there's some overlapping elements and terminologies. A brief note about how these would complement each other would be beneficial.

As a user I will want to know how I should use these two in my workflow.

[mprahl]

@B-Step62 I addressed your comments in the latest commit, please take a look!

[Copilot]

Pull request overview

Copilot reviewed 2 out of 4 changed files in this pull request and generated 9 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 3 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[TomeHirata]

When/how is the server status modified? Also does it return servers, or versions?

[jonburdo]

Status lives on versions, not servers (there's no status column on mcp_servers). Server status is derived from the latest server version at query time. Filtering search_mcp_servers by status should be feasible using a subquery + JOIN pattern similar to how MLflow model registry does it for tag filters on search_model_versions (tags live in SqlModelVersionTag, resolved via subquery join).

Maybe I can update the doc to make it clearer, and to highlight difference between these two:

mlflow mcp-servers search --filter "status = 'active'"  # get server (uses subquery)
mlflow mcp-server-versions search --filter "status = 'active'"  # get server version (simpler query internally)

[jonburdo]

Clarified here and also described here

[TomeHirata]

nit: users should be able to configure which mcp server are available for which end user/agent

[jonburdo]

Is this clearer:

• Control which MCP servers are available to specific users, teams, or agents

Let me know if I've missed what you're getting at :)

[TomeHirata]

Why do we want to define this mixin as part of model_registry?

[jonburdo]

The idea was to follow the same pattern as GatewayStoreMixin on the tracking store, but this is closer in function to model registry, so it could share the model registry AbstractStore for simplicity. That said, a standalone store (e.g. mlflow/store/mcp_registry/) would also work, but it would require more work. (Or we could use tracking store instead of model registry store)

[TomeHirata]

Since mcp gateway is closer to llm gateway and we have ai gateway resources in the tracking store, I think we should use tracking store

[mprahl]

I updated the RFC to place the MCP registry mixin under the tracking store, following the same composition pattern as the gateway code rather than the model registry store.

[TomeHirata]

First of all, can we clarify the difference between MCP Registry and the MCP gateway (e.g., portkey), and why we want to introduce the MCP registry? We will certainly add MCP gateway as that's a clear tablestake as an ai gateway product, and I wonder if gateway and registry are two distinct features, or can be unified. If these are separate concepts, I need to think carefully about the potential confusions that users may have when seeing MCP gateway and registry in the same platform.

[mprahl]

Good point. I updated the RFC to make the registry vs. gateway split more explicit.

Short version: this RFC is for the registry/control-plane piece, not the MCP gateway/runtime piece. The registry is the governed source of truth for canonical MCP server definitions, version history, aliases, and approved deployment locations. That gives us enterprise governance and historical records that a gateway alone would not provide.

A future MCP gateway in MLflow AI Gateway would then consume those governed records for live MCP traffic, while the registry continues to provide the canonical identity/history behind what the gateway is serving. That also improves traceability, since gateway-produced traces can be linked back to the governed MCP server/version records rather than only to a live endpoint.

I added more detail in Summary, Registry vs. Gateway, and MCPHostedBinding.

[TomeHirata]

Note - If we will provide MCP gateway, this is an essential feature

[mprahl]

Agreed. The RFC now makes that boundary clearer: it does not design the MCP gateway itself, but it does shape the registry so it can integrate cleanly with a future MCP gateway in MLflow AI Gateway.

The main value the registry adds beyond the gateway is governed historical state: canonical definitions, version/alias history, and approved deployment locations. That gives us enterprise governance and a better source of truth for linking gateway output traces back to the MCP server/version that was actually in use. See Summary, Registry vs. Gateway, and MCPHostedBinding sections for more details.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 3 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[TomeHirata]

MCP gateway still needs to store a list of MCP server configurations, so there are some overlaps. I think the relationship is probably MCP gateway = subset of MCP registry capabilities + runtime proxy, authentication, observability. Can we clarify this overlap and how we plan to unify them?

[mprahl]

Could you please check if the last commit addresses this the way you expected?

[TomeHirata]

nit: Can we rephrase a bit so that it's clear that MCP gateway will be built on top of the registry layer described in this RFC?

[mprahl]

Addressed in the last commit.

[TomeHirata]

So when admin wants to add a new version for production, do they need to both update alias and create a new binding?

[mprahl]

If they move the alias to the new MCPServer entity, then the binding stays the same. If the binding is tied to a version, then the binding must change to point to the new version.

[TomeHirata]

For me to understand, what's the use case of setting a different mcp server endpoint from the one in server_json? When the server host is updated, shouldn't users just create a new version with the new host url?

[TomeHirata]

If this is just meant for the "approval status" we can have another column in the mcp server version entity for it.

[mprahl]

@TomeHirata the remotes in server_json may not be present (e.g. requires on-premise deployment) or the access binding may be pointing to a gateway endpoint.

The goal is that server_json can be taken directly from the publisher and is treated as immutable. The access bindings are how we communicate the catalog of what is deployed/available for use.

An alternative could be to require the admin to manually modify the server_json and allow modifying only the remotes field in server_json, however, it's limiting and would not provide a good unifying experience for direct access + MCP gateway.

[TomeHirata]

Understood the intention, thanks for the clarification. Regarding the data model, is it better to be a separate entity? I wonder if it fits better if we have a separate mutable column in ServerVersion. Also let's not mix this with gateway endpoint since the binding/deployment url is the location the actual MCP server is hosted and MCP gateway will invoke the url internally anyway.

[jonburdo]

I think we want a separate entity because:

1. independent lifecycle - endpoints get added/moved/removed without touching the governed version record
2. alias-targeted bindings - a binding can target an alias like production rather than a concrete version, which doesn't fit as a column on a version row
3. gateway extensibility - keeping bindings decoupled lets a future MCP Gateway reuse the same concept with additional gateway-specific fields

The separation also enables two complementary UI experiences: access bindings as a catalog of what's currently available/deployed in the organization, and the registry (MCPServer/MCPServerVersion) as the governed historical record.

Agreed on the gateway point - the binding URL is where the actual server is hosted, not a gateway endpoint.

[B-Step62]

Can "access-binding" be renamed to "deployment"? I feel like it would match more nicely with the MCP Gateway path.

[jonburdo]

These are really pointers to already-running endpoints. In a previous comment, @HumairAK actually flagged the same concern from the other direction (suggesting has_active_binding over is_deployed). Even in consideration of the eventual unified registry/gateway experience, I think "binding" keeps the distinction clear - a record of where a governed server can be reached, not a record of something MLflow necessarily deployed.

[HumairAK]

I am not very strongly opinionated here, but I do think "deployment" in the context of mcp servers can give the impression we are offering server deployment capabilities. When the server is an already deployed remote service that we are creating a route to (via gateway proxy or otherwise). In my opinion you create or connect endpoints to live services, and you deploy services themselves.

I suppose you could you could say you are "deploying" an endpoint that points to a server "deployment" that is also "deployed", but it feels a bit confusing. However, if this terminology is already being used elsewhere in MLflow gateway, then maybe it's better to just be consistent and stick to deployment.

[B-Step62]

Can we elaborate this step? Is the permission here only for discovery not access control of the server itself, because registry is not a part of the access flow from end users?

[B-Step62]

Tbh I'm not sure if there is a much benefit in setting permissions for discovery.

• For remote server, admins will put the access control on the endpoints. This is governed by MLflow if they use MLflow MCP Gateway, otherwise configured at their hosting service.
• The local package governance seems to be easily bypassed by end users. While admin can control which version/server can be seen on MLflow registry, users can still use any servers locally or tweak canonical server_json. To strictly control which version and server is used by the end users, which I guess what many organizations want, they need to gate at installation not discovery, for instance, hosting internal npm proxy with subset of mcp packages.

In either case, setting up a separate permission for discovering the server in MLflow seem to be duplicate effort.

I might be wrong, but it feels like the more realistic operation would be all servers are discoverable, but to use the server, developers need permissions granted by admins. Are requirements you heard from enterprise customers different?

[jonburdo]

The registry permissions are really for management operations (register, update, deprecate, delete), not runtime access control. Agreed that all servers should probably be discoverable within a workspace - workspace scoping handles visibility, per-resource permissions handle who can modify state. I think this follows the existing MLflow patterns in Model Registry, Prompt Registry

[mprahl]

We can also just remove that line if it's confusing.

[jonburdo]

I've removed the line from both stories. Our permission model here just follows existing mlflow patterns

[TomeHirata]

Let's remove this due to https://github.com/mlflow/rfcs/pull/12/changes#r3192622469 and update "Future gateway relationship" section

[jonburdo]

Agreed, I've removed the subclass example. A future gateway entity would follow the same parent/target resolution pattern, but whether it shares implementation with access bindings (subclass, mixin, etc.) is an implementation detail we can decide later.

I also updated the "Future gateway relationship" section accordingly

[TomeHirata]

Given the e2e user journey, shouldn't we allow users to attach an alias to MCPAccessBinding rather than attaching it to MCPServerVersion and linking it to MCPAccessBinding? I think there's a scenario where the same MCP server definition is used across STG and PRD, but endpoints differ between environments. The current data model doesn't tell us which endpoint is for which environment since the alias is attached to MCPServerVersion rather than MCPAccessBinding, while the endpoint url is a field of MCPAccessBinding.

[jonburdo]

I think the current model already handles this scenario. A binding targets an alias rather than being labeled by one - so a binding with alias=production and endpoint_url=prd.example.com tells you both the environment and the endpoint. When you promote by moving the alias, the binding automatically resolves to the new version without needing to update the binding itself.

For example, say you have versions v1, v2, v3:

• alias production -> v2, alias staging -> v3
• binding A: alias=production, endpoint_url=prd.example.com
• binding B: alias=staging, endpoint_url=stg.example.com

Promoting v3 to production just means moving the production alias from v2 to v3. Binding A automatically resolves to v3 - no binding update needed. Pinning bindings to concrete versions would lose that indirection and require updating binding records on every promotion.

[TomeHirata]

That promotion workflow is possible, but which API should I use to know the endpoint_url for "production" in the scenario? Since an alias is linked to MCPServerVersion, it's not straightforward to determine the binding from the alias. But in the actual user journey, I'd like to retrieve the set of MCPServerVersion + endpoint id from an alias easily.

[jonburdo]

The binding targets an alias directly via server_alias, so to find the version + endpoints for "production":

version = mlflow.genai.get_mcp_server_version_by_alias(
    name="io.github.anthropic/brave-search",
    alias="production",
)

bindings = mlflow.genai.search_mcp_access_bindings(
    server_name="io.github.anthropic/brave-search",
    filter_string="server_alias = 'production'"
)

Note this is a search rather than a get because alias -> bindings is 1:many. For example, an org might deploy the same server behind two endpoints targeting production - https://mcp-primary.example.com/brave-search and https://mcp-failover.example.com/brave-search - for redundancy. A single get_mcp_server() call also returns all bindings with their alias targets as summaries.

We looked into a name_or_uri approach following the prompt registry pattern (load_prompt("prompts:/my_prompt@production")), but MCP server names use reverse-DNS format with slashes (e.g., io.github.anthropic/brave-search) which conflicts with URI path separators, so the pattern doesn't translate cleanly.

Maybe as a follow-up enhancement we could consider adding server_alias and server_version as direct query parameters / SDK kwargs on the search endpoint to avoid constructing filter_string expressions for these common lookups:

bindings = mlflow.genai.search_mcp_access_bindings(
    server_name="io.github.anthropic/brave-search",
    server_alias="production",
)

GET /ajax-api/3.0/mlflow/mcp-servers/io.github.anthropic%2Fbrave-search/bindings?server_alias=production

[TomeHirata]

Got it, so are we intentionally allowing to have multiple endpoints per alias? I'm honestly not sure if having multiple endpoints is realistic since we can use the same domain with load balancing. But yeah, if it's intentional, the current data model makes sense then. Let's update search_mcp_access_bindings so that it's easier to find endpoints for a specific alias/environment.

[jonburdo]

Yeah, it's intentional - the model doesn't require multiple bindings per alias, but it doesn't prevent it either.

Scenarios where multiple bindings per alias or version are useful

Internal vs external access: An org might expose the same governed server at https://mcp.internal.example.com/brave-search (internal network, no auth) and https://mcp.example.com/brave-search (external, with mTLS). Both target production but serve different network contexts.

Different deployment modes: Consider something like mcp-atlassian, which supports a READ_ONLY_MODE env var. An org could deploy two instances of the same governed server version - one read-only (READ_ONLY_MODE=true) at https://mcp-readonly.example.com/atlassian and one read-write (READ_ONLY_MODE=false) at https://mcp-readwrite.example.com/atlassian - both targeting the same alias but offering different operational guarantees.

Version migration with stable + versioned endpoints: Even with a single binding per alias, you can end up with multiple bindings resolving to the same version. For example:

• binding1 -> alias: production -> resolves to v3 (follows the alias pointer)
• binding2 -> version: v3 (pinned directly)
• binding3 -> version: v2 (legacy clients still on v2)

Each might have its own endpoint: prod.example.com, mcp-v3.example.com, mcp-v2.example.com. When the admin moves production from v2 to v3, binding1 automatically follows while binding3 stays on v2 for legacy clients. This is a natural outcome of the alias + direct-version model.

Agreed on improving search_mcp_access_bindings by adding server_alias and server_version as direct query parameters. However, I will do this as a follow-up enhancement if that's okay, since this RFC has been approved now!

[TomeHirata]

How do we plan to support the stdio connection?

[jonburdo]

Access bindings are specifically for remote endpoints, so stdio doesn't apply here. I've renamed the enum to MCPRemoteTransportType and dropped STDIO from it to make that scoping clearer.

I originally included it since I figured an MCPTransportType would be a general purpose thing and should include all possible types.

[TomeHirata]

Not limited to the bindings, but do we expect users to register stdio MCP servers in this MCP registry? Or is this limited to HTTP connections only? If that's the latter, we should clarify in the RFC.

[jonburdo]

Yeah, stdio servers are supported in the registry. They just wouldn't have an MCPAccessBinding. The registry stores the full server_json payload including packages[].transport.type = "stdio".

There is still value in having stdio servers in the registry for governance, versioning, and discovery - and for linking traces to them.

[TomeHirata]

LGTM once https://github.com/mlflow/rfcs/pull/12/changes#r3199173218 is addressed/answered!

[mprahl]

The latest changes looks good! Perhaps I shouldn't have approved because I'm a coauthor lol. Could @B-Step62 and @TomeHirata take one more look?