Skip to content

First cut at server.json #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
toby merged 3 commits into from
Jul 2, 2025
Merged

First cut at server.json #153

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a72657d
First pass
tadasant Jun 27, 2025
650c70e
Address feedback
tadasant Jun 27, 2025
8041f5f
Simplify schema
tadasant Jun 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/server-json/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# server.json file

There are a variety of use cases where a _static representation of an MCP server_ is necessary:
- Discoverability on a centralized registry (i.e. our official Registry work)
- Discoverability on a decentralized `.well-known` endpoint
- As a response to an initialization call, so the client knows information about the MCP server to which it is connecting
- As an input into crafting a [DXT file](https://www.anthropic.com/engineering/desktop-extensions)
- Packaged in with the source code of an MCP server, so as to have a structured way context

All of these scenarios (and more) would benefit from an agreed-upon, standardized format that makes it easy to port around and maintain a consistent experience for consumers and developers working with the data. At the end of the day, it's all the same data (or a subset of it). MCP server maintainers should have to manage one copy of this file, and all these use cases can serve that file (or a programmatic derivative/subset of it).

Please note: this is different from the file commonly referred to as `mcp.json`, which is _an MCP client's configuration file for **running** a specific set of MCP servers_. See [this issue](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/292).

References:
- [schema.json](./schema.json) - The official JSON schema specification for this representation
- [examples.md](./examples.md) - Example manifestations of the JSON schema
326 changes: 326 additions & 0 deletions docs/server-json/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,326 @@
# Server JSON Examples

## Basic Server with NPM Package

```json
{
"name": "io.modelcontextprotocol/brave-search",
"description": "MCP server for Brave Search API integration",
"repository": {
"url": "https://github.com/modelcontextprotocol/servers",
"source": "github",
"id": "abc123de-f456-7890-ghij-klmnopqrstuv"
},
"version_detail": {
"version": "1.0.2",
"release_date": "2023-06-15T10:30:00Z"
},
"packages": [
{
"registry_name": "npm",
"name": "@modelcontextprotocol/server-brave-search",
"version": "1.0.2",
"environment_variables": [
{
"name": "BRAVE_API_KEY",
"description": "Brave Search API Key",
"is_required": true,
"is_secret": true
}
]
}
]
}
```

## Filesystem Server with Multiple Packages

```json
{
"name": "io.modelcontextprotocol/filesystem",
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
"repository": {
"url": "https://github.com/modelcontextprotocol/servers",
"source": "github",
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
},
"version_detail": {
"version": "1.0.2",
"release_date": "2023-06-15T10:30:00Z"
},
"packages": [
{
"registry_name": "npm",
"name": "@modelcontextprotocol/server-filesystem",
"version": "1.0.2",
"package_arguments": [
{
"type": "positional",
"value_hint": "target_dir",
"description": "Path to access",
"default": "/Users/username/Desktop",
"is_required": true,
"is_repeated": true
}
],
"environment_variables": [
{
"name": "LOG_LEVEL",
"description": "Logging level (debug, info, warn, error)",
"default": "info"
}
]
},
{
"registry_name": "docker",
"name": "mcp/filesystem",
"version": "1.0.2",
"runtime_arguments": [
{
"type": "named",
"description": "Mount a volume into the container",
"name": "--mount",
"value": "type=bind,src={source_path},dst={target_path}",
"is_required": true,
"is_repeated": true,
"variables": {
"source_path": {
"description": "Source path on host",
"format": "filepath",
"is_required": true
},
"target_path": {
"description": "Path to mount in the container. It should be rooted in `/project` directory.",
"is_required": true,
"default": "/project"
}
}
}
],
"package_arguments": [
{
"type": "positional",
"value_hint": "target_dir",
"value": "/project"
}
],
"environment_variables": [
{
"name": "LOG_LEVEL",
"description": "Logging level (debug, info, warn, error)",
"default": "info"
}
]
}
]
}
```

## Remote Server Example

```json
{
"name": "Remote Filesystem Server",
"description": "Cloud-hosted MCP filesystem server",
"repository": {
"url": "https://github.com/example/remote-fs",
"source": "github",
"id": "xyz789ab-cdef-0123-4567-890ghijklmno"
},
"version_detail": {
"version": "2.0.0",
"release_date": "2024-01-20T14:30:00Z"
},
"remotes": [
{
"transport_type": "sse",
"url": "https://mcp-fs.example.com/sse"
}
]
}
```

## Python Package Example

```json
{
"name": "weather-mcp-server",
"description": "Python MCP server for weather data access",
"repository": {
"url": "https://github.com/example/weather-mcp",
"source": "github",
"id": "def456gh-ijkl-7890-mnop-qrstuvwxyz12"
},
"version_detail": {
"version": "0.5.0",
"release_date": "2024-02-10T09:15:00Z"
},
"packages": [
{
"registry_name": "pypi",
"name": "weather-mcp-server",
"version": "0.5.0",
"runtime_hint": "uvx",
"environment_variables": [
{
"name": "WEATHER_API_KEY",
"description": "API key for weather service",
"is_required": true,
"is_secret": true
},
{
"name": "WEATHER_UNITS",
"description": "Temperature units (celsius, fahrenheit)",
"default": "celsius"
}
]
}
]
}
```

## Complex Docker Server with Multiple Arguments

```json
{
"name": "mcp-database-manager",
"description": "MCP server for database operations with support for multiple database types",
"repository": {
"url": "https://github.com/example/mcp-database",
"source": "gitlab",
"id": "ghi789jk-lmno-1234-pqrs-tuvwxyz56789"
},
"version_detail": {
"version": "3.1.0",
"release_date": "2024-03-05T16:45:00Z"
},
"packages": [
{
"registry_name": "docker",
"name": "mcp/database-manager",
"version": "3.1.0",
"runtime_arguments": [
{
"type": "named",
"name": "--network",
"value": "host",
"description": "Use host network mode"
},
{
"type": "named",
"name": "-e",
"value": "DB_TYPE={db_type}",
"description": "Database type to connect to",
"is_repeated": true,
"variables": {
"db_type": {
"description": "Type of database",
"choices": ["postgres", "mysql", "mongodb", "redis"],
"is_required": true
}
}
}
],
"package_arguments": [
{
"type": "named",
"name": "--host",
"description": "Database host",
"default": "localhost",
"is_required": true
},
{
"type": "named",
"name": "--port",
"description": "Database port",
"format": "number"
},
{
"type": "positional",
"value_hint": "database_name",
"description": "Name of the database to connect to",
"is_required": true
}
],
"environment_variables": [
{
"name": "DB_USERNAME",
"description": "Database username",
"is_required": true
},
{
"name": "DB_PASSWORD",
"description": "Database password",
"is_required": true,
"is_secret": true
},
{
"name": "SSL_MODE",
"description": "SSL connection mode",
"default": "prefer",
"choices": ["disable", "prefer", "require"]
}
]
}
]
}
```

## Server with Remote and Package Options

```json
{
"name": "hybrid-mcp-server",
"description": "MCP server available as both local package and remote service",
"repository": {
"url": "https://github.com/example/hybrid-mcp",
"source": "github",
"id": "klm012no-pqrs-3456-tuvw-xyz789abcdef"
},
"version_detail": {
"version": "1.5.0",
"release_date": "2024-04-01T12:00:00Z"
},
"packages": [
{
"registry_name": "npm",
"name": "@example/hybrid-mcp-server",
"version": "1.5.0",
"runtime_hint": "npx",
"package_arguments": [
{
"type": "named",
"name": "--mode",
"description": "Operation mode",
"default": "local",
"choices": ["local", "cached", "proxy"]
}
]
}
],
"remotes": [
{
"transport_type": "sse",
"url": "https://hybrid-mcp.example.com/sse",
"headers": [
{
"name": "X-API-Key",
"description": "API key for authentication",
"is_required": true,
"is_secret": true
},
{
"name": "X-Region",
"description": "Service region",
"default": "us-east-1",
"choices": ["us-east-1", "eu-west-1", "ap-southeast-1"]
}
]
},
{
"transport_type": "streamable",
"url": "https://hybrid-mcp.example.com/stream"
}
]
}
```
Loading
Loading