MCP Server

WildwoodAPI hosts a Model Context Protocol (MCP) server at /mcp that allows AI agents like Claude Code to query and manage app configurations directly through a standardized protocol.

Overview

The MCP server uses Streamable HTTP transport (Server-Sent Events) and provides 46 tools across 15 tool classes. AI agents connect via OAuth 2.1 with PKCE — on first connection, a browser window opens for the user to log in at WildwoodAdmin. After authentication, all MCP tool calls are scoped to the user's company and app context.

Prerequisites

Before MCP tools work, three conditions must be met:

Authentication: OAuth 2.1

The MCP server uses OAuth 2.1 with Authorization Code + PKCE flow:

1. AI agent sends first request to /mcp without a token → receives 401
2. Agent discovers auth endpoints via /.well-known/oauth-protected-resource
3. Agent opens a browser window for the user to log in at WildwoodAdmin
4. User authenticates with Wildwood credentials (email/password or social providers)
5. OAuth flow completes → agent receives access token + refresh token
6. Token is sent as Authorization: Bearer <token> on every subsequent request
7. Token refresh happens automatically

OAuth Endpoints

Feature Gating

The MCP endpoint is protected by three independent gates:

Gate 1: App-Level Toggle

The CompanyApp.IsMCPEnabled boolean flag must be true. This is a per-app toggle — when false, all MCP requests for that app return 403. No role can bypass this gate, not even Admin.

Gate 2: Tier Feature Check

The MCP_SERVERS feature code must be available via the company's tier subscription or add-on. The Admin role bypasses this check (consistent with other tier-gated endpoints). When denied, the response includes upgrade information:

{
  "error": "Feature not available on your current plan",
  "featureCode": "MCP_SERVERS",
  "currentTier": "Starter",
  "requiredTier": "Business",
  "upgradeMessage": "Upgrade to Business to access MCP Servers",
  "availableAsAddOn": true,
  "addOnName": "MCP Servers"
}

Gate 3: Per-Tool Enable/Disable

Individual MCP tools can be enabled or disabled by platform admins via WildwoodAdmin > Settings > MCP Servers. When a tool is disabled, any tools/call request targeting that tool returns a JSON-RPC error:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Tool 'wildwood_manage_ai_config' is currently disabled by the platform administrator."
  },
  "id": 1
}

All tools are enabled by default. The tool registry is automatically synced on API startup — new tools are registered and removed tools are cleaned up. Admin actions include:

• Toggle individual tools — Enable or disable a single tool
• Bulk toggle by category — Enable/disable all Read or all Write tools at once
• Enable/Disable All — Toggle every tool in one action

Tool call logs are available in the admin dashboard showing tool name, success/failure, response time, and caller information.

MCP Tools Reference

46 tools across 15 tool classes. All tools require CompanyAdmin authentication. Write tools require confirm: true and automatically snapshot the current configuration before making changes.

Read Tools (20)

Write Tools (26)

All write tools require confirm: true parameter and auto-snapshot before changes.

Configuration Workflows

Use MCP tools to configure your app's backend — equivalent to clicking through WildwoodAdmin but automated through your AI agent.

Enable MCP for an App

wildwood_update_app_config(isMCPEnabled: true, confirm: true)

Set Up AI Chat

// 1. Find a system AI provider (e.g., OpenAI, Anthropic)
wildwood_list_system_providers()
// Returns: providers[] with { id, name, providerCode }

// 2. Create a company AI provider with your API key
wildwood_manage_ai_provider(
  name: "OpenAI",
  systemAIProviderId: "<id-from-step-1>",
  apiKey: "sk-...",
  isEnabled: true,
  confirm: true
)
// API key is encrypted at rest; response shows hasApiKey: true

// 3. Create AI configuration linked to the provider
wildwood_manage_ai_config(
  name: "Customer Support",
  configurationType: "chat",
  model: "gpt-4o",
  providerTypeCode: "openai",
  companyAIProviderId: "<id-from-step-2>",
  isActive: true,
  isChatEnabled: true,
  maxTokensPerRequest: 4096,
  temperature: 0.7,
  welcomeMessage: "Hello! How can I help?",
  confirm: true
)

Set Up Authentication

// 1. Configure auth settings
wildwood_manage_auth_config(
  isEnabled: true,
  allowLocalAuth: true,
  allowPasswordReset: true,
  requireEmailVerification: true,
  allowOpenRegistration: true,
  passwordMinimumLength: 8,
  passwordRequireDigit: true,
  passwordRequireUppercase: true,
  confirm: true
)

// 2. Find company-level auth provider credentials
wildwood_list_available_providers()
// Returns: authentication.providers[] with { id, providerType, hasCredentials }

// 3. Enable a social login provider
wildwood_manage_auth_providers(
  providerType: "Google",
  isEnabled: true,
  displayName: "Sign in with Google",
  buttonText: "Continue with Google",
  companyAuthProviderId: "<id-from-step-2>",
  confirm: true
)

Set Up Messaging

