MCP Setup Guide

Connect Claude Desktop, Claude.ai, Claude Code, Cursor, or any MCP client to manage your Willform agents 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 AI agents on dedicated VMs, manage resources, and monitor status — 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://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://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://willform.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "willform": {
      "type": "http",
      "url": "https://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://willform.ai/api/mcp.

OAuth login popup doesn't appear

Your browser may be blocking popups. Allow popups for 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 tools across 6 categories for managing AI agents, namespaces, credits, and more.

Namespace Management

Tool	Description
namespace_create	Create a new namespace for organizing agents
namespace_get	Get details of a specific namespace
namespace_list	List all your namespaces
namespace_update	Update namespace name
namespace_delete	Delete a namespace and all its resources
namespace_usage	Check namespace resource usage

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

Agent Management

Tool	Description
agent_create	Create a new managed AI agent
agent_list	List all your managed agents
agent_get	Get details of a specific agent
agent_update	Update agent name, persona, or configuration
agent_delete	Delete an agent permanently (stops VM, removes secrets)
agent_deploy	Deploy an agent as a dedicated VM
agent_undeploy	Stop a running agent VM (preserves config for re-deploy)
agent_status	Check agent health and VM status
agent_invoke	Invoke a specific agent tool
agent_chat	Talk to your agent — natural language conversation
agent_recover	Recover a failed agent
agent_configure	Configure agent settings (persona, tool pack, MCP servers)
agent_add_mcp_server	Add an external MCP server to an agent
agent_remove_mcp_server	Remove an MCP server from an agent
agent_upload_document	Upload a document to the agent knowledge base
agent_list_documents	List documents in the agent knowledge base
agent_remove_document	Remove a document from the agent knowledge base
agent_search_knowledge	Search the agent knowledge base (vector RAG)
agent_propose_tool	Propose a new tool for the agent (self-improvement)
agent_propose_memory	Propose a memory entry for the agent (self-improvement)
agent_list_proposals	List pending self-improvement proposals
agent_approve_proposal	Approve a self-improvement proposal
agent_register_identity	Temporarily unavailable during the agent_instances migration
agent_identity_status	Check whether ERC-8004 identity operations are currently available
agent_identity_update	Temporarily unavailable during the agent_instances migration
agent_deactivate_identity	Temporarily unavailable during the agent_instances migration

Budget Policies

Tool	Description
budget_policy_create	Create a budget policy for an agent (daily limits, domain allowlist)
budget_policy_list	List budget policies and today's spend
budget_policy_update	Update an existing budget policy
budget_policy_delete	Delete a budget policy (falls back to defaults)

x402 Payments

Tool	Description
x402_proxy_call	Make an outbound HTTP request through the x402 budget proxy
x402_transactions	List x402 external payment transaction history

Utility & Channels

Tool	Description
toolpack_list	List available tool packs for agents
preset_list	List available persona presets for agents
design_agent_chat	Design an AI agent through multi-turn conversation
channel_add	Add a notification channel (Slack, Discord, etc.)
channel_list	List configured notification channels
channel_remove	Remove a notification channel
ask_willy	Ask Willy — get platform guidance and help