MCP Setup Guide

Connect Claude Desktop, Claude.ai, Claude Code, Cursor, or any MCP client to manage your Willform deployments via AI.

What is MCP?

The Model Context Protocol (MCP) allows AI assistants to interact with external tools and services. Willform exposes an MCP server that lets you create namespaces, deploy containers, manage resources, and monitor logs — all through natural language.

Authentication Methods

Willform MCP supports two authentication methods depending on your client:

Method	Clients	How It Works
OAuth 2.0	Claude Desktop, Claude.ai	Automatic — just enter the server URL. Phone OTP login via browser.
API Key	Claude Code, Cursor, custom clients	Manual — create a key in Dashboard, add to config file.

Option A: OAuth Clients (No API Key Needed)

Claude Desktop and Claude.ai support OAuth 2.0 auto-discovery. You only need to provide the MCP server URL — authentication is handled automatically through a browser-based phone verification flow.

Claude Desktop

Open Settings (gear icon) → Developer → Edit Config
Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "willform": {
      "type": "http",
      "url": "https://agent.willform.ai/api/mcp"
    }
  }
}

Restart Claude Desktop.
On first use, a browser window opens for authentication. Enter your phone number and verify with the OTP code.
Approve the mcp:tools permission. You're connected — tokens refresh automatically.

Claude.ai (Web)

Requires a paid plan: MCP Integrations on Claude.ai are available on Max and Pro plans only.

Go to claude.ai/settings/connectors (or Settings → Connectors)
Click + Add custom connector. Enter a name (e.g. Willform) and the server URL:

https://agent.willform.ai/api/mcp

Complete the phone verification in the popup window and approve the mcp:tools permission.
The Willform integration now appears in your chat. Start a new conversation and the MCP tools are available.

How OAuth works behind the scenes: The client discovers our authorization server via /.well-known/oauth-authorization-server, registers itself (DCR), then runs a PKCE S256 authorization code flow. Access tokens expire in 1 hour and refresh tokens last 30 days with automatic rotation.

Option B: API Key Clients

For developer tools that support custom headers, use an API key directly.

Step 1: Get Your API Key

Navigate to Dashboard → API Keys and create a new key. Copy the key — it starts with wf_sk_ and will only be shown once.

Step 2: Configure Your Client

Claude Code (CLI)

Create .mcp.json in your project root:

{
  "mcpServers": {
    "willform": {
      "type": "http",
      "url": "https://agent.willform.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "willform": {
      "type": "http",
      "url": "https://agent.willform.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Code Plugin (Alternative)

If you use Claude Code, you can also install the Willform plugin for slash commands instead of raw MCP. It provides interactive commands like /wf-deploy, /wf-status, /wf-monitor, and more.

Install from the marketplace:

/install-plugin willform-ai/willform-plugins

View on GitHub →

Verify Connection

After configuring any client, ask your AI assistant:

"List my Willform namespaces"

The assistant should use the namespace_list tool to show your namespaces. If you see a list (even empty), the connection is working.

Troubleshooting

Claude Desktop: "Failed to connect"

Make sure you restarted Claude Desktop after editing the config. Check that the URL is exactly https://agent.willform.ai/api/mcp.

OAuth login popup doesn't appear

Your browser may be blocking popups. Allow popups for agent.willform.ai and retry.

API key returns 401

Verify your key starts with wf_sk_. Keys are scoped to your account — make sure you're using a key from the correct account.

Available Tools

Willform exposes 34 tools across 6 categories.

Namespace Management

Tool	Description
namespace_create	Create a new namespace with CPU and memory allocation
namespace_list	List all your namespaces
namespace_get	Get details of a specific namespace
namespace_update	Update namespace name or resource allocation
namespace_delete	Delete a namespace and all its resources

Registry Management

Tool	Description
registry_credentials	Generate Docker registry push credentials for a namespace
registry_usage	Check container image storage usage and quota

Deployment Management

Tool	Description
chart_list	List available chart types (web, database, queue, cache, storage, worker, cronjob, job, static-site)
deploy_preflight	Pre-deployment validation (quota, balance, image checks)
deploy_create	Deploy a container image to a namespace
deploy_status	Check deployment health and status
deploy_list	List all deployments in a namespace
deploy_stop	Stop a running deployment (scales to 0)
deploy_restart	Restart a stopped deployment
deploy_delete	Delete a deployment and its resources
deploy_logs	Retrieve recent container logs from a deployment
deploy_diagnose	Diagnose deployment issues with events and pod status
deploy_update_env	Update environment variables for a deployment
deploy_scale	Scale deployment replicas up or down
deploy_events	View Kubernetes events for a deployment
deploy_expose	Expose a deployment externally with a default subdomain
deploy_unexpose	Remove external access from a deployment
deploy_metrics	Get resource usage metrics for a deployment

Credits & Billing

Tool	Description
credits_balance	Check your credit balance and burn rate
credits_deposit_info	Get USDC deposit address and instructions
credits_deposit_verify	Verify an on-chain USDC deposit

Domain Management

Tool	Description
domain_add	Add a custom domain to a deployment
domain_remove	Remove a custom domain from a deployment
domain_verify	Check domain DNS verification status

Willy Agent

Tool	Description
agent_status	Check Willy agent health and status
agent_invoke	Invoke a specific Willy agent tool
agent_chat	Talk to Willy — natural language conversation with your AI deployment assistant
ask_willy	Ask Willy — get platform guidance and deployment help