Plugin Design Principles

The Five Core Principles

Principle 1: Credential Safety

The credential pattern is mandatory for every plugin that connects to an external service. Raw secrets in appsettings.json — even in environment variables — are a security violation.

// CORRECT — store only the credential ID
{
  "EmailPlugin": {
    "CredentialId": 30      // integer — resolved at runtime
  }
}

// WRONG — never store raw secrets
{
  "EmailPlugin": {
    "SmtpPassword": "hunter2"   // ❌ violates credential pattern
  }
}

// In OnStartAsync — resolve the secret at runtime
public async Task OnStartAsync(IOctopusPluginContext context)
{
    var config  = context.Config.GetSection<EmailPluginConfig>("EmailPlugin");
    var secret  = await context.CredentialResolver
                               .GetPasswordAsync(config.CredentialId);

    _smtpClient = new SmtpClient(config.SmtpHost)
    {
        Credentials = new NetworkCredential(config.SmtpUser, secret)
    };
}

Principle 2: Tenant Isolation

Multi-tenancy is not optional. Every external API call, every database query, and every cache entry must be keyed or filtered by tenant ID.

// Inject ITenantContext into your tool handler
public class CrmToolHandler
{
    private readonly ITenantContext _tenant;
    private readonly ICrmClient     _crm;

    public CrmToolHandler(ITenantContext tenant, ICrmClient crm)
    {
        _tenant = tenant;
        _crm    = crm;
    }

    public async Task<JsonElement> HandleGetContactAsync(JsonElement input)
    {
        var tenantId = _tenant.TenantId;   // read from JWT "tid" claim

        // Scope the query to this tenant's CRM instance
        var contact = await _crm.GetContactAsync(
            tenantId: tenantId,
            email:    input.GetProperty("email").GetString());

        return JsonSerializer.SerializeToElement(contact);
    }
}

Principle 3: MCP Tool Schema Standards

Octopus agents use the JSON Schema defined in inputSchema to decide how to call your tool. A poorly defined schema produces hallucinated or missing arguments at runtime.

// Well-formed MCP tool definition
new MCPTool
{
    Name        = "crm_get_contact",
    Description = "Look up a CRM contact by email address. " +
                  "Returns contact name, account, phone, and open opportunities.",
    InputSchema = JsonDocument.Parse("""
    {
      "type": "object",
      "properties": {
        "email": {
          "type":        "string",
          "format":      "email",
          "description": "The contact's email address (required)"
        },
        "include_opportunities": {
          "type":        "boolean",
          "description": "Include open opportunities in the response",
          "default":     false
        }
      },
      "required": ["email"]
    }
    """)
}

Principle 4: IOctopusPlugin Contract

The plugin lifecycle contract is strict. Violating it causes startup failures, resource leaks, or incorrect DI resolution.

public interface IOctopusPlugin
{
    // Called during DI container setup — register services here only.
    // Do NOT start connections, open sockets, or call external APIs.
    void OnRegister(IServiceCollection services, IOctopusConfig config);

    // Called after DI container is built and host is starting.
    // Resolve connections, start background workers, register MCP tools.
    Task OnStartAsync(IOctopusPluginContext context,
                      CancellationToken cancellationToken);

    // Called during graceful shutdown — release all resources.
    // Must complete within the host's shutdown timeout (default 30 s).
    Task OnStopAsync(CancellationToken cancellationToken);
}

Principle 5: Graceful Degradation

External services fail. Network partitions happen. Rate limits are hit. A plugin that throws an unhandled exception in a tool handler will kill the agent's turn. Return structured errors instead.

public async Task<JsonElement> HandleGetContactAsync(JsonElement input)
{
    try
    {
        var contact = await _crm.GetContactAsync(
            email: input.GetProperty("email").GetString());

        return JsonSerializer.SerializeToElement(new
        {
            success = true,
            contact
        });
    }
    catch (CrmRateLimitException ex)
    {
        _logger.LogWarning(ex, "CRM rate limit hit for tenant {TenantId}",
                           _tenant.TenantId);
        return JsonSerializer.SerializeToElement(new
        {
            success      = false,
            error        = "rate_limit",
            message      = "CRM rate limit reached. Please retry in 60 seconds.",
            retry_after  = 60
        });
    }
    catch (CrmNotFoundException)
    {
        return JsonSerializer.SerializeToElement(new
        {
            success = false,
            error   = "not_found",
            message = $"No contact found for email: {input.GetProperty("email")}"
        });
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Unexpected error in crm_get_contact");
        return JsonSerializer.SerializeToElement(new
        {
            success = false,
            error   = "internal_error",
            message = "An unexpected error occurred. Please try again."
        });
    }
}

Plugin Compliance Checklist