jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/infra/factory-tools/mcp-validator/specification/specification-2025-06-18.md
Jake Shore f3c4cd817b Add all MCP servers + factory infra to MCPEngine — 2026-02-06 
=== NEW SERVERS ADDED (7) ===
- servers/closebot — 119 tools, 14 modules, 4,656 lines TS (Stage 7)
- servers/google-console — Google Search Console MCP (Stage 7)
- servers/meta-ads — Meta/Facebook Ads MCP (Stage 8)
- servers/twilio — Twilio communications MCP (Stage 8)
- servers/competitor-research — Competitive intel MCP (Stage 6)
- servers/n8n-apps — n8n workflow MCP apps (Stage 6)
- servers/reonomy — Commercial real estate MCP (Stage 1)

=== FACTORY INFRASTRUCTURE ADDED ===
- infra/factory-tools — mcp-jest, mcp-validator, mcp-add, MCP Inspector
  - 60 test configs, 702 auto-generated test cases
  - All 30 servers score 100/100 protocol compliance
- infra/command-center — Pipeline state, operator playbook, dashboard config
- infra/factory-reviews — Automated eval reports

=== DOCS ADDED ===
- docs/MCP-FACTORY.md — Factory overview
- docs/reports/ — 5 pipeline evaluation reports
- docs/research/ — Browser MCP research

=== RULES ESTABLISHED ===
- CONTRIBUTING.md — All MCP work MUST go in this repo
- README.md — Full inventory of 37 servers + infra docs
- .gitignore — Updated for Python venvs

TOTAL: 37 MCP servers + full factory pipeline in one repo.
This is now the single source of truth for all MCP work.
2026-02-06 06:32:29 -05:00

279 lines
13 KiB
Markdown
Raw Blame History

