How should the registry handle MCP servers embedded in apps/CLIs?

[KalleBylin]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

Context

The server.json schema in this registry is designed to describe MCP servers that are distributed through installable artifacts — packages on npm/PyPI/NuGet, container images, downloadable binaries, etc.

This works well when the MCP server has its own distribution channel.

But more MCP servers are now embedded inside other applications or CLI tools without a standalone MCP-specific package or repo. Examples:

Figma Desktop — ships with a built-in MCP server.

Snyk CLI — includes an MCP server in the CLI binary.

If you have the host app installed, you already have the MCP server — but there’s no separate MCP package to point to in the registry.

---

The Gap

The current schema/examples don’t explicitly show how to represent:

• Discovery – How to reference an MCP server that’s part of a larger package.

• Execution – How to specify the canonical command/args to start it.

• Versioning – How to reflect host package version constraints.

• Trust – How to indicate vendor identity when source isn’t public.

Especially if the registry is re-used for an internal enterprise setting, it seems like it would be desirable to be able to register and expose this type of servers as well.

---

Questions

1. Is it within the scope of the registry to include this type of MCP Servers?

2. If so, does it make sense to re-use the existing packages and remotes shapes for embedded MCP servers, or should there be more explicit semantics in the schema for this case?

I went through the current server.json schema/examples, and I searched existing discussions and issues, but was not able to find specific guidance on this. Sorry if it has been covered somewhere else.

---

Current Schema Re-use Approach

If the host app/CLI is installed via a known package registry (npm, PyPI, NuGet, etc.):

Use that registry in registry_name.

Use the official package name in name.

Use runtime_hint and package_arguments to specify how to start MCP mode.

If the embedded MCP server exposes a local HTTP/SSE endpoint (rather than stdio):

Use the existing remotes shape, as in the Remote Server example.

---

Examples

Example 1 – Snyk CLI installed via npm

{
  "name": "snyk-cli-mcp",
  "description": "MCP server provided by the Snyk CLI",
  "status": "active",
  "version_detail": { "version": ">=1.1298.0" },
  "packages": [
    {
      "registry_name": "npm",
      "name": "snyk",
      "version": ">=1.1298.0",
      "runtime_hint": "snyk",
      "package_arguments": [
        { "type": "positional", "value": "mcp" },
        { "type": "positional", "value": "-t" },
        { "type": "positional", "value": "stdio" }
      ]
    }
  ]
}

---

Example 2 – Figma Dev Mode MCP exposed via SSE

{
  "name": "figma-dev-mode-mcp",
  "description": "Figma Dev Mode MCP server exposed by the Figma Desktop app",
  "status": "active",
  "remotes": [
    {
      "transport_type": "sse",
      "url": "http://127.0.0.1:3845/mcp"
    }
  ]
}

---

Discussion Points

1. Is re-using packages and remotes the right way to model embedded servers, or should we add more explicit semantics?

2. Should the schema formally document this pattern so clients can support it consistently?

3. Is there a need for optional metadata such as version mapping between host package and MCP server, or vendor identity?

---

Goal

Agree on whether and how embedded MCP servers should be represented using the existing packages/remotes shapes, or whether the schema should add explicit semantics for this case.

[tadasant]

Thanks for raising this @KalleBylin ! It's a very good callout.

Is it within the scope of the registry to include this type of MCP Servers?

I would say yes. At least for the purpose of discovery. We may want to consider "installation" of some of these variants as out of scope.

If so, does it make sense to re-use the existing packages and remotes shapes for embedded MCP servers, or should there be more explicit semantics in the schema for this case?

One escape hatch I think we could lean on is the concept of a website_url: #183

So for some of the cases you called out, it may make sense to have a fairly light entry that doesn't include much more than top level metadata + a website_url to, for example, understand how to start the Figma Dev Mode MCP Server from Figma Desktop. I don't think we should use localhost URLs in remotes.url. cc @Avish34 for consideration when sanitizing URLs here.

For other cases, like your Snyk example, it seems close enough to the model for starting standalone servers, and fits the schema with CLI args, etc, that we can encourage that approach.

Should the schema formally document this pattern so clients can support it consistently?

Absolutely should document this well somewhere. It's probably a server.json-level concern that extends beyond the Registry, worth documenting in here.

Is there a need for optional metadata such as version mapping between host package and MCP server

