MCP Local Spec

🚀 Specification for Local MCP Servers

This specification aims to provide a standard way to list and configure MCP servers on local machines.

Version

1.0.1

🎯 Goals

This specification aims to allow the listing and configuration of MCP servers on local machines in a standardized way.

Many tools already use MCP servers to enhance LLM capabilities. Currently, there is no standard method to quickly register MCP servers.

Here are some popular MCP clients:

• IntelliJ IDEA
• Anthropic Claude
• OpenAI ChatGPT
• Cursor
• Windsurf
• Warp
• Submit a PR to add yours

🛠️ Supported Tools

• Submit a PR if your tool supports this specification

📋 Specification

Create a file for each MCP server in the ~/.mcp folder (%USER_HOME% on Windows).

This file is a Markdown file that explains the details of your MCP server to an LLM (such as Claude or ChatGPT). The client needs to convert the LLM's interpretation into an actionable MCP server.

The client must periodically refresh the information from the disk to discover new MCP servers.

This protocol does not address any security issues related to MCP servers. It remains the responsibility of the MCP client.

For example:

~/.mcp/my-mcp-server-tool-id.md

Create the following text in the file:

---
version: 1.0.1
---

# MCP Server: Production Environment

Here, I describe what my MCP server is doing and why the LLM would decide to include my server in a specific request.

## Basic Information
- **Name**: Production Jonnyzzz MCP Server
- **ID**: prod-mcp-01
- **Version**: 3.2.1
- **URL**: https://mcp-prod.jonnyzzz.com:8443
- **API Version**: v2

## Authentication
- **Type**: oauth2
- **Client ID**: client_123
- **Token Endpoint**: https://auth.example.com/token

## Features
- compute
- storage
- networking

## Regions
### us-east
- us-east-1a
- us-east-1b

### eu-west
- eu-west-1a
- eu-west-1b

## Health Check
- **Endpoint**: /health
- **Interval**: 60 seconds

## Metadata
- **Environment**: Production
- **Owner**: platform-team
- **Priority**: High

💻 How to Use This Specification?

MCP clients use an LLM (such as Claude or ChatGPT) to extract the necessary information from the Markdown files of all available MCP servers in the ~/.mcp folder. Whether to use a specific LLM, request credentials, etc., is determined by the LLM and the client. The client should periodically refresh the files from the disk.