Skip to content

Commit 2061151

Browse files
tadasanttoby
tadasant
authored and
toby
committed
First pass
1 parent 443159f commit 2061151

File tree

3 files changed

+713
-0
lines changed

3 files changed

+713
-0
lines changed

‎docs/server-json/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# server.json file
2+
3+
There are a variety of use cases where a _static representation of an MCP server_ is necessary:
4+
- Discoverability on a centralized registry (i.e. our official Registry work)
5+
- Discoverability on a decentralized `.well-known` endpoint
6+
- As a response to an initialization call, so the client knows information about the MCP server to which it is connecting
7+
- As an input into crafting a [DXT file](https://www.anthropic.com/engineering/desktop-extensions)
8+
- Packaged in with the source code of an MCP server, so as to have a structured way context
9+
10+
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).
11+
12+
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).
13+
14+
References:
15+
- [schema.json](./schema.json) - The official JSON schema specification for this representation
16+
- [examples.md](./examples.md) - Example manifestations of the JSON schema

‎docs/server-json/examples.md

Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
# Server JSON Examples
2+
3+
## Basic Server with NPM Package
4+
5+
```json
6+
{
7+
"name": "io.modelcontextprotocol/brave-search",
8+
"description": "MCP server for Brave Search API integration",
9+
"repository": {
10+
"url": "https://github.com/modelcontextprotocol/servers",
11+
"source": "github",
12+
"id": "abc123de-f456-7890-ghij-klmnopqrstuv"
13+
},
14+
"version_detail": {
15+
"version": "1.0.2",
16+
"release_date": "2023-06-15T10:30:00Z"
17+
},
18+
"packages": [
19+
{
20+
"registry_name": "npm",
21+
"name": "@modelcontextprotocol/server-brave-search",
22+
"version": "1.0.2",
23+
"environment_variables": [
24+
{
25+
"name": "BRAVE_API_KEY",
26+
"description": "Brave Search API Key",
27+
"is_required": true,
28+
"is_secret": true
29+
}
30+
]
31+
}
32+
]
33+
}
34+
```
35+
36+
## Filesystem Server with Multiple Packages
37+
38+
```json
39+
{
40+
"name": "io.modelcontextprotocol/filesystem",
41+
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
42+
"repository": {
43+
"url": "https://github.com/modelcontextprotocol/servers",
44+
"source": "github",
45+
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
46+
},
47+
"version_detail": {
48+
"version": "1.0.2",
49+
"release_date": "2023-06-15T10:30:00Z"
50+
},
51+
"packages": [
52+
{
53+
"registry_name": "npm",
54+
"name": "@modelcontextprotocol/server-filesystem",
55+
"version": "1.0.2",
56+
"package_arguments": [
57+
{
58+
"type": "positional",
59+
"value_hint": "target_dir",
60+
"description": "Path to access",
61+
"default": "/Users/username/Desktop",
62+
"is_required": true,
63+
"is_repeated": true
64+
}
65+
],
66+
"environment_variables": [
67+
{
68+
"name": "LOG_LEVEL",
69+
"description": "Logging level (debug, info, warn, error)",
70+
"default": "info"
71+
}
72+
]
73+
},
74+
{
75+
"registry_name": "docker",
76+
"name": "mcp/filesystem",
77+
"version": "1.0.2",
78+
"runtime_arguments": [
79+
{
80+
"type": "named",
81+
"description": "Mount a volume into the container",
82+
"name": "--mount",
83+
"value": "type=bind,src={source_path},dst={target_path}",
84+
"is_required": true,
85+
"is_repeated": true,
86+
"variables": {
87+
"source_path": {
88+
"description": "Source path on host",
89+
"format": "filepath",
90+
"is_required": true
91+
},
92+
"target_path": {
93+
"description": "Path to mount in the container. It should be rooted in `/project` directory.",
94+
"is_required": true,
95+
"default": "/project"
96+
}
97+
}
98+
}
99+
],
100+
"package_arguments": [
101+
{
102+
"type": "positional",
103+
"value_hint": "target_dir",
104+
"value": "/project"
105+
}
106+
],
107+
"environment_variables": [
108+
{
109+
"name": "LOG_LEVEL",
110+
"description": "Logging level (debug, info, warn, error)",
111+
"default": "info"
112+
}
113+
]
114+
}
115+
]
116+
}
117+
```
118+
119+
## Remote Server Example
120+
121+
```json
122+
{
123+
"name": "Remote Filesystem Server",
124+
"description": "Cloud-hosted MCP filesystem server",
125+
"repository": {
126+
"url": "https://github.com/example/remote-fs",
127+
"source": "github",
128+
"id": "xyz789ab-cdef-0123-4567-890ghijklmno"
129+
},
130+
"version_detail": {
131+
"version": "2.0.0",
132+
"release_date": "2024-01-20T14:30:00Z"
133+
},
134+
"remotes": [
135+
{
136+
"transport_type": "sse",
137+
"url": "https://mcp-fs.example.com/sse"
138+
}
139+
]
140+
}
141+
```
142+
143+
## Python Package Example
144+
145+
```json
146+
{
147+
"name": "weather-mcp-server",
148+
"description": "Python MCP server for weather data access",
149+
"repository": {
150+
"url": "https://github.com/example/weather-mcp",
151+
"source": "github",
152+
"id": "def456gh-ijkl-7890-mnop-qrstuvwxyz12"
153+
},
154+
"version_detail": {
155+
"version": "0.5.0",
156+
"release_date": "2024-02-10T09:15:00Z"
157+
},
158+
"packages": [
159+
{
160+
"registry_name": "pypi",
161+
"name": "weather-mcp-server",
162+
"version": "0.5.0",
163+
"runtime_hint": "uvx",
164+
"environment_variables": [
165+
{
166+
"name": "WEATHER_API_KEY",
167+
"description": "API key for weather service",
168+
"is_required": true,
169+
"is_secret": true
170+
},
171+
{
172+
"name": "WEATHER_UNITS",
173+
"description": "Temperature units (celsius, fahrenheit)",
174+
"default": "celsius"
175+
}
176+
]
177+
}
178+
]
179+
}
180+
```
181+
182+
## Complex Docker Server with Multiple Arguments
183+
184+
```json
185+
{
186+
"name": "mcp-database-manager",
187+
"description": "MCP server for database operations with support for multiple database types",
188+
"repository": {
189+
"url": "https://github.com/example/mcp-database",
190+
"source": "gitlab",
191+
"id": "ghi789jk-lmno-1234-pqrs-tuvwxyz56789"
192+
},
193+
"version_detail": {
194+
"version": "3.1.0",
195+
"release_date": "2024-03-05T16:45:00Z"
196+
},
197+
"packages": [
198+
{
199+
"registry_name": "docker",
200+
"name": "mcp/database-manager",
201+
"version": "3.1.0",
202+
"runtime_arguments": [
203+
{
204+
"type": "named",
205+
"name": "--network",
206+
"value": "host",
207+
"description": "Use host network mode"
208+
},
209+
{
210+
"type": "named",
211+
"name": "-e",
212+
"value": "DB_TYPE={db_type}",
213+
"description": "Database type to connect to",
214+
"is_repeated": true,
215+
"variables": {
216+
"db_type": {
217+
"description": "Type of database",
218+
"choices": ["postgres", "mysql", "mongodb", "redis"],
219+
"is_required": true
220+
}
221+
}
222+
}
223+
],
224+
"package_arguments": [
225+
{
226+
"type": "named",
227+
"name": "--host",
228+
"description": "Database host",
229+
"default": "localhost",
230+
"is_required": true
231+
},
232+
{
233+
"type": "named",
234+
"name": "--port",
235+
"description": "Database port",
236+
"format": "number"
237+
},
238+
{
239+
"type": "positional",
240+
"value_hint": "database_name",
241+
"description": "Name of the database to connect to",
242+
"is_required": true
243+
}
244+
],
245+
"environment_variables": [
246+
{
247+
"name": "DB_USERNAME",
248+
"description": "Database username",
249+
"is_required": true
250+
},
251+
{
252+
"name": "DB_PASSWORD",
253+
"description": "Database password",
254+
"is_required": true,
255+
"is_secret": true
256+
},
257+
{
258+
"name": "SSL_MODE",
259+
"description": "SSL connection mode",
260+
"default": "prefer",
261+
"choices": ["disable", "prefer", "require"]
262+
}
263+
]
264+
}
265+
]
266+
}
267+
```
268+
269+
## Server with Remote and Package Options
270+
271+
```json
272+
{
273+
"name": "hybrid-mcp-server",
274+
"description": "MCP server available as both local package and remote service",
275+
"repository": {
276+
"url": "https://github.com/example/hybrid-mcp",
277+
"source": "github",
278+
"id": "klm012no-pqrs-3456-tuvw-xyz789abcdef"
279+
},
280+
"version_detail": {
281+
"version": "1.5.0",
282+
"release_date": "2024-04-01T12:00:00Z"
283+
},
284+
"packages": [
285+
{
286+
"registry_name": "npm",
287+
"name": "@example/hybrid-mcp-server",
288+
"version": "1.5.0",
289+
"runtime_hint": "npx",
290+
"package_arguments": [
291+
{
292+
"type": "named",
293+
"name": "--mode",
294+
"description": "Operation mode",
295+
"default": "local",
296+
"choices": ["local", "cached", "proxy"]
297+
}
298+
]
299+
}
300+
],
301+
"remotes": [
302+
{
303+
"transport_type": "sse",
304+
"url": "https://hybrid-mcp.example.com/sse",
305+
"headers": [
306+
{
307+
"name": "X-API-Key",
308+
"description": "API key for authentication",
309+
"is_required": true,
310+
"is_secret": true
311+
},
312+
{
313+
"name": "X-Region",
314+
"description": "Service region",
315+
"default": "us-east-1",
316+
"choices": ["us-east-1", "eu-west-1", "ap-southeast-1"]
317+
}
318+
]
319+
},
320+
{
321+
"transport_type": "streamable",
322+
"url": "https://hybrid-mcp.example.com/stream"
323+
}
324+
]
325+
}
326+
```

0 commit comments

Comments
 (0)