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]

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.

[KalleBylin]

Bad timing on my side, opening the discussion right before family vacations :) Opened the small PR for the CLI example.

Regarding the other case, I have been playing around with different options in my mind but it seems like manual covers most use cases. In terms of semantics I think the most important message we are trying to convey is that running the MCP Server requires a non-standard process and the user should manually go through the available documentation.

I see that the SEP is still open, so I can potentially wait until that one is closed before making both changes (addition of manual to the registry_type and the website_url option)

[tadasant]

I think it'd be very reasonable to go ahead and add website_url to our Registry spec now if you want to make the contribution; it's a helpful fallback for this and probably other cases.

I think manual is probably a good idea but is also probably niche enough and won't have client support for a little while that I think that would be reasonable to defer to post-preview-launch here.

[tadasant]

websiteUrl landed so it's definitely ready to work in: #183

[KalleBylin]

Perfect, thanks for the heads-up 💪 I'll aim to pick this up tomorrow if possible

[KalleBylin]

In summary:

• For cases like the embedded in the Snyk CLI, where usage is very similar to standalone servers, we encourage using the same approach by leveraging packages and specifying required arguments, etc.
• For the more custom use cases, like an MCP Server that is embedded and started in a Desktop app, we now provide a websiteUrl field that can be used to point users to a landing page with documentation and instructions on how to use the server. In this case, there is no need to specify packages or remotes if these are not used.

For the latest instructions / best practices refer to the docs and examples.