# Model Context Protocol Specification - 2025-06-18
## Overview
[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
This specification defines the authoritative protocol requirements, based on the TypeScript schema in [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-06-18/schema.ts).
For implementation guides and examples, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] [[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only when, they appear in all capitals, as shown here.
## Key Changes from 2025-03-26
### Major Changes
1. **Remove support for JSON-RPC batching** (PR [#416](https://github.com/modelcontextprotocol/specification/pull/416))
2. **Add support for structured tool output** (PR [#371](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/371))
3. **Classify MCP servers as OAuth Resource Servers**, adding protected resource metadata to discover the corresponding Authorization server (PR [#338](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/338))
4. **Require MCP clients to implement Resource Indicators** as described in [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) to prevent malicious servers from obtaining access tokens (PR [#734](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/734))
5. **Clarify security considerations** and best practices in the authorization spec and in a new security best practices page
6. **Add support for elicitation**, enabling servers to request additional information from users during interactions (PR [#382](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/382))
7. **Add support for resource links** in tool call results (PR [#603](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/603))
8. **Require negotiated protocol version to be specified** via `MCP-Protocol-Version` header in subsequent requests when using HTTP (PR [#548](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/548))
9. **Change SHOULD to MUST** in Lifecycle Operation
### Other Schema Changes
1. **Add `_meta` field** to additional interface types (PR [#710](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/710))
2. **Add `context` field** to `CompletionRequest`, providing for completion requests to include previously-resolved variables (PR [#598](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/598))
3. **Add `title` field** for human-friendly display names, so that `name` can be used as a programmatic identifier (PR [#663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/663))
## Base Protocol
### JSON-RPC Messages
All messages between MCP clients and servers **MUST** follow the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification.
#### Requests
- Requests **MUST** include a string or integer ID (not null)
- Request IDs **MUST** be unique within a session
- Requests **MUST** include a method string
- JSON-RPC batching is **NOT** supported in this version
#### Responses
- Responses **MUST** include the same ID as the corresponding request
- Responses **MUST** include either a result or an error (not both)
- Error responses **MUST** include an error code and message
#### Notifications
- Notifications **MUST NOT** include an ID
- Notifications **MUST** include a method string
### Transport
#### STDIO Transport
- Client **MUST** launch server as subprocess
- Server **MUST** read from stdin and write to stdout
- Messages **MUST** be delimited by newlines
- Messages **MUST NOT** contain embedded newlines
- Server **MUST NOT** write anything to stdout that is not a valid MCP message
- Client **MUST NOT** write anything to stdin that is not a valid MCP message
#### Streamable HTTP Transport
- Server **MUST** provide a single HTTP endpoint supporting both POST and GET methods
- Client messages **MUST** be sent as HTTP POST requests
- Server **MAY** use Server-Sent Events (SSE) for streaming responses
- Client **MUST** include `MCP-Protocol-Version` header on all subsequent requests
- Server **MUST** validate `Origin` header to prevent DNS rebinding attacks
- When running locally, servers **SHOULD** bind only to localhost
### Lifecycle
#### Initialization
- Client **MUST** send initialize request as first interaction
- Initialize request **MUST** include protocol version supported
- Initialize request **MUST** include client capabilities
- Initialize request **MUST** include client implementation information
- Server **MUST** respond with protocol version
- Server **MUST** respond with server capabilities
- Server **MUST** respond with server implementation information
- After successful initialization, client **MUST** send initialized notification
#### Version Negotiation
- Client **MUST** send a protocol version it supports
- If server supports requested version, it **MUST** respond with same version
- Otherwise, server **MUST** respond with another supported version
- If client doesn't support server's version, it **SHOULD** disconnect
#### Capability Negotiation
- Client and server **MUST** declare capabilities during initialization
- Both parties **SHOULD** respect negotiated capabilities
#### Shutdown
- For STDIO: client **SHOULD** close input stream to server for shutdown
- For HTTP: shutdown indicated by closing HTTP connections
### Authorization (HTTP Only)
#### OAuth 2.1 Compliance
- MCP servers **MUST** act as OAuth 2.1 resource servers
- MCP clients **MUST** implement Resource Indicators (RFC 8707)
- Authorization servers **MUST** implement OAuth 2.1 with appropriate security measures
- Authorization servers **SHOULD** support Dynamic Client Registration (RFC 7591)
#### Protected Resource Metadata
- MCP servers **MUST** implement OAuth 2.0 Protected Resource Metadata (RFC 9728)
- Servers **MUST** use `WWW-Authenticate` header when returning 401 Unauthorized
- Clients **MUST** parse `WWW-Authenticate` headers and respond to 401 responses
#### Access Token Usage
- Clients **MUST** use Authorization header with Bearer token
- Access tokens **MUST NOT** be included in URI query strings
- Servers **MUST** validate access tokens were issued specifically for them
- Servers **MUST NOT** accept tokens intended for other resources
### Security Considerations
#### General Security
- Users **MUST** explicitly consent to data access and operations
- Users **MUST** retain control over data sharing and actions
- Hosts **MUST** obtain explicit user consent before exposing user data
- Tools require explicit user consent before invocation
#### Token Security
- Servers **MUST** validate token audience to prevent confused deputy attacks
- Token passthrough is explicitly forbidden
- Clients **MUST** include resource parameter in authorization requests
- Authorization servers **SHOULD** issue short-lived access tokens
#### Session Security
- Session IDs **MUST** be secure and non-deterministic
- Servers **SHOULD** bind session IDs to user-specific information
- Servers **MUST** verify all inbound requests when authorization is implemented
## Server Features
### Resources
#### Capabilities
- Servers supporting resources **MUST** declare resources capability
- Resources capability **MAY** include subscribe feature
- Resources capability **MAY** include listChanged feature
#### Listing Resources
- Server response to resources/list **MUST** include resources array
- Each resource **MUST** include uri and name
- Each resource **SHOULD** include title for display purposes
#### Reading Resources
- Server response to resources/read **MUST** include contents array
- Each content item **MUST** include uri and either text or blob
- Each content item **SHOULD** include mimeType
#### Resource Templates
- Server response to resources/templates/list **MUST** include resourceTemplates array
- Each template **MUST** include uriTemplate
#### Notifications
- Server **MUST** send notifications/resources/updated when resource changes
- Server **MUST** support subscribe capability to use subscription feature
- Server **SHOULD** send notifications/resources/list_changed when resource list changes
- Server **MUST** support listChanged capability to use list_changed notification
### Prompts
#### Capabilities
- Servers supporting prompts **MUST** declare prompts capability
- Prompts capability **MAY** include listChanged feature
#### Listing Prompts
- Server response to prompts/list **MUST** include prompts array
- Each prompt **MUST** include name
- Each prompt **SHOULD** include title for display purposes
#### Getting Prompts
- Server response to prompts/get **MUST** include messages array
- Each message **MUST** include role and content
- Content **MUST** be one of: text, image, audio, or resource
#### Notifications
- Server **SHOULD** send notifications/prompts/list_changed when prompt list changes
- Server **MUST** support listChanged capability to use list_changed notification
### Tools
#### Capabilities
- Servers supporting tools **MUST** declare tools capability
- Tools capability **MAY** include listChanged feature
#### Listing Tools
- Server response to tools/list **MUST** include tools array
- Each tool **MUST** include name, description, and inputSchema
- Each tool **SHOULD** include title for display purposes
- Each tool **MAY** include outputSchema for structured results
#### Calling Tools
- Server response to tools/call **MUST** include content array and isError flag
- Each content item **MUST** be one of: text, image, audio, resource, or resource_link
- Tools **MAY** return structured content in structuredContent field
- If outputSchema provided, structured results **MUST** conform to schema
#### Notifications
- Server **SHOULD** send notifications/tools/list_changed when tool list changes
- Server **MUST** support listChanged capability to use list_changed notification
## Client Features
### Roots
#### Capabilities
- Clients supporting roots **MUST** declare roots capability
- Roots capability **MAY** include listChanged feature
#### Listing Roots
- Client response to roots/list **MUST** include roots array
- Each root **MUST** include uri
- Each root **SHOULD** include name for display purposes
#### Notifications
- Client **MUST** send notifications/roots/list_changed when root list changes
- Client **MUST** support listChanged capability to use list_changed notification
### Sampling
#### Capabilities
- Clients supporting sampling **MUST** declare sampling capability
#### Creating Messages
- Client response to sampling/createMessage **MUST** include role, content, model, and stopReason
- Content **MUST** be one of: text, image, or audio
- Clients **SHOULD** implement human-in-the-loop approval for sampling requests
### Elicitation
#### Capabilities
- Clients supporting elicitation **MUST** declare elicitation capability
#### Creating Elicitation Requests
- Client response to elicitation/create **MUST** include action and optionally content
- Action **MUST** be one of: accept, reject, or cancel
- Schema **MUST** be restricted to flat objects with primitive properties
- Clients **SHOULD** provide clear UI for elicitation requests
## Utilities
### Ping
- Ping receiver **MUST** respond promptly with empty response
### Cancellation
- Cancellation notification **MUST** include requestId of request to cancel
- Cancellation notifications **MUST** only reference previously issued requests
- Initialize request **MUST NOT** be cancelled by clients
- Receivers **SHOULD** stop processing cancelled request
### Progress
- Progress tokens **MUST** be unique across active requests
- Progress notifications **MUST** include progressToken and progress value
- Progress value **MUST** increase with each notification
- Progress notifications **MUST** only reference active requests
### Logging
- Servers supporting logging **MUST** declare logging capability
- Log messages **MUST** follow standard syslog severity levels
- Log messages **MUST NOT** contain sensitive information
### Completion
- Server response to completion/complete **MUST** include completion values
- Completion response limited to maximum 100 items per response
- Completion requests **MAY** include context with previously-resolved arguments
### Pagination
- Clients **MUST** treat cursors as opaque tokens
- Servers **SHOULD** provide stable cursors
- Missing nextCursor indicates end of results
## Meta Fields
The `_meta` property is reserved by MCP for protocol-level metadata. Key names have two segments: an optional prefix and a name. Prefixes beginning with `modelcontextprotocol` or `mcp` are reserved for MCP use.
Reference in New Issue View Git Blame Copy Permalink