MCP servers

Add mcp.json next to plugin.json when your plugin needs runtime tools or resources from an MCP server.

Reforma supports the Agent Plugins MCP format for remote and stdio servers.

If the agent only needs instructions or a workflow, use a skill instead.

Authentication on this page connects the Reforma project to an MCP server so the builder agent can use it. It is unrelated to authentication for users of the app being built.

To connect Claude, Cursor, or Codex to Reforma itself, see MCP server.

Remote MCP

A Streamable HTTP server uses type: streamable-http and an absolute URL:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "google-drive": {
      "type": "streamable-http",
      "url": "https://drivemcp.googleapis.com/mcp/v1"
    }
  }
}

For a plugin with one MCP server, use the plugin name as the server key.

Imported vendor plugins may use another key; the Reforma catalog packer normalizes a lone server key to the plugin name.

Stdio MCP

Local MCP servers use type: stdio:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "./bin/server",
      "args": ["--config", "${PLUGIN_ROOT}/config.json"]
    }
  }
}

Agent Plugins defines ${PLUGIN_ROOT} and ${PLUGIN_DATA} for stdio args, env, and cwd.

Authentication

Agent Plugins does not define portable OAuth or credential-reference fields. Authentication is handled by the client.

Reforma supports three common cases.

Public server

If the server needs no authentication, do not declare any variables:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "example": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Enabling the plugin is enough to connect.

API key

Declare configurable values in extensions.reforma.variables in plugin.json:

{
  "name": "example",
  "description": "Connects the builder agent to Example.",
  "extensions": {
    "reforma": {
      "variables": {
        "type": "object",
        "properties": {
          "API_KEY": {
            "type": "string",
            "title": "API key"
          }
        },
        "required": ["API_KEY"]
      }
    }
  }
}

Reforma treats string variables as vault secrets by default. Set "secret": false for a non-secret string. Boolean and enum settings are not secrets.

Reference a variable from the MCP configuration:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "example": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${API_KEY} substitution is a Reforma extension. Portable Agent Plugins clients treat HTTP headers as literal configuration and are not required to resolve Reforma variables.

Required variables must be configured before Reforma connects the integration.

Resolved variables are also exposed to plugin hooks as environment variables using the property name. OAuth tokens are not exposed to hooks.

OAuth

Do not declare OAuth credentials or OAuth configuration in plugin.json.

Reforma first connects to the MCP server normally. If the server responds with 401, or with 403 and an insufficient_scope challenge, the integration surfaces Log in.

After authentication, Reforma stores the OAuth tokens in the project vault and sends the access token as:

Authorization: Bearer <token>

When an authenticated connection is active, the integration surfaces Log out.

Because authentication is client-managed, the same mcp.json can describe an OAuth-protected remote server without embedding credentials in the plugin.

Catalog discovery

When packing a catalog plugin, Reforma may connect to a reachable HTTP MCP server and cache tool, resource, and resource-template metadata for the integration UI.

This discovery metadata is generated by Reforma; it is not part of the portable Agent Plugins mcp.json authoring format.

Servers that require authentication may not be discoverable during packing. Stdio servers are not probed.

Custom MCP

Project owners can also add a remote MCP server directly in project settings instead of installing a catalog plugin.

A custom MCP can use no authentication, a bearer token, or OAuth. It is project configuration and is not a marketplace plugin.

On this page