mctx.json Reference

The mctx.json file configures your MCP server for deployment on mctx. It follows the official MCP server manifest specification with an additional entrypoint field.

File Location

Place mctx.json in your repository root or in a subdirectory for monorepos.

Single-package repository:

my-mcp-server/
├── src/
├── dist/
├── mctx.json          # Root level
└── package.json

Monorepo:

my-monorepo/
├── packages/
│   └── my-mcp-server/
│       ├── mctx.json  # Package level
│       ├── src/
│       └── dist/
└── package.json

When deploying from a monorepo, specify the package path in the deployment form (e.g., packages/my-mcp-server).

Schema Reference

Required Fields

Optional Fields

Version Field

Format: Semantic versioning (MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD])

Examples:

• 1.0.0 - Production release
• 1.1.0 - New feature, backward compatible
• 1.0.1 - Bug fix
• 2.0.0 - Breaking changes
• 1.0.0-beta.1 - Pre-release version
• 1.0.0-rc.1+20130313144700 - Release candidate with build metadata

Validation:

• Must be a valid semver string
• Must be unique per deployment (cannot redeploy same version)
• Case-sensitive

Version Detection:

mctx detects new versions by comparing the version field in mctx.json against deployed versions. Changes to your code without a version bump will not trigger deployment.

Description Field

Purpose: Displayed on server info pages and in the MCP Community Registry.

Best Practices:

• Start with a verb ("Get", "Search", "Query", "Generate")
• Be specific about what makes your server unique
• Keep under 200 characters for optimal display
• Avoid marketing language

Good Examples:

• "Query financial data from SEC filings with natural language"
• "Get real-time weather forecasts for any location worldwide"
• "Search documentation across 50+ programming languages"

Bad Examples:

• "A server that does things with data" (too vague)
• "The best, most amazing tool ever created!" (marketing fluff)
• "Server for stuff" (not descriptive)

Entrypoint Field

Path: Relative to the location of mctx.json.

Requirements:

• Must be a .js or .mjs file
• Must exist in the repository (committed or CI-generated)
• Must export a default handler compatible with Cloudflare Workers

Common Patterns:

Handler Format:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Handle MCP JSON-RPC requests
  },
};

Name Field

Optional. Suggested display name shown in the dashboard when you first deploy. You can override this in the server settings.

If omitted, mctx derives a name from your repository name.

Instructions Field

Optional. Provides context to AI models about how to use your server effectively.

Purpose:

• Explain tool purposes briefly
• Mention expected input formats
• Note limitations or special behavior

Maximum Length: 2000 characters

Example:

{
  "instructions": "Use 'search_docs' to find documentation pages. Use 'get_page' with a URL to retrieve specific content. Results are markdown-formatted. The search is case-insensitive and supports partial matches."
}

Capabilities Field

Optional. Declares which MCP protocol features your server supports.

Important: This is protocol-level capability negotiation only. It does NOT define your tools, resources, or prompts. Those are discovered via tools/list, resources/list, and prompts/list handlers in your code.

Capability Schema

{
  "capabilities": {
    "tools": {
      "listChanged": boolean
    },
    "resources": {
      "subscribe": boolean,
      "listChanged": boolean
    },
    "prompts": {
      "listChanged": boolean
    }
  }
}

Capability Flags

Default Capabilities

If capabilities is omitted, defaults to:

{
  "capabilities": {
    "tools": {}
  }
}

Common Configurations

Tools-only server:

{
  "capabilities": {
    "tools": {}
  }
}

Static resources:

{
  "capabilities": {
    "resources": {}
  }
}

Dynamic resources with subscriptions:

{
  "capabilities": {
    "resources": {
      "subscribe": true,
      "listChanged": true
    }
  }
}

Minimal Example

{
  "version": "1.0.0",
  "description": "Get real-time weather data for any location",
  "entrypoint": "dist/index.js"
}

Full Example

{
  "name": "Weather API",
  "version": "1.0.0",
  "description": "Get real-time weather data for any location worldwide using OpenWeatherMap",
  "entrypoint": "dist/index.js",
  "instructions": "Use 'get_weather' for current conditions. Use 'get_forecast' for 5-day predictions. Provide city name or coordinates. All temperatures are in Celsius.",
  "capabilities": {
    "tools": {
      "listChanged": false
    }
  }
}

Validation Rules

mctx validates mctx.json when you:

1. Select a repository in the deployment form
2. Push changes to your branch (webhook triggers validation)

Common Validation Errors

Platform-Managed Initialization

mctx intercepts MCP initialize requests and responds using your mctx.json configuration. Your server code does NOT need to handle initialize.

Initialize Response Fields:

• serverInfo.name - From dashboard server name (not mctx.json name)
• serverInfo.version - From mctx.json version field
• capabilities - From mctx.json capabilities field
• instructions - From mctx.json instructions field

What You Implement:

Your server only handles business logic:

• tools/list
• tools/call
• resources/list (if applicable)
• resources/read (if applicable)
• prompts/list (if applicable)
• prompts/get (if applicable)

See Also

• Environment Variables - Secrets and configuration
• Versioning - How versions work
• Server Requirements - Server code structure

See something wrong? Report it or suggest an improvement — your feedback helps make these docs better.