What do you mean by this exactly? We already have the ability to declare server-level versions and package-level versions, so that mapping exists in a given instance of server.json.

or vendor identity?

We do already have this notion of a reverse-DNS namespace that forms the foundation for this.

However you're right that we should plan to introduce some notion of "author" that is separate from the top level server name's namespace (have discussed this with @domdomegg and @felixweinberger). Issue here: #29

[KalleBylin]

Thanks @tadasant for looking into this. This sounds like a good path forward.

Concretely, for the two examples I mentioned:

• MCP Servers embedded & launched in other appliciations (e.g., Figma Desktop) — I agree a lightweight entry with a link to vendor instructions is the right approach. Since website_url isn’t yet in the schema and is part of SEP-973, we should probably hold on that for now. Instead, I can open a separate issue proposing an example that uses website_url (or the decided approach) once the SEP is closed.

• Embedded MCP Servers that closely match existing patterns (e.g., Snyk CLI) — This fits cleanly into the existing packages shape using runtime_hint and package_arguments. I can prepare a PR adding it to docs/server-json/examples.md along with a short note in the docs on when to use this pattern for embedded servers.

What do you mean by this exactly? We already have the ability to declare server-level versions and package-level versions, so that mapping exists in a given instance of server.json.

On version mapping, I was probably getting ahead of myself. I was thinking about the case where there might be an embedded server and an independent server (similar to how some providers like Github have an open source version and a remote version).

I was wondering if there needed to be some explicit mapping between these, but don’t think there would be much value. This can be solved by registering them as separate servers and/or providing more information in docs (providing something like website_url )

We do already have this notion of a reverse-DNS namespace that forms the foundation for this.

However you're right that we should plan to introduce some notion of "author" that is separate from the top level server name's namespace (have discussed this with @domdomegg and @felixweinberger. Issue here: #29

For vendor identity I was thinking more in line with the issue you linked, and I think this would be satisfied if we could do something like a reverse DNS lookup of the name. Examples can be updated once that is also closed.

Next steps

I can:

1. Draft PR for the CLI example + guidance in docs/server-json.
2. Open an issue for the embedded in application example, blocked by SEP-973.

Would that help?

[domdomegg]

1. Sounds good!
2. Would be keen to hear more about what a concrete example would look like here. Feels like we can discuss this on this discussion - not sure why an issue would be better? (but fine to open one if I'm missing something)

[KalleBylin]

I potentially misinterpreted the contributing instructions. When I wrote this I understood community agreement as being established in the discussions. So the issue was mostly to keep track of this work that should be done at some point, but currently blocked. I have since then realized the community is active in many other channels of communication (e.g. Discord).

I'm happy to continue the discussion here. I'm thinking

Alternative A: Minimalistic with instructions pushed to publisher docs.

There is the option to go completely minimalistic and follow a format similar to

{
  "name": "com.figma/desktop-devmode",
  "description": "Figma Dev Mode MCP server for providing important design information and context to AI agents generating code from Figma design files",
  "status": "active",
  "version_detail": { "version": "125.4.9" },
  "website_url": "https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Dev-Mode-MCP-Server"
}

If we assume that servers like this are run similar to how it is done in the Figma case (some UI trigger to start the server), then there is no need to know about additional headers or variables that need to be passed to the server. The application should take care of this.

The drawback is that there would be no clear instructions on how to connect to the server. Users would have to go to the docs manually to retrieve this information and set up the connection to the server in the desired host.

Alternative B: Include installation/configuration information

This could be leveraged by hosts like VS Code to set up a connection to the server, but in the case of remotes (which seems like a very natural option in this scenario) this brings up the issue of localhost URLs in remotes.url that was mentioned above.

My feeling is that it is still a bit early to understand how different application developers will embed MCP servers into their applications and the resulting access patterns. So I'm leaning more towards to lightweight approach to start with, and it can be extended with more examples or proposed changes in the future.

[domdomegg]

Ah I should maybe say that I don't think there are super strict rules on what lives between discussions/issues/Discord threads, sorry 😅. But I just think keeping information about the same stuff in the same place is good, so hence my suggestion to keep it here.

I wonder if Alternative C might be to have a package type of 'special' or 'manual' (e.g. as opposed to docker/npm/pypi/etc.) with the website_url? This feels similar to Alternative A, but feels it fits in the model I have in my head for server.json more cleanly.