mcpgen.json reference

mcpgen.json (config format version 1) is the single source of truth of a generated project. This page is generated from internal/config/schema.json, the JSON Schema (draft 2020-12) that mcpgen check validates against and that mcpgen schema embeds.

Top-level required fields: version, server, transport. Unknown fields are rejected (additionalProperties: false).

Complete example

{
  "version": 1,
  "server": {
    "name": "weather",
    "title": "weather",
    "version": "0.1.0",
    "module": "example.com/weather",
    "description": "Generated MCP server.",
    "instructions": "Generated MCP server."
  },
  "transport": {
    "type": "http",
    "httpPort": 8080
  },
  "protocol": "compat",
  "tools": [
    {
      "id": "greet",
      "title": "Greet",
      "description": "Greets a user with a short welcome.",
      "inputSchema": {
        "type": "object"
      },
      "outputSchema": {
        "type": "object"
      },
      "readOnly": true
    }
  ],
  "prompts": [
    {
      "id": "welcome",
      "title": "Welcome",
      "description": "A friendly welcome prompt."
    }
  ],
  "resources": [
    {
      "id": "readme",
      "title": "Readme",
      "description": "A readme stub resource.",
      "uri": "file:///readme",
      "mimeType": "text/plain",
      "text": "Welcome to your MCP server."
    }
  ]
}

Fields

Field	Type	Required	Constraints	Default	Description
features	object			—
prompts	array			—
protocol	string		one of compat, latest-only	compat	compat negotiates down to legacy MCP versions; latest-only serves only 2026-07-28
resources	array			—
server	object	yes		—
tools	array			—
transport	object	yes		—
version	integer	yes	must be 1	—	Config format version. mcpgen v1 supports only 1.

features

Field	Type	Required	Constraints	Default	Description
features.oauth	boolean			—
features.skills	boolean			—
features.tasks	boolean			—

prompts[]

Field	Type	Required	Constraints	Default	Description
prompts[].arguments	array			—
prompts[].description	string			—
prompts[].id	string	yes	pattern ^[a-zA-Z0-9_-]+$; min length 1	—
prompts[].title	string			—

prompts[].arguments[]

Field	Type	Required	Constraints	Default	Description
prompts[].arguments[].description	string			—
prompts[].arguments[].name	string	yes	min length 1	—
prompts[].arguments[].required	boolean			—
prompts[].arguments[].title	string			—

resources[]

Field	Type	Required	Constraints	Default	Description
resources[].description	string			—
resources[].id	string	yes	pattern ^[a-zA-Z0-9_-]+$; min length 1	—
resources[].mimeType	string			—
resources[].text	string			—	Stub content served by the generated handler
resources[].title	string			—
resources[].uri	string			—	Absolute URI. Exactly one of uri/uriTemplate.
resources[].uriTemplate	string			—	RFC 6570 URI template. Exactly one of uri/uriTemplate.

server

Field	Type	Required	Constraints	Default	Description
server.description	string			—
server.instructions	string			—	Instructions sent to MCP clients
server.module	string		min length 1	—	Go module path
server.name	string	yes	min length 1	—
server.title	string			—
server.version	string			—	SemVer of the server, e.g. 0.1.0

tools[]

Field	Type	Required	Constraints	Default	Description
tools[].description	string			—
tools[].id	string	yes	pattern ^[a-zA-Z0-9_-]+$; min length 1	—
tools[].idempotent	boolean			—	Maps to the tool idempotentHint annotation
tools[].inputSchema	object			—	JSON Schema (draft 2020-12 object) for tool input
tools[].outputSchema	object			—	JSON Schema (draft 2020-12 object) for structured output
tools[].readOnly	boolean			—	Maps to the tool readOnlyHint annotation
tools[].title	string			—

transport

Field	Type	Required	Constraints	Default	Description
transport.httpPort	integer		min 1; max 65535	—
transport.type	string	yes	one of stdio, http	—

Id rules

Tool, prompt, and resource id values must match ^[a-zA-Z0-9_-]+$ (letters, digits, underscore, hyphen). Ids become file names and MCP names, so the pattern is enforced before any file is written. Duplicate ids within one kind are rejected.

Schemas inside the config

tools[].inputSchema and tools[].outputSchema hold raw JSON Schema documents (draft 2020-12 objects), embedded verbatim into the generated Go code as json.RawMessage backtick literals and used by the go-sdk to generate the typed Input/Output structs of each handler.

Full JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/alesr/mcpgen/schema/mcpgen.schema.json",
  "title": "mcpgen project config (mcpgen.json)",
  "description": "Single source of truth for an mcpgen-generated MCP server project. Version 1.",
  "type": "object",
  "required": ["version", "server", "transport"],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "integer",
      "const": 1,
      "description": "Config format version. mcpgen v1 supports only 1."
    },
    "server": {
      "type": "object",
      "required": ["name"],
      "additionalProperties": false,
      "properties": {
        "name": { "type": "string", "minLength": 1 },
        "title": { "type": "string" },
        "version": { "type": "string", "description": "SemVer of the server, e.g. 0.1.0" },
        "module": { "type": "string", "minLength": 1, "description": "Go module path" },
        "description": { "type": "string" },
        "instructions": { "type": "string", "description": "Instructions sent to MCP clients" }
      }
    },
    "transport": {
      "type": "object",
      "required": ["type"],
      "additionalProperties": false,
      "properties": {
        "type": { "type": "string", "enum": ["stdio", "http"] },
        "httpPort": { "type": "integer", "minimum": 1, "maximum": 65535 }
      }
    },
    "protocol": {
      "type": "string",
      "enum": ["compat", "latest-only"],
      "default": "compat",
      "description": "compat negotiates down to legacy MCP versions; latest-only serves only 2026-07-28"
    },
    "tools": {
      "type": "array",
      "items": { "$ref": "#/definitions/tool" }
    },
    "prompts": {
      "type": "array",
      "items": { "$ref": "#/definitions/prompt" }
    },
    "resources": {
      "type": "array",
      "items": { "$ref": "#/definitions/resource" }
    },
    "features": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "tasks": { "type": "boolean" },
        "skills": { "type": "boolean" },
        "oauth": { "type": "boolean" }
      }
    }
  },
  "definitions": {
    "tool": {
      "type": "object",
      "required": ["id"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "inputSchema": { "type": "object", "description": "JSON Schema (draft 2020-12 object) for tool input" },
        "outputSchema": { "type": "object", "description": "JSON Schema (draft 2020-12 object) for structured output" },
        "readOnly": { "type": "boolean", "description": "Maps to the tool readOnlyHint annotation" },
        "idempotent": { "type": "boolean", "description": "Maps to the tool idempotentHint annotation" }
      }
    },
    "prompt": {
      "type": "object",
      "required": ["id"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "arguments": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["name"],
            "additionalProperties": false,
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "title": { "type": "string" },
              "description": { "type": "string" },
              "required": { "type": "boolean" }
            }
          }
        }
      }
    },
    "resource": {
      "type": "object",
      "required": ["id"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "uri": { "type": "string", "description": "Absolute URI. Exactly one of uri/uriTemplate." },
        "uriTemplate": { "type": "string", "description": "RFC 6570 URI template. Exactly one of uri/uriTemplate." },
        "mimeType": { "type": "string" },
        "text": { "type": "string", "description": "Stub content served by the generated handler" }
      }
    }
  }
}