wildwood_manage_messaging_config(
  isMessagingEnabled: true,
  allowFileAttachments: true,
  allowImageAttachments: true,
  maxFileSize: 10485760,
  maxMessageLength: 5000,
  allowPrivateMessages: true,
  allowGroupMessages: true,
  showReadReceipts: true,
  showTypingIndicators: true,
  confirm: true
)

Set Up Payments

// 1. Configure payment settings (public fields)
wildwood_manage_payment_config(
  isPaymentEnabled: true,
  defaultCurrency: "usd",
  stripePublishableKey: "pk_live_...",
  allowSavedPaymentMethods: true,
  enablePaymentReceipts: true,
  confirm: true
)

// 2. Set secret keys (encrypted, separate tool for safety)
wildwood_set_payment_secrets(
  stripeSecretKey: "sk_live_...",
  stripeWebhookSecret: "whsec_...",
  confirm: true
)

Set Up Theme

wildwood_manage_theme(
  themeName: "My Brand",
  primaryColor: "#3B82F6",
  secondaryColor: "#1E40AF",
  accentColor: "#F59E0B",
  backgroundColor: "#FFFFFF",
  textColor: "#1F2937",
  fontFamily: "Inter, sans-serif",
  isDarkMode: false,
  borderRadius: "8px",
  confirm: true
)

Set Up CAPTCHA

wildwood_manage_captcha_config(
  isEnabled: true,
  providerType: "GoogleReCaptcha",
  siteKey: "6Le...",
  secretKey: "6Le...",
  theme: "light",
  requireForLogin: false,
  requireForRegistration: true,
  confirm: true
)

Set Up Subscription Tiers

// 1. Create a pricing model
wildwood_manage_pricing_model(
  name: "Monthly Standard",
  billingFrequency: "Monthly",
  price: 29.99,
  isActive: true,
  trialDays: 14,
  confirm: true
)

// 2. Create a tier
wildwood_manage_tier(
  name: "Professional",
  description: "For growing teams",
  isDefault: false,
  isFreeTier: false,
  status: "Active",
  confirm: true
)

// 3. Add features to the tier
wildwood_manage_tier_feature(
  tierId: "<tier-id>",
  featureCode: "AI_CHAT",
  displayName: "AI Chat",
  isEnabled: true,
  category: "AI",
  confirm: true
)

// 4. Add usage limits
wildwood_manage_tier_limit(
  tierId: "<tier-id>",
  limitCode: "AI_REQUESTS",
  displayName: "AI Requests",
  maxValue: 1000,
  limitType: "Monthly",
  enforceHardLimit: true,
  confirm: true
)

// 5. Associate pricing
wildwood_manage_tier_pricing(
  tierId: "<tier-id>",
  pricingModelId: "<pricing-model-id>",
  confirm: true
)

Set Up Subscriptions

wildwood_manage_subscription_config(
  isSubscriptionEnabled: true,
  allowTrialPeriod: true,
  defaultTrialDays: 14,
  allowPlanUpgrades: true,
  allowPlanDowngrades: true,
  confirm: true
)

Review and Restore Configurations

// List all auto-saved snapshots
wildwood_list_config_snapshots()

// Filter by entity type
wildwood_list_config_snapshots(entityType: "AppAIConfiguration")

// Restore from a snapshot
wildwood_restore_config_snapshot(snapshotId: "<id>", confirm: true)

What Can vs Cannot Be Configured via MCP

Safety & Security

• CompanyAdmin only — User and Admin roles cannot access MCP tools
• OAuth 2.1 + PKCE — Browser-based login, no credentials in the MCP protocol
• No secrets exposed — Tools return hasApiKey: true/false, never actual keys or passwords
• Tenant isolation — All queries scoped by AppId and CompanyId from the JWT
• Auto-snapshots — Every write operation saves the current state before modifying
• Audit logging — All tool calls logged to AppMCPToolCallLog with timing and results
• Input validation — URL schemes, string lengths, numeric ranges, and enum values validated
• Per-tool admin control — Platform admins can disable individual tools without redeployment
• Confirmation required — Write tools require explicit confirm: true
• Rate limiting — OAuth endpoints are rate-limited to prevent abuse

Claude Code Plugin

The recommended way to connect to the MCP server is via the WildwoodComponents.Claude plugin for Claude Code:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/WildwoodWorks/WildwoodComponents.Claude/master/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/WildwoodWorks/WildwoodComponents.Claude/master/install.ps1 | iex

# MCP server only (no skills)
claude mcp add --transport http wildwood https://api.wildwoodworks.io/mcp

This provides:

• MCP connection — Pre-configured to connect to api.wildwoodworks.io/mcp
• /wildwood — Single command for setup, integration, deployment, hosting, databases, and status

Configuration

MCP server behavior is configurable in appsettings.json:

{
  "MCP": {
    "Snapshots": {
      "CleanupIntervalHours": 6,
      "RetentionDays": 30,
      "MaxPerEntity": 10
    },
    "OAuth": {
      "CleanupIntervalHours": 4
    }
  },
  "Security": {
    "RateLimiting": {
      "MCPOAuthPermitLimit": 20
    }
  }
}