mcporter.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mcpServers": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "description": {
            "description": "Human-readable description of the server",
            "type": "string"
          },
          "baseUrl": {
            "description": "Base URL for HTTP/SSE transport (camelCase)",
            "type": "string"
          },
          "base_url": {
            "description": "Base URL for HTTP/SSE transport (snake_case)",
            "type": "string"
          },
          "url": {
            "description": "Server URL for HTTP/SSE transport",
            "type": "string"
          },
          "serverUrl": {
            "description": "Server URL for HTTP/SSE transport (camelCase)",
            "type": "string"
          },
          "server_url": {
            "description": "Server URL for HTTP/SSE transport (snake_case)",
            "type": "string"
          },
          "command": {
            "description": "Command to spawn for stdio transport (string or array of arguments)",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "executable": {
            "description": "Executable path for stdio transport",
            "type": "string"
          },
          "args": {
            "description": "Arguments to pass to the stdio command",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cwd": {
            "description": "Working directory for stdio servers. A leading ~ is expanded to $HOME; relative paths resolve against the config file directory",
            "type": "string"
          },
          "headers": {
            "description": "HTTP headers for requests. Supports ${VAR}, ${VAR:-fallback}, and $env:VAR placeholders",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "env": {
            "description": "Environment variables for stdio commands. Supports ${VAR} and ${VAR:-fallback} placeholders",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "auth": {
            "description": "Authentication method (e.g., \"oauth\")",
            "type": "string"
          },
          "tokenCacheDir": {
            "description": "Directory for caching OAuth tokens (camelCase)",
            "type": "string"
          },
          "token_cache_dir": {
            "description": "Directory for caching OAuth tokens (snake_case)",
            "type": "string"
          },
          "clientName": {
            "description": "Client identifier for server telemetry (camelCase)",
            "type": "string"
          },
          "client_name": {
            "description": "Client identifier for server telemetry (snake_case)",
            "type": "string"
          },
          "oauthClientId": {
            "description": "Pre-registered OAuth client id (camelCase)",
            "type": "string"
          },
          "oauth_client_id": {
            "description": "Pre-registered OAuth client id (snake_case)",
            "type": "string"
          },
          "oauthClientSecret": {
            "description": "Pre-registered OAuth client secret (camelCase)",
            "type": "string"
          },
          "oauth_client_secret": {
            "description": "Pre-registered OAuth client secret (snake_case)",
            "type": "string"
          },
          "oauthClientSecretEnv": {
            "description": "Environment variable containing the OAuth client secret",
            "type": "string"
          },
          "oauth_client_secret_env": {
            "description": "Environment variable containing the OAuth client secret",
            "type": "string"
          },
          "oauthTokenEndpointAuthMethod": {
            "description": "OAuth token endpoint auth method, e.g. client_secret_post",
            "type": "string"
          },
          "oauth_token_endpoint_auth_method": {
            "description": "OAuth token endpoint auth method, e.g. client_secret_post",
            "type": "string"
          },
          "oauthRedirectUrl": {
            "description": "Custom OAuth redirect URL (camelCase)",
            "type": "string"
          },
          "oauth_redirect_url": {
            "description": "Custom OAuth redirect URL (snake_case)",
            "type": "string"
          },
          "oauthScope": {
            "description": "OAuth scope override (camelCase)",
            "type": "string"
          },
          "oauth_scope": {
            "description": "OAuth scope override (snake_case)",
            "type": "string"
          },
          "oauthCommand": {
            "description": "Custom OAuth command configuration for stdio servers (camelCase)",
            "type": "object",
            "properties": {
              "args": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Arguments for the OAuth command"
              }
            },
            "required": ["args"],
            "additionalProperties": false
          },
          "oauth_command": {
            "description": "Custom OAuth command configuration for stdio servers (snake_case)",
            "type": "object",
            "properties": {
              "args": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Arguments for the OAuth command"
              }
            },
            "required": ["args"],
            "additionalProperties": false
          },
          "bearerToken": {
            "description": "Static bearer token for authentication (camelCase)",
            "type": "string"
          },
          "bearer_token": {
            "description": "Static bearer token for authentication (snake_case)",
            "type": "string"
          },
          "bearerTokenEnv": {
            "description": "Environment variable name containing the bearer token (camelCase)",
            "type": "string"
          },
          "bearer_token_env": {
            "description": "Environment variable name containing the bearer token (snake_case)",
            "type": "string"
          },
          "refresh": {
            "type": "object",
            "properties": {
              "tokenEndpoint": {
                "description": "OAuth token endpoint used to refresh access tokens",
                "type": "string"
              },
              "token_endpoint": {
                "description": "OAuth token endpoint used to refresh access tokens",
                "type": "string"
              },
              "clientIdEnv": {
                "description": "Environment variable containing the OAuth client id",
                "type": "string"
              },
              "client_id_env": {
                "description": "Environment variable containing the OAuth client id",
                "type": "string"
              },
              "clientSecretEnv": {
                "description": "Environment variable containing the OAuth client secret",
                "type": "string"
              },
              "client_secret_env": {
                "description": "Environment variable containing the OAuth client secret",
                "type": "string"
              },
              "clientAuthMethod": {
                "description": "OAuth token endpoint client auth method",
                "type": "string"
              },
              "client_auth_method": {
                "description": "OAuth token endpoint client auth method",
                "type": "string"
              },
              "refreshSkewSeconds": {
                "description": "Refresh before expiry by this many seconds",
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "refresh_skew_seconds": {
                "description": "Refresh before expiry by this many seconds",
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "accessTokenEnv": {
                "description": "STDIO env var that receives the refreshed access token",
                "type": "string"
              },
              "access_token_env": {
                "description": "STDIO env var that receives the refreshed access token",
                "type": "string"
              }
            },
            "additionalProperties": false,
            "description": "Refreshable bearer token settings"
          },
          "httpFetch": {
            "description": "HTTP fetch implementation for Streamable HTTP/SSE requests",
            "type": "string",
            "enum": ["default", "node-http1"]
          },
          "http_fetch": {
            "description": "HTTP fetch implementation for Streamable HTTP/SSE requests",
            "type": "string",
            "enum": ["default", "node-http1"]
          },
          "lifecycle": {
            "anyOf": [
              {
                "type": "string",
                "const": "keep-alive",
                "description": "Keep the server connection alive"
              },
              {
                "type": "string",
                "const": "ephemeral",
                "description": "Connect only when needed"
              },
              {
                "type": "object",
                "properties": {
                  "mode": {
                    "anyOf": [
                      {
                        "type": "string",
                        "const": "keep-alive"
                      },
                      {
                        "type": "string",
                        "const": "ephemeral"
                      }
                    ],
                    "description": "Connection lifecycle mode"
                  },
                  "idleTimeoutMs": {
                    "description": "Idle timeout in milliseconds before disconnecting",
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "required": ["mode"],
                "additionalProperties": false
              }
            ],
            "description": "Server connection lifecycle: keep-alive maintains persistent connections, ephemeral connects on-demand"
          },
          "logging": {
            "description": "Logging configuration for the server",
            "type": "object",
            "properties": {
              "daemon": {
                "description": "Daemon-specific logging configuration",
                "type": "object",
                "properties": {
                  "enabled": {
                    "description": "Enable daemon logging for this server",
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "allowedTools": {
            "description": "Only these exact tool names are exposed (camelCase)",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "allowed_tools": {
            "description": "Only these exact tool names are exposed (snake_case)",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "blockedTools": {
            "description": "These exact tool names are hidden and blocked (camelCase)",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "blocked_tools": {
            "description": "These exact tool names are hidden and blocked (snake_case)",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false,
        "description": "MCP server definition supporting both HTTP/SSE and stdio transports"
      },
      "description": "Map of server names to their configurations"
    },
    "daemonIdleTimeoutMs": {
      "description": "Idle timeout in milliseconds before shutting down an inactive daemon",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "daemon_idle_timeout_ms": {
      "description": "Idle timeout in milliseconds before shutting down an inactive daemon",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "imports": {
      "description": "Editor configurations to import servers from. Omit to use defaults, or set to [] to disable imports",
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"],
        "description": "Supported editor/client configurations to import MCP servers from"
      }
    },
    "$schema": {
      "type": "string",
      "description": "JSON Schema URL for IDE validation and autocomplete"
    }
  },
  "required": ["mcpServers"],
  "additionalProperties": false,
  "description": "mcporter configuration file schema",
  "$id": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json